185 lines
4.2 KiB
Markdown
185 lines
4.2 KiB
Markdown
# Troubleshooting
|
||
|
||
This page is a practical checklist for common failure points.
|
||
|
||
If something fails, also see:
|
||
|
||
- Installer internals: [[01 - Installer (How It Works)]]
|
||
- Windows specifics: [[05 - Windows Support]]
|
||
- CLI flags: [[03 - CLI Arguments]]
|
||
- Updater internals: [[06 - Updater (How It Works)]]
|
||
|
||
---
|
||
|
||
## 1) Jibo not found / can’t talk to APX (RCM)
|
||
|
||
### Symptoms
|
||
|
||
- Tool prints “Jibo not found in RCM mode”
|
||
- `EMMC_READ` / `EMMC_WRITE` fails immediately
|
||
- On Linux, `lsusb` does not show `0955:7740`
|
||
|
||
### Checklist
|
||
|
||
- Use a known-good **data** micro-USB cable (charge-only cables are common).
|
||
- Ensure the robot is actually in RCM:
|
||
- hold RCM button
|
||
- press reset/power
|
||
- release when you get red LED and no normal boot
|
||
- Try a different USB port (avoid hubs).
|
||
|
||
### Linux permissions
|
||
|
||
- If it works only with `sudo`, consider installing the udev rule:
|
||
- see `../99-jibo-rcm.rules`
|
||
|
||
### Windows driver
|
||
|
||
- Install WinUSB for the “APX” device using Zadig.
|
||
- Run the tool as Administrator.
|
||
|
||
---
|
||
|
||
## 2) ShofEL build issues
|
||
|
||
### Symptoms
|
||
|
||
- `make` fails in `../Shofel/`
|
||
- Tool complains about missing payload binaries (like `emmc_server.bin`)
|
||
|
||
### Checklist
|
||
|
||
- You need normal build tools: `gcc`, `make`, libusb dev headers.
|
||
- If payload `.bin` files are missing you also need the ARM toolchain:
|
||
- `arm-none-eabi-gcc`
|
||
|
||
Notes:
|
||
|
||
- The tool’s `--rebuild-shofel` forces a rebuild.
|
||
|
||
---
|
||
|
||
## 3) Dump is slow / crashes near the end
|
||
|
||
### Full dump mode
|
||
|
||
- Full dump reads ~15GB; multi-hour runtime is normal.
|
||
- If it fails at ~99%, you often still have most of the content.
|
||
|
||
### Use fast mode instead
|
||
|
||
If your only goal is enabling SSH/dev mode, you can usually skip the full dump:
|
||
|
||
- `--mode-json-only`
|
||
|
||
This reads only GPT + `/var` (~500MB) and writes back only what changed.
|
||
|
||
---
|
||
|
||
## 4) mode.json edit fails
|
||
|
||
### Why this happens
|
||
|
||
`/var` is an ext filesystem image. Editing a file *inside* it is easiest on Linux (mount) and harder on Windows.
|
||
|
||
### What the installer tries (in order)
|
||
|
||
- Linux: mount loop device and edit `/var/jibo/mode.json`
|
||
- Any OS: try `debugfs` if installed
|
||
- Fallback: raw byte-pattern overwrite
|
||
|
||
### Fixes
|
||
|
||
- On Windows, install `debugfs` via MSYS2:
|
||
- package: `e2fsprogs`
|
||
- If raw patching fails:
|
||
- it likely can’t find the exact JSON string pattern, or it would need to grow the data region.
|
||
- installing `debugfs` is usually the right fix.
|
||
|
||
---
|
||
|
||
## 5) Fast mode patch-write writes too much (or falls back)
|
||
|
||
### What patch-write is
|
||
|
||
In `--mode-json-only` the tool tries to compute which 512-byte sectors changed between:
|
||
|
||
- `var_partition_original.bin`
|
||
- `var_partition.bin`
|
||
|
||
Then it writes only those sector ranges.
|
||
|
||
### When it falls back to full `/var` write
|
||
|
||
It will write the entire partition if:
|
||
|
||
- the images differ in size (shouldn’t happen in normal flows)
|
||
- too many sectors changed
|
||
- too many disjoint ranges were detected
|
||
|
||
If your edit method rewrites a lot of blocks (filesystem reallocation), you may see a full write anyway.
|
||
|
||
To force full write explicitly:
|
||
|
||
- `--full-var-write`
|
||
|
||
---
|
||
|
||
## 6) Verify step fails (hash mismatch)
|
||
|
||
### Meaning
|
||
|
||
- The read-back does not match the local file.
|
||
|
||
### Common causes
|
||
|
||
- Unstable USB connection/cable
|
||
- Jibo dropped out of RCM mid-process
|
||
- Write succeeded but read-back got corrupted
|
||
|
||
### What to do
|
||
|
||
- Re-enter RCM and re-run with `--mode-json-only --full-var-write` (simplest “make it match” path).
|
||
- Consider disabling verify to proceed if you’re confident the write worked:
|
||
- `--no-verify`
|
||
|
||
---
|
||
|
||
## 7) SSH works but updater fails
|
||
|
||
### Connection failures
|
||
|
||
- Check Jibo is booted to the checkmark and reachable:
|
||
- port 22 open
|
||
- `root` / `jibo`
|
||
|
||
### “Rootfs is read-only” issues
|
||
|
||
Updater tries to remount `/` read-write:
|
||
|
||
- `mount -o remount,rw /`
|
||
|
||
If that fails, the updater will refuse to upload.
|
||
|
||
### Archive layout issues
|
||
|
||
If the updater cannot find `build/` automatically:
|
||
|
||
- pass `--build-path` to point at it inside the extracted tree
|
||
|
||
### Dry-run
|
||
|
||
To debug without uploading files:
|
||
|
||
- `--dry-run`
|
||
|
||
---
|
||
|
||
## 8) Where to look for logs / outputs
|
||
|
||
- Installer work files: `../jibo_work/`
|
||
- Updater cached downloads/extraction: `../jibo_work/updates/`
|
||
- Updater state tracking: `../jibo_work/update_state.json`
|
||
|
||
See: [[07 - Working Directory + State Files]]
|