Jailbreak Troubleshooting¶

Solutions to common issues during the jailbreak process.

OpenOCD Issues¶

"JTAG scan chain interrogation failed"¶

Symptoms: OpenOCD can't detect the device

Solutions:

Check wiring - Verify all 5 connections match the pin mapping
Check device power - Smartap must be powered on
Check cable quality - Try shorter or better quality jumper wires
Reduce speed - Add to sysfsgpio-smartap.cfg:
```
adapter speed 50
```

Check GPIO access - Ensure OpenOCD can access GPIO:

sudo usermod -aG gpio $USER
# Then log out and back in

"Permission denied" errors¶

Symptoms: OpenOCD fails to access GPIO pins

Solutions:

# Option 1: Add user to gpio group (preferred)
sudo usermod -aG gpio $USER
newgrp gpio  # Apply without logout

# Option 2: Run OpenOCD as root (not recommended)
sudo openocd -f ...

OpenOCD loses connection¶

Symptoms: OpenOCD was working, then stops responding

Causes: - Device watchdog timer reset the device - Power interruption - JTAG cable came loose

Solutions:

Power cycle the Smartap device
Restart OpenOCD immediately after
Run commands quickly before watchdog kicks in

"Error: cc32xx.cpu: target not halted"¶

Symptoms: GDB operations fail with "target not halted"

Solutions:

# Restart OpenOCD
# The cc3200-complete.cfg should halt the device automatically
# If not, manually halt via telnet:
telnet localhost 4444
> halt
> exit

GDB Issues¶

"Connection refused" to OpenOCD¶

Symptoms: smartap-jtag can't connect to OpenOCD

Solutions:

Check OpenOCD is running:
```
ps aux | grep openocd
```
Check binding: For remote connections, OpenOCD needs:
```
openocd ... -c "bindto 0.0.0.0"
```

Check firewall:

# On Raspberry Pi
sudo ufw allow 3333/tcp

Check correct host:

smartap-jtag verify-setup --openocd-host <pi-ip-address>

"arm-none-eabi-gdb: command not found"¶

Symptoms: GDB binary isn't found

Solutions:

# Option 1: Install ARM toolchain
sudo apt install gcc-arm-none-eabi

# Option 2: Use gdb-multiarch
sudo apt install gdb-multiarch
smartap-jtag --gdb-path gdb-multiarch verify-setup

GDB timeout errors¶

Symptoms: Operations fail with "timeout" or "no response"

Solutions:

Increase timeout:

smartap-jtag --timeout 10m inject-certs

Check device hasn't reset - Restart OpenOCD and try again
Run with verbose:
```
smartap-jtag --verbose inject-certs
```

Firmware Detection Issues¶

"Firmware unknown" / Low confidence¶

Symptoms: detect-firmware shows <100% confidence

This is expected for unrecognized firmware versions.

Solutions:

Submit a memory dump - See Unrecognized Firmware
Check for newer smartap-jtag release - Your version may have been added
Analyze the firmware yourself - See the Firmware Analysis Guide if you're comfortable with reverse engineering

Detection succeeds but inject-certs fails¶

Symptoms: Firmware detected at 100% but injection fails

Solutions:

Fresh device boot - Power cycle and try immediately
Check OpenOCD still connected - May need to restart
Run with verbose:
```
smartap-jtag --verbose inject-certs
```

Certificate Injection Issues¶

"Failed to delete old certificate"¶

Symptoms: Injection fails at "Deleting old certificate" step

This might be OK - If the certificate doesn't exist yet, deletion will fail but injection can continue.

If injection still fails:

Verify firmware detection showed 100% confidence
Power cycle device and try again
Check verbose output for specific error

"Failed to create new file"¶

Symptoms: Injection fails at "Creating new file" step

Possible causes:

File system corruption
Wrong function addresses (firmware mismatch)
Device reset during operation

Solutions:

Verify firmware detection was 100% confident

Try reading a file first to test filesystem:

smartap-jtag read-file --remote-file /cert/129.der --output test.der

Power cycle and retry

"Bytes written mismatch"¶

Symptoms: Injection reports wrong number of bytes written

Solutions:

Certificate may have written partially
Power cycle and retry injection
The certificate file may be corrupted - re-download smartap-jtag

Device unresponsive after injection¶

Symptoms: Device LEDs off or stuck after injection

Don't panic! The injection process resumes the device, but:

Wait 30 seconds - Device may be rebooting
Power cycle - Turn off and on

Check certificate - Use read-file to verify:

smartap-jtag read-file --remote-file /cert/129.der --output check.der
ls -la check.der  # Should be ~1500 bytes

Device Issues¶

Device resets during operation¶

Symptoms: Operations start but device resets mid-way

Cause: CC3200 watchdog timer

Solutions:

Work quickly - Start OpenOCD right after device power-on
Fresh boot - Power cycle before important operations
Use the right config - cc3200-complete.cfg has watchdog handling

Device won't boot after modification¶

Symptoms: Device doesn't start normally after injection

Solutions:

Wait - Give it 30-60 seconds
Power cycle - Full off/on
Re-inject - The certificate can be overwritten:
```
smartap-jtag inject-certs
```

Read the certificate - Verify what was written:

smartap-jtag read-file --remote-file /cert/129.der --output check.der
file check.der  # Should show DER certificate

LED behavior is wrong¶

Symptoms: LEDs don't match expected states

LED states to know:

Yellow flashing = Pairing mode
Normal operation = Device working
No LEDs = No power or crashed

After injection, device should return to normal operation.

Network Issues¶

Can't connect to Pi from laptop¶

Symptoms: smartap-jtag can't reach OpenOCD on remote Pi

Solutions:

Check Pi IP: hostname -I on the Pi
Check port open: nc -zv <pi-ip> 3333
Check OpenOCD binding: Must have -c "bindto 0.0.0.0"
Check firewall: Both on Pi and your laptop

Memory dump incomplete¶

Symptoms: Dump file is smaller than 256KB

Solutions:

Device may have reset during dump
Power cycle and retry immediately

Increase timeout:

smartap-jtag --timeout 10m dump-memory --output firmware.bin

Still Stuck?¶

If these solutions don't help:

Check GitHub Issues - Someone may have had the same problem: github.com/muurk/smartap/issues

Run with verbose mode and include the output:

smartap-jtag --verbose <command> 2>&1 | tee debug.log

Open a new issue with:
What you tried
Complete command output
Device model (if known)
Raspberry Pi model and OS version

Previous: Unrecognized Firmware Back to Jailbreak Overview