diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index d494dbd..e54d11d 100755 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -27,12 +27,12 @@ "state": { "type": "markdown", "state": { - "file": "index.md", + "file": "Jibo Tools & Mod Installer/08 - Troubleshooting.md", "mode": "source", "source": false }, "icon": "lucide-file", - "title": "index" + "title": "08 - Troubleshooting" } } ], @@ -214,10 +214,19 @@ }, "active": "0806f039bf8a940e", "lastOpenFiles": [ + "Jibo Tools & Mod Installer/07 - Working Directory + State Files.md", + "Jibo Tools & Mod Installer/06 - Updater (How It Works).md", + "Jibo Tools & Mod Installer/05 - Windows Support.md", + "Jibo Tools & Mod Installer/04 - GUI (How It Works).md", + "Assets/JiboToolsScreen.png", + "Assets/Screenshot_20260317_235807.png", + "Jibo Tools & Mod Installer/03 - CLI Arguments.md", + "Jibo Tools & Mod Installer/01 - Installer (How It Works).md", + "Getting Started/Modifying the Firmware/1. Get your environment ready!.md", + "Jibo Tools & Mod Installer/00 - Index.md", + "index.md", "Documentation/Useful Items List.md", - "obsidian/06 - Updater (How It Works).md", - "obsidian/02 - Mapping to guide.md", - "obsidian/00 - Index.md", + "Jibo Tools & Mod Installer/02 - Mapping to guide.md", "Getting Started/Welcome to the Jibo Revival Project.md", "Documentation/AtDev - New Firewall script.md", "Documentation/Networking/Network Profiling & Traffic Analysis.md", @@ -232,21 +241,14 @@ "Getting Started/Developing for Jibo/About - Jibo SDK V2!.md", "Getting Started/Developing for Jibo/Introduction to the New Jibo SDK.md", "Documentation/The be skill/Assets/Menu Buttons/ButtonSetup.png", - "Attack Vectors/Hardware and Tegra Exploitation.md", + "About UART Connection/Attack Vectors (Depricated)/Hardware and Tegra Exploitation.md", "Dictionary/ShofEL2 - Fusée Gelée Exploit.md", "Assets/Jibo RCM.jpg", - "index.md", "About UART Connection", - "obsidian/08 - Troubleshooting.md", - "obsidian/07 - Working Directory + State Files.md", - "obsidian/05 - Windows Support.md", - "obsidian/04 - GUI (How It Works).md", - "obsidian/03 - CLI Arguments.md", - "obsidian/01 - Installer (How It Works).md", - "obsidian", + "Jibo Tools & Mod Installer/08 - Troubleshooting.md", + "Jibo Tools & Mod Installer", "Documentation/The be skill/Assets/Menu Buttons/ButtonSetup.kra", "Documentation/The be skill/Assets/Menu Buttons", - "Getting Started/Modifying the Firmware/1. Get your environment ready!.md", "Discoveries/Jibo Workshop HRI 2024.md", "Getting Started/Developing for Jibo", "Getting Started/Modifying the Firmware", diff --git a/Attack Vectors/Hardware and Tegra Exploitation.md b/About UART Connection/Attack Vectors (Depricated)/Hardware and Tegra Exploitation.md similarity index 100% rename from Attack Vectors/Hardware and Tegra Exploitation.md rename to About UART Connection/Attack Vectors (Depricated)/Hardware and Tegra Exploitation.md diff --git a/Attack Vectors/Validated memory adresses.md b/About UART Connection/Attack Vectors (Depricated)/Validated memory adresses.md similarity index 100% rename from Attack Vectors/Validated memory adresses.md rename to About UART Connection/Attack Vectors (Depricated)/Validated memory adresses.md diff --git a/Assets/JiboToolsScreen.png b/Assets/JiboToolsScreen.png new file mode 100644 index 0000000..b591105 Binary files /dev/null and b/Assets/JiboToolsScreen.png differ diff --git a/Assets/Screenshot_20260317_235807.png b/Assets/Screenshot_20260317_235807.png new file mode 100644 index 0000000..6a6f2a3 Binary files /dev/null and b/Assets/Screenshot_20260317_235807.png differ diff --git a/ESML/ESML-SDK.pdf b/Documentation/ESML/ESML-SDK.pdf similarity index 100% rename from ESML/ESML-SDK.pdf rename to Documentation/ESML/ESML-SDK.pdf diff --git a/ESML/Jibo-Animations.pdf b/Documentation/ESML/Jibo-Animations.pdf similarity index 100% rename from ESML/Jibo-Animations.pdf rename to Documentation/ESML/Jibo-Animations.pdf diff --git a/Getting Started/Modifying the Firmware/1. Get your environment ready!.md b/Getting Started/Modifying the Firmware/1. Get your environment ready!.md index af3c29e..653102d 100755 --- a/Getting Started/Modifying the Firmware/1. Get your environment ready!.md +++ b/Getting Started/Modifying the Firmware/1. Get your environment ready!.md @@ -21,6 +21,12 @@ Before starting ANY work , lets get you up to speed with the enviroment and what 5. An the mindset of (everything will be fine!) - - - + +>[!DANGER] +> # Part 0 | Note your jibos IP Down +> Make sure you have your jibos IP adress , so you wont have to redo 4 hours of flashing just because you forgot your ip + +- - - # Part 1 | Connecting your jibo So first , go ahead and plug jibo in to your host device that you are going to dump the firmware into using your usb cable diff --git a/Jibo Tools & Mod Installer/00 - Index.md b/Jibo Tools & Mod Installer/00 - Index.md new file mode 100644 index 0000000..cc01dbe --- /dev/null +++ b/Jibo Tools & Mod Installer/00 - Index.md @@ -0,0 +1,14 @@ +# JiboAutoModv2 +This folder contains internal documentation for how this repo works. + +## Start here + +- [[01 - Installer (How It Works)]] +- [[02 - Mapping to guide]] +- [[03 - CLI Arguments]] +- [[04 - GUI (How It Works)]] +- [[05 - Windows Support]] +- [[06 - Updater (How It Works)]] +- [[07 - Working Directory + State Files]] +- [[08 - Troubleshooting]] + diff --git a/Jibo Tools & Mod Installer/01 - Installer (How It Works).md b/Jibo Tools & Mod Installer/01 - Installer (How It Works).md new file mode 100644 index 0000000..e0a44b9 --- /dev/null +++ b/Jibo Tools & Mod Installer/01 - Installer (How It Works).md @@ -0,0 +1,88 @@ +# Installer (How It Works) + +The repo has a “CLI installer” and an optional GUI wrapper that launches the same Python tools. + +The basic mod logic lives in `../jibo_automod.py` + +## What the installer actually does + +The tool is automating the exact same high-level steps you do manually in [[1. Get your environment ready!]] + +1. Build ShofEL (`shofel2_t124`) if it isn’t built yet. +2. Put the Jibo into NVIDIA Tegra RCM mode (USB device `0955:7740`). +3. Read eMMC contents using `EMMC_READ`. +4. Find the `/var` partition (usually GPT partition #5, ~500MB). +5. Modify `/var/jibo/mode.json` from `normal` to `int-developer`. +6. Write the modified `/var` partition back using `EMMC_WRITE`. +7. Optionally verify by reading back and comparing hashes. + +After that, Jibo boots to a checkmark and SSH should work: + +- `ssh root@` +- password: `jibo` + +## Launchers (what runs what) + +### Linux launcher + +- `../jibo_automod.sh` is a Bash launcher +- It does a light dependency check, then prompts: + - CLI installer (recommended) + - GUI installer (experimental) + +In CLI mode it runs: + +- `python3 ../jibo_automod.py ` + +In GUI mode it: + +- creates `../.venv/` if missing +- installs GUI deps from `../JiboTools/JiboTools/requirements.txt` +- launches `../JiboTools/JiboTools/main_panel.py` + +### Windows launcher + +- `../jibo_automod.bat` just runs `python ../jibo_automod.py ` +- It warns if you’re not running as Administrator. + +## How it edits mode.json (important detail) + +`../jibo_automod.py` tries multiple strategies to edit `mode.json` inside the `/var` filesystem image: + +1. **Linux mount (preferred on Linux)** + - Mounts `var_partition.bin` as a loop device. + - Edits `jibo/mode.json` (or a couple fallback paths). + - Unmounts. + +2. **debugfs (preferred for Windows if available)** + - Uses `debugfs` from `e2fsprogs` to read and rewrite the file inside the ext filesystem image without mounting. + - This is the safest option on Windows if you can install it (see [[05 - Windows Support]]). + +3. **Raw in-place patch (last resort)** + - Searches the binary image for known JSON string patterns like `{"mode": "normal"}`. + - Overwrites bytes in-place without changing file size. + - **If the replacement would require growing the data and there is no safe padding, it refuses.** + +>[!note] +Because this is a real filesystem image, the mount/debugfs approaches are more reliable than raw patching. + +## Installer modes + +The CLI tool supports three main workflows: + +- **Full mod** (default): full eMMC dump, then extract/modify/write `/var`. +- **Dump-only**: only dumps eMMC (no modifications). +- **Mode-json-only** (“fast mode”): reads only GPT + `/var` and patch-writes only changed sectors. + +Details and flags: [[03 - CLI Arguments]] + +## Where output goes + +By default, the tool uses `../jibo_work/` for working files: + +- `jibo_full_dump.bin` (full mode) +- `gpt_dump.bin` (fast mode) +- `var_partition_original.bin` / `var_partition.bin` +- backups, verification reads, and patch chunks + +More: [[07 - Working Directory + State Files]] diff --git a/Jibo Tools & Mod Installer/02 - Mapping to guide.md b/Jibo Tools & Mod Installer/02 - Mapping to guide.md new file mode 100644 index 0000000..545b1de --- /dev/null +++ b/Jibo Tools & Mod Installer/02 - Mapping to guide.md @@ -0,0 +1,104 @@ +# Mapping to guide.md + +This page explains how the automated installer in `../jibo_automod.py` relates to the manual steps in `../guide.md`. + +## Big picture + +`../guide.md` is the “do it by hand” method. + +`../jibo_automod.py` is the “do the same steps, but scripted” method. + +If something goes wrong in automation, the guide is still valuable because it explains: + +- how to confirm RCM mode +- how to interpret partition layouts +- what `/var/jibo/mode.json` does conceptually + +## Step-by-step mapping + +### Part 1 (Connecting / RCM) + +Guide: +- Enter RCM mode and confirm with `lsusb` showing NVIDIA APX (`0955:7740`). + +Tool: +- `detect_jibo_rcm()` tries `lsusb` on Linux. +- Falls back to scanning `/sys/bus/usb/devices` if `lsusb` is missing. +- On Windows it can’t reliably detect in the same way, so it prints guidance and proceeds. + +Related: [[05 - Windows Support]] + +### Part 2 (Build ShofEL) + +Guide: +- Clone/build ShofEL manually with `make`. + +Tool: +- `build_shofel()` runs `make` inside `../Shofel/`. +- If payload `.bin` files are missing, it requires the ARM toolchain (`arm-none-eabi-gcc`). + +### Part 3 (Dump eMMC) + +Guide: +- Run: `shofel2_t124 EMMC_READ 0x0 0x1D60000 full_jibo_dump.bin` + +Tool: +- Default full workflow calls `dump_emmc()` which runs the same command. +- Fast workflow (`--mode-json-only`) does *not* dump full eMMC; it only reads GPT + `/var`. + +### Part 4 (Identify and extract /var) + +Guide: +- Run `fdisk -l dump.bin` +- Find partition 5, compute start/count, then `dd` out `var_partition.bin`. + +Tool: +- Parses GPT directly (`parse_gpt_partitions()`), with an `fdisk` fallback on Linux. +- Then extracts bytes by seeking directly inside the dump (no `dd` needed). +- Uses heuristics to identify `/var` (partition #5 and roughly 400–600MB). + +### Part 4.2 (Edit mode.json) + +Guide: +- Mount loop device and edit `jibo/mode.json`. + +Tool: +- On Linux: prefers a loop mount and edits `mode.json`. +- On Windows: prefers `debugfs` if installed. +- Raw in-place patch is last resort. + +Related: [[01 - Installer (How It Works)]] + +### Part 5 (Write /var back) + +Guide: +- Convert start sector to hex and run `EMMC_WRITE var_partition.bin`. + +Tool: +- Always uses the GPT-derived start sector (so you don’t manually convert it). +- In fast mode, it can patch-write only changed sectors instead of writing the full 500MB. + +### Part 6 (Verify) + +Guide: +- Read back and compare hashes. + +Tool: +- Optional verify step reads back the written range and compares MD5. + +## Why the automated tool differs from the guide + +The guide is intentionally explicit and teaches the mental model. + +The tool tries to reduce “math + manual disk ops” by: + +- parsing GPT automatically +- extracting partitions programmatically +- handling mount/debugfs edits +- optionally patch-writing only changed sectors + +## When to fall back to the guide + +- If your partition layout differs enough that `/var` isn’t partition 5. +- If the filesystem inside `/var` is corrupted and mount/debugfs can’t read it. +- If you want a full backup regardless of speed (the guide defaults to full dump). diff --git a/Jibo Tools & Mod Installer/03 - CLI Arguments.md b/Jibo Tools & Mod Installer/03 - CLI Arguments.md new file mode 100644 index 0000000..0cf09bd --- /dev/null +++ b/Jibo Tools & Mod Installer/03 - CLI Arguments.md @@ -0,0 +1,147 @@ +# CLI Arguments + +This page documents the CLI flags for the two main tools: + +- `../jibo_automod.py` (installer/mod tool) +- `../jibo_updater.py` (OS updater) + +If you’re using launchers (`.sh`/`.bat`), they forward all arguments through. + +## jibo_automod.py + +### Modes (mutually exclusive) + +- (no mode flag) + - Full mod workflow (full eMMC dump, extract/modify/write `/var`). + +- `--dump-only` + - Only dump eMMC; don’t modify anything. + +- `--write-partition FILE` + - Write an already-prepared partition image to eMMC. + - You must tell it where to write using `--start-sector`. + +- `--mode-json-only` + - Fast path: + 1) read GPT (small) + 2) read `/var` only (~500MB) + 3) modify `/var/jibo/mode.json` + 4) write back either a patch (default) or full `/var` + +### Common options + +- `--dump-path FILE` + - Use an existing dump file instead of reading from the device. + +- `--output FILE` / `-o FILE` + - Output file for dumps. + +- `--start-sector HEX` + - Start sector for `--write-partition`. + - Parsed with base autodetect (`0x...` works). + - Default is `0x7E9022` (but the full/fast workflows usually compute the start sector from GPT). + +- `--force-dump` + - Re-dump even if a dump exists. + +- `--rebuild-shofel` + - Force rebuilding ShofEL (`make clean` then `make`). + +- `--skip-detection` + - Skip USB “is Jibo connected” checks. + +- `--no-verify` + - Skip verification read-back. + +### Fast mode options + +- `--full-var-write` + - Only meaningful with `--mode-json-only`. + - If set: write the full `/var` partition back (slower). + - If not set: compute sector diffs and only write changed ranges (faster). + +### Examples + +- Full mod: + - `python3 jibo_automod.py` + +- Dump only: + - `python3 jibo_automod.py --dump-only -o my_dump.bin` + +- Use existing dump: + - `python3 jibo_automod.py --dump-path jibo_work/jibo_full_dump.bin` + +- Fast mode: + - `python3 jibo_automod.py --mode-json-only` + +- Write a prepared partition: + - `python3 jibo_automod.py --write-partition var_partition.bin --start-sector 0x7E9022` + +## jibo_updater.py + +The updater assumes you already have SSH access to the robot. + +### Required + +- `--ip ` (alias: `--host`) + - IP or hostname of your Jibo. + +### Connection + +- `--user ` (default `root`) +- `--password ` (default `jibo`) +- `--ssh-timeout ` (default `15`) + +### Release selection + +- `--releases-api ` + - API endpoint for Gitea releases. + +- `--stable` + - Ignore prereleases. + +- `--tag ` + - Install a specific tag instead of “latest”. + +### Archive layout + +- `--build-path ` + - If the updater can’t find the `build/` folder automatically, specify where it is inside the extracted archive. + +### Safety / UX + +- `--state-file ` + - Where it remembers the last applied version per host. + +- `--force` + - Re-download and re-install even if the local state says you’re already on that version. + +- `--yes` + - Don’t prompt for confirmation. + +- `--dry-run` + - Download/extract + connect, but don’t upload files and don’t touch mode.json. + +### Returning to normal mode + +- `--return-normal` + - After update, set `/var/jibo/mode.json` back to `normal` (no prompt). + +- `--no-return-normal` + - Never prompt and never change mode back. + +### Examples + +- Update to latest: + - `python3 jibo_updater.py --ip 192.168.1.50` + +- Stable only: + - `python3 jibo_updater.py --ip 192.168.1.50 --stable` + +- Specific tag: + - `python3 jibo_updater.py --ip 192.168.1.50 --tag v3.3.0` + +- Dry run: + - `python3 jibo_updater.py --ip 192.168.1.50 --dry-run` + +More detail: [[06 - Updater (How It Works)]] diff --git a/Jibo Tools & Mod Installer/04 - GUI (How It Works).md b/Jibo Tools & Mod Installer/04 - GUI (How It Works).md new file mode 100644 index 0000000..01cf818 --- /dev/null +++ b/Jibo Tools & Mod Installer/04 - GUI (How It Works).md @@ -0,0 +1,100 @@ +# GUI (How It Works) + +The GUI is an optional Qt (PySide6) front-end. + +>[!Important] +the GUI does **not** re-implement the mod/updater logic; it mostly launches the same Python scripts and shows their logs. + +- - - + + +![[JiboToolsScreen.png]] + +- - - +## Entry points + +- Linux launcher: `../jibo_gui.sh` +- Windows launcher: `../jibo_gui.bat` + +The GUI module it runs is: + +- `python -m gui.main_panel` + +The implementation is in: + +- `../JiboTools/JiboTools/gui/main_panel.py` + +## Main Panel overview + +The main panel UI (`form.ui`) is loaded at runtime (Qt Widgets, not QML): + +- `../JiboTools/JiboTools/form.ui` + +`MainWindowController` wires up widgets and behavior: + +- “Connect” button opens an SSH session to the robot using Paramiko. +- It reads `/var/jibo/identity.json` to display the robot name. +- The panel includes toggles/fields for Home Assistant and AI settings (currently UI-only wiring; the panel mainly focuses on connection + launching tools). + +### Connection behavior + +- Host/IP comes from the UI field. +- Credentials are currently fixed to `root` / `jibo` in the panel code. +- UI shows a status dot and swaps images based on connection state. + +## Tool runner windows (Installer / Updater) + +When you click installer/updater from the panel, it spawns a separate “Tool Runner” window: + +- Installer: runs `jibo_automod.py` +- Updater: runs `jibo_updater.py` + +The common implementation is: + +- `../JiboTools/JiboTools/gui/tool_runner_window.py` + +### How the tool runner executes scripts + +- Uses `QProcess` (see `ProcessRunner`) to run a Python process. +- Captures merged stdout/stderr and appends it into a log view. +- Has a Start/Stop button (Stop terminates then kills if needed). + +It resolves which Python to use with: + +- `resolve_python_invocation()` in `../JiboTools/JiboTools/gui/process_runner.py` + +Resolution order (simplified): + +1. Use repo-local `../.venv/` Python if present. +2. Otherwise use the current interpreter (useful if launched from Qt Creator). +3. Windows fallback: `py -3`. +4. Linux fallback: `python3`, then `python`. + +### Passing arguments + +- The tool runner has an “Extra args” textbox. +- For the updater runner specifically, it also has a host field that becomes `--ip `. + +This means the GUI is effectively a thin wrapper over the CLI flags described in [[03 - CLI Arguments]]. + +### “Open in terminal” + +The tool runner can try to spawn an external terminal window with the exact command line it would run. + +- Linux: tries `x-terminal-emulator`, `gnome-terminal`, `konsole`, etc. +- Windows: uses `cmd.exe`. + +## Dependencies + +GUI deps live in: + +- `../requirements-gui.txt` (PySide6) +- `../JiboTools/JiboTools/requirements.txt` (PySide6 + Paramiko) + +The CLI installer launcher `../jibo_automod.sh` also auto-creates `../.venv/` and installs `../JiboTools/JiboTools/requirements.txt` if you pick GUI mode. + +## Practical notes / limitations + +- The GUI is great for convenience, but debugging is often easier from CLI because you can see exactly what flags are being passed. +- The installer still requires RCM mode + USB access; the GUI does not remove that requirement. +- The updater requires SSH access (meaning: you must already be in developer mode / checkmark boot). diff --git a/Jibo Tools & Mod Installer/05 - Windows Support.md b/Jibo Tools & Mod Installer/05 - Windows Support.md new file mode 100644 index 0000000..07ecf9b --- /dev/null +++ b/Jibo Tools & Mod Installer/05 - Windows Support.md @@ -0,0 +1,83 @@ +# Windows Support + +This repo supports Windows, but there are two separate “Windows” stories: + +1. **Running the Python scripts on Windows** (launchers: `.bat`) +2. **Actually talking to the Jibo over USB in RCM mode** (drivers + build tools) + +The USB/RCM part is the trickiest. + +## Launchers + +- Installer: `../jibo_automod.bat` + - Runs `python ../jibo_automod.py %*` + - Warns if not Administrator. + +- Updater: `../jibo_updater.bat` + - Prefers `../.venv/` Python if present. + - Else prefers `py -3`. + +- GUI: `../jibo_gui.bat` + - Same Python resolution approach. + +## Environment setup helper + +- `../windows_setup.bat` helps install dependencies via MSYS2 and explains Zadig. + +It installs (via MSYS2): + +- MinGW gcc/make +- libusb +- ARM toolchain (`arm-none-eabi-gcc`) for payload builds + +## USB driver requirement (RCM mode) + +When Jibo is in RCM mode it enumerates as NVIDIA APX (`0955:7740`). + +On Windows you typically need to replace its driver with WinUSB: + +- Use Zadig and install WinUSB for the “APX” device. + +Without this, ShofEL won’t be able to talk to the device. + +## Editing mode.json on Windows + +Linux can mount the ext filesystem image and edit `/var/jibo/mode.json` normally. + +Windows usually can’t mount the ext image easily, so `../jibo_automod.py` tries alternative methods: + +1. **debugfs (recommended)** + - If `debugfs.exe` is available on PATH, the tool can edit the file inside the ext filesystem image safely. + - Install via MSYS2: + - `pacman -S --needed e2fsprogs` + +2. **Raw in-place patch (last resort)** + - The tool searches the partition image bytes for JSON patterns and overwrites them without changing length. + - This can fail if the on-disk JSON format differs or if there’s no safe padding space. + +If you’re on Windows and you’re seeing warnings about raw edits or the tool can’t find patterns, installing `debugfs` is the best fix. + +## WSL option + +Another workable approach is to use WSL2 and follow the Linux path. + +Caveat: you still need USB passthrough into WSL (which can be non-trivial depending on your setup). + +## Common Windows failure modes + +- Device not detected / can’t open USB: + - Wrong driver (use Zadig -> WinUSB) + - Not Administrator + - Cable is charge-only + +- Build failures: + - Missing MSYS2 packages + - ARM toolchain missing (payload `.bin` files won’t build) + +- mode.json edit failures: + - Install `e2fsprogs` and ensure `debugfs` is on PATH + +## Related docs + +- Installer workflow: [[01 - Installer (How It Works)]] +- CLI flags: [[03 - CLI Arguments]] diff --git a/Jibo Tools & Mod Installer/06 - Updater (How It Works).md b/Jibo Tools & Mod Installer/06 - Updater (How It Works).md new file mode 100644 index 0000000..b113ca9 --- /dev/null +++ b/Jibo Tools & Mod Installer/06 - Updater (How It Works).md @@ -0,0 +1,79 @@ +# Updater (How It Works) + +The updater is a separate tool from the installer. + +- Installer: puts Jibo into developer mode by editing `/var/jibo/mode.json` via RCM + eMMC writes. +- Updater: once you have SSH access, it downloads a JiboOs release and uploads a rootfs overlay to the robot over SFTP. + +Implementation: `../jibo_updater.py` + +## High-level flow + +1. Query the releases API (Gitea JSON) and pick a release: + - latest (default) + - stable-only (`--stable`) + - specific tag (`--tag`) + +2. Download the chosen release archive. + +3. Extract it safely (checks for path traversal in archives). + +4. Find the `build/` folder inside the extracted tree. + - You can override with `--build-path`. + +5. SSH into the Jibo using Paramiko. + +6. Ensure `/` is writable: + - tests with a `touch` on `/.jibo_rw_test` + - if needed, runs `mount -o remount,rw /` + +7. Upload the contents of `build/` into `/` using SFTP. + - Directories are created as needed. + - Files are uploaded and chmod is best-effort preserved. + - Symlinks are uploaded as symlinks if possible; otherwise it uploads dereferenced content. + +8. Optionally return Jibo to normal mode by changing `/var/jibo/mode.json` back to `normal`. + +9. Record the applied tag in a local state file so repeated runs can short-circuit. + +## What “build/” means + +Releases are expected to contain a “rootfs overlay” folder named `build/`. + +That directory typically includes paths like: + +- `etc/` +- `opt/` +- `usr/` +- `var/` + +The updater essentially copies those files to the same locations on the robot. + +## State file + +By default, the updater stores last-applied tag per host in: + +- `../jibo_work/update_state.json` + +If the state file says the host already has the latest tag, it exits unless you pass `--force`. + +More: [[07 - Working Directory + State Files]] + +## Safety knobs + +- It prompts before upload unless `--yes` is passed. +- `--dry-run` downloads/extracts and connects, but does not upload or edit mode.json. + +## Returning to normal mode + +At the end, the updater can switch the robot back to normal mode: + +- `--return-normal` (force it) +- `--no-return-normal` (never prompt / never change) +- otherwise it prompts (unless `--yes` is passed) + +Note: returning to normal mode can disable the “checkmark/dev” behavior depending on how JiboOs uses `mode.json`. + +## CLI reference + +See [[03 - CLI Arguments]] for the complete list and examples. diff --git a/Jibo Tools & Mod Installer/07 - Working Directory + State Files.md b/Jibo Tools & Mod Installer/07 - Working Directory + State Files.md new file mode 100644 index 0000000..5c8f9ad --- /dev/null +++ b/Jibo Tools & Mod Installer/07 - Working Directory + State Files.md @@ -0,0 +1,65 @@ +# Working Directory + State Files + +Both the installer and updater use `../jibo_work/` as their “scratch + cache” directory. + +This is helpful for: + +- keeping your large dumps out of the repo root +- making it obvious what can be deleted vs what is precious + +## jibo_automod.py outputs + +Depending on mode, you may see: + +- `jibo_full_dump.bin` + - The full eMMC dump (~15GB). Created by full workflow. + +- `gpt_dump.bin` + - Small dump (default 4096 sectors / ~2MB) used by `--mode-json-only`. + +- `var_partition_original.bin` + - Original `/var` read from the robot (fast mode). + +- `var_partition.bin` + - Working copy that gets modified. + +- `var_partition_backup.bin` + - Backup copy made before modifications. + +- `verify_partition.bin` + - Read-back buffer used during verification. + +- `var_patch_###.bin` + - Patch chunks produced by sector-diff patch-writing in fast mode. + +- `mode.json.original` / `mode.json.modified` + - Best-effort debug copies of the JSON before/after editing. + +### What you should keep + +- Keep `var_partition_backup.bin` somewhere safe. +- If you made a full dump, consider archiving `jibo_full_dump.bin` (space permitting). + +## jibo_updater.py outputs + +The updater uses: + +- `../jibo_work/updates/` + - `downloads/` cached archives + - `extracted/` extracted trees + +And it tracks state in: + +- `../jibo_work/update_state.json` + +That file maps host -> last applied tag. + +## Cleaning up + +- Safe-ish to delete: extracted archives and patch chunks (you can always re-download / re-create). +- Be careful deleting: backups and any full dump you still care about. + +## Related docs + +- Installer overview: [[01 - Installer (How It Works)]] +- Updater overview: [[06 - Updater (How It Works)]] diff --git a/Jibo Tools & Mod Installer/08 - Troubleshooting.md b/Jibo Tools & Mod Installer/08 - Troubleshooting.md new file mode 100644 index 0000000..3a4ba5e --- /dev/null +++ b/Jibo Tools & Mod Installer/08 - Troubleshooting.md @@ -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]]