OMG More warnings

.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",

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

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]]
+

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@<jibo-ip>`
+- 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 <args>`
+
+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 <args>`
+- 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]]

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 <start> 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).

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 <host>` (alias: `--host`)
+  - IP or hostname of your Jibo.
+
+### Connection
+
+- `--user <name>` (default `root`)
+- `--password <pass>` (default `jibo`)
+- `--ssh-timeout <seconds>` (default `15`)
+
+### Release selection
+
+- `--releases-api <url>`
+  - API endpoint for Gitea releases.
+
+- `--stable`
+  - Ignore prereleases.
+
+- `--tag <tag>`
+  - Install a specific tag instead of “latest”.
+
+### Archive layout
+
+- `--build-path <relative/path>`
+  - If the updater can’t find the `build/` folder automatically, specify where it is inside the extracted archive.
+
+### Safety / UX
+
+- `--state-file <path>`
+  - 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)]]

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 <host>`.
+
+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).

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]]

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.

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)]]

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]]