OMG More warnings
This commit is contained in:
184
Jibo Tools & Mod Installer/08 - Troubleshooting.md
Normal file
184
Jibo Tools & Mod Installer/08 - Troubleshooting.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# 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]]
|
||||
Reference in New Issue
Block a user