docs: add Tools chapter, restructure Production, expand gdbrunner section

Adds a new Tools super-section between Host Protocol and Production
covering the desktop GUIs, external libraries, and calculators that
ship around the cam. Restructures Production -- battery moves into
Tools, romfs-image lands under Shipping the application, and the TLS
toctree is renamed to "Advanced material" so it can host other niche
tutorials. Expands the make-debug-shortcut paragraph in
firmware/debugging.rst into a proper gdbrunner section. Fixes three
display bugs from nested code-inside-bold markup.

Tools chapter
- New tools/index.rst with three captioned groups: Desktop GUIs
  (IDE placeholder, Projects Tools), External libraries (openmv-py,
  Arduino RPC), Calculators (battery-life-estimator).
- New tools/openmv-py/ covers the host-side openmv PyPI package end
  to end: the included CLI viewer (cli.rst), a hello-cam page for
  connecting and reading stdout, frame streaming (including the
  raw-streaming JPEG-skip path), bidirectional custom channels, and
  a new events page covering _handle_event subclassing,
  poll_events(), and the cam-side send_event surface. Reference
  page documents the full Camera class plus the OMVException
  hierarchy; private channel-internals, retry decorator, and
  subclassing hooks at the bottom for power users.
- New tools/arduino-rpc/index.rst -- sales-summary page for the
  openmv-arduino-rpc library with a transports figure showing
  UART / SPI / I2C / CAN between an Arduino and a cam.
- New tools/projects-tools/index.rst -- desktop GUI tools paired
  with cam-side scripts (ISP tuner, thermal-overlay calibration,
  Prophesee visualiser).
- battery-life.rst moved out of production/ into
  tools/battery-life-estimator.rst.
- tools/ide/ is a placeholder for the IDE overview.

Production reorg
- Intro paragraph trimmed -- dropped "on battery" (now Tools) and
  the "order is roughly the path of a product" framing paragraph.
- Section order is now Custom firmware builds -> Shipping the
  application -> Advanced material.
- romfs-image.rst added under Shipping the application alongside
  freezing-scripts.rst.
- TLS toctree caption renamed "Working with TLS certificates" ->
  "Advanced material".

firmware/debugging.rst
- Old 11-line "make debug shortcut" paragraph replaced with a full
  "Command-line debugging with gdbrunner" section that introduces
  the gdbrunner Python package (pip install gdbrunner), shows how
  it collapses the manual server+gdb dance into one foreground
  process, and lists six features that help command-line users:
  clean lifecycle, STM32CubeProgrammer auto-discovery, per-project
  .gdbinit honoured, --dryrun, --show-output, and the QEMU backend.

Library index
- omv.protocol.rst moved from "Frozen Python helpers" to "Built
  into the firmware on every OpenMV camera board" -- it is
  registered via MP_REGISTER_EXTENSIBLE_MODULE in py_protocol.c,
  not a frozen script.

Display fixes (nested code-inside-bold)
- formatting.rst: four format-flag bullets used **flag \`\`-\`\`**,
  **flag \`\`0\`\`**, etc. -- RST can't nest code inside bold, so
  the asterisks and backticks were rendering literally. Reworked
  to one-word bold lead-ins (Left-align, Zero pad, Sign, Alternate
  form) with the flag character in code form in the body.
- debugging.rst pitfalls: **Everything is \`\`<optimized out>\`\`**
  had the same problem. Reworked to **Optimized-out variables.**
  lead-in with <optimized out> in the description.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: kwagyeman

docs/library/index.rst

@@ -126,6 +126,7 @@ Built into the firmware on every OpenMV camera board.
    omv.crc.rst
    omv.ml.rst
    omv.ulab.rst
+   omv.protocol.rst
    logging.rst
    senml.rst
 
@@ -136,7 +137,6 @@ networking, and utilities):
    :maxdepth: 1
 
    aioble.rst
-   omv.protocol.rst
    omv.rpc.rst
    omv.rtsp.rst
    omv.mqtt.rst

docs/openmvcam/tutorial/index.rst

@@ -44,4 +44,6 @@ something covered earlier, it links back.
    bluetooth/index.rst
    protocol/index.rst
 
+   tools/index.rst
+
    production/index.rst

docs/openmvcam/tutorial/production/firmware/debugging.rst

@@ -250,18 +250,74 @@ Reaching the Windows host from WSL depends on the WSL networking mode:
    boards (N6 / RT1062 / AE3). Use ``"request": "launch"`` to reset,
    flash the ELF, and start fresh at ``runToEntryPoint``.
 
-The ``make debug`` shortcut
----------------------------
-
-If the J-Link is on the same machine as the build, the repository has
-a shortcut that starts a GDB server with the right device automatically::
+Command-line debugging with gdbrunner
+-------------------------------------
+
+Setting up a GDB session against an embedded target by hand is a
+five-step dance: start the J-Link / ST-Link / OpenOCD GDB server in
+one window with the right device, port, and interface flags; wait
+for it to print *Waiting for GDB connection*; run
+``arm-none-eabi-gdb`` in a second window; type ``target remote
+localhost:<port>``; point gdb at the ELF. When the gdb session ends,
+remember to kill the server window. `gdbrunner
+<https://github.com/openmv/gdbrunner>`__ is a small CLI that collapses
+all of that into one foreground command::
+
+    pip install gdbrunner
+
+    gdbrunner jlink --device STM32H743VI build/OPENMV4/bin/firmware.elf
+    gdbrunner stlink build/OPENMV4/bin/firmware.elf
+    gdbrunner qemu --machine mps2-an500 build/OPENMV4/bin/firmware.elf
+
+The first positional argument picks the server backend (``jlink``,
+``stlink``, ``qemu``); the rest are forwarded to that backend, with
+defaults that work for the OpenMV cams. ``gdbrunner --help`` lists
+the full per-backend flag list; each backend's argument table is
+JSON-driven (``src/gdbrunner/backends.json``), so adding a new server
+is a config edit rather than code.
+
+The firmware repository's ``make debug`` target is a thin wrapper
+around gdbrunner that fills in the current ``TARGET``'s J-Link
+arguments automatically::
 
     make -j$(nproc) TARGET=<TARGET> DEBUG=1 debug
 
-This runs the SDK's ``gdbrunner`` with the board's J-Link arguments
-against ``build/<TARGET>/bin/firmware.elf``. It is convenient for
-command-line gdb; for source-level stepping, the VS Code Cortex-Debug
-setup above is what you want.
+This is the fastest way to drop into command-line gdb on whichever
+board ``TARGET`` selects.
+
+What gdbrunner does for command-line work:
+
+* **One process, clean lifecycle.** Server starts, gdb attaches when
+  the port is open, server is terminated cleanly when gdb exits. No
+  orphan ``JLinkGDBServer`` surviving the session, no two terminals
+  to manage.
+* **STM32CubeProgrammer auto-discovery.** The ``stlink`` backend
+  searches the usual install locations (``~/STM32CubeProgrammer/``,
+  ``/opt/st/``, the STM32CubeIDE plugin tree) for
+  ``ST-LINK_gdbserver``, so the long ``--cube-prog`` path doesn't
+  have to be typed every time.
+* **Per-project gdbinit honoured.** A ``.gdbinit`` in the current
+  directory is loaded with ``-ix`` -- overriding the user-wide
+  ``~/.gdbinit`` -- so per-project gdb scripting (pretty-printers,
+  board-specific macros, breakpoint sets) drops in by being present
+  in the working directory.
+* **Dry run.** ``--dryrun`` prints the server command without
+  running it, useful for adapting the invocation to a wrapper
+  script, copying it into an IDE launcher config, or just checking
+  what arguments gdbrunner is composing.
+* **Server output visible.** ``--show-output`` keeps the server's
+  stdout / stderr visible. The default suppresses it (so gdb's UI
+  stays clean); flip the flag when the server itself is what's
+  misbehaving.
+* **QEMU backend.** ``qemu-system-arm`` running ``mps2-an500`` /
+  ``mps3-an547`` debugs the same ELF without a board plugged in --
+  code paths that don't touch cam-specific peripherals are
+  steppable on a flight.
+
+For source-level stepping with breakpoint gutters and a peripheral
+register view, the VS Code Cortex-Debug setup above is the better
+tool; gdbrunner is the right one for everything that lives at the
+command line.
 
 Using the debugger
 ------------------
@@ -336,8 +392,8 @@ RT1062, or AE3 -- use J-Link for those.
 Debugging pitfalls
 ------------------
 
-* **Everything is ``<optimized out>``** -- you built ``DEBUG=0``.
-  Rebuild with ``DEBUG=1``.
+* **Optimized-out variables.** Everything shows ``<optimized out>``
+  -- you built ``DEBUG=0``. Rebuild with ``DEBUG=1``.
 * **"GDB executable not found"** -- the SDK ``gcc/bin`` is not on
   ``PATH``; set ``armToolchainPath`` / ``gdbPath``.
 * **"Cannot connect" / wrong memory map** -- wrong or missing

docs/openmvcam/tutorial/production/index.rst

@@ -3,39 +3,27 @@ Production
 
 A working script on the bench is the start, not the
 end. A camera that ships in a product has to do its job
-unattended, on battery, against a network the script
-does not control, without the source code being
-readable by whoever takes the enclosure apart. The
-pages in this section cover the practical work between
-*the demo runs* and *the device is out the door*.
-
-The order is roughly the path of a product: pick a
-battery that fits the duty cycle, freeze the
-application into the firmware so it ships as one
-binary, secure the network connections it makes, and --
-when the stock firmware needs to change -- build,
-flash, and debug the firmware itself.
+unattended, on a network the script does not control,
+without the source code being readable by whoever takes
+the enclosure apart. The pages in this section cover
+the practical work between *the demo runs* and *the
+device is out the door*.
 
 .. toctree::
-   :caption: Power and battery life
+   :caption: Custom firmware builds
    :maxdepth: 1
 
-   battery-life.rst
+   firmware/index.rst
 
 .. toctree::
    :caption: Shipping the application
    :maxdepth: 1
 
    freezing-scripts.rst
+   romfs-image.rst
 
 .. toctree::
-   :caption: Working with TLS certificates
+   :caption: Advanced material
    :maxdepth: 1
 
    tls/index.rst
-
-.. toctree::
-   :caption: Custom firmware builds
-   :maxdepth: 1
-
-   firmware/index.rst

docs/openmvcam/tutorial/production/romfs-image.rst

@@ -0,0 +1,16 @@
+Building a ROMFS image
+======================
+
+A *ROMFS image* is a flash-resident, read-only
+filesystem the firmware mounts at ``/rom/``. It is the
+right place to ship assets that are too large or too
+many to freeze as Python modules: machine-learning model
+files, label tables, JSON configuration, image
+templates, anything the application opens and reads but
+never writes.
+
+This page covers building a ROMFS partition image
+offline and laying it down alongside the firmware so the
+shipped device reads from it directly at boot.
+
+(Page in progress -- content to come.)

docs/openmvcam/tutorial/python/text/formatting.rst

@@ -192,14 +192,14 @@ type letter. The full shape is ``%[flags][width][.precision]type``:
   number of digits after the decimal point. ``%.2f`` gives two
   decimal places. For strings, the maximum number of characters
   to take (``%.5s`` truncates to five).
-* **flag ``-``** -- left-align inside the field. ``%-10d`` puts
-  the digits on the left side with trailing spaces.
-* **flag ``0``** -- pad with leading zeros instead of spaces (for
-  numeric types). ``%05d`` zero-pads to five digits.
-* **flag ``+``** -- always show the sign on numbers, including a
-  ``+`` for positives.
-* **flag ``#``** -- alternate form. For ``%x`` this prefixes the
-  output with ``0x``; for ``%o`` it prefixes ``0o``.
+* **Left-align** -- the ``-`` flag puts the field on the left.
+  ``%-10d`` puts the digits on the left side with trailing spaces.
+* **Zero pad** -- the ``0`` flag pads with leading zeros instead
+  of spaces (for numeric types). ``%05d`` zero-pads to five digits.
+* **Sign** -- the ``+`` flag always shows the sign on numbers,
+  including a ``+`` for positives.
+* **Alternate form** -- the ``#`` flag. For ``%x`` this prefixes
+  the output with ``0x``; for ``%o`` it prefixes ``0o``.
 
 Flags, width, and precision can be combined:
 

docs/openmvcam/tutorial/tools/arduino-rpc/figures/transports.svg

@@ -0,0 +1,42 @@
+OpenMV Arduino RPC Library
+==========================
+
+The `openmv-arduino-rpc
+<https://github.com/openmv/openmv-arduino-rpc>`__
+library is the Arduino-side counterpart to the cam's
+:mod:`rpc` module. The cam registers Python callables;
+the Arduino calls them as if they were local functions,
+over UART, SPI, I2C, or CAN. No PC sits in the middle.
+
+.. image:: figures/transports.svg
+   :alt: An Arduino board on the left and an OpenMV cam
+         on the right, connected by four labelled
+         transport lines -- UART (two wires), SPI (four
+         wires), I2C (two wires), and CAN (two wires) --
+         showing the wire-level pairings the Arduino
+         RPC library can drive.
+   :align: center
+
+The pattern is symmetric. The Arduino sketch picks the
+transport class that matches the wire, calls a function
+on the cam by name, and gets the return value back. The
+cam side mirrors it: register Python callables, run the
+library's polling loop. Framing, fragmentation, and
+retries on a noisy bus are handled by both sides
+underneath, so application code sees just "call a
+function on the other board, get a result back."
+
+The repo's `examples
+<https://github.com/openmv/openmv-arduino-rpc/tree/master/examples>`__
+cover the two shapes most projects need: short
+remote-control calls (read a sensor, drive a pin, run a
+detector and read the result back) and JPEG image
+streaming from the cam to the Arduino for forwarding
+onward. Paired cam-side scripts ship in the openmv
+tree under
+`08-RPC-Library/
+<https://github.com/openmv/openmv/tree/master/scripts/examples/08-RPC-Library>`__.
+
+The repo README covers per-transport wiring; the
+:doc:`/library/omv.rpc` reference covers the cam-side
+API in full.

docs/openmvcam/tutorial/tools/arduino-rpc/index.rst

@@ -0,0 +1,10 @@
+OpenMV IDE
+==========
+
+The OpenMV IDE is the desktop editor and runtime that
+ships with every camera. It is the fastest way to write,
+run, and iterate on a script: open a project, plug in a
+camera, hit run, and the frame buffer streams back in
+real time while the script executes on the device.
+
+(Section in progress -- pages to come.)