docs(pi): audit and rewrite Pi6X Flow and Just a Pi docs

SUMMARY.md

@@ -44,6 +44,8 @@
     * [Apt Upgrade Hold Back Risky Packages](embedded-computers/ark-just-a-jetson/apt-upgrade-hold-back-risky-packages.md)
   * [ARK Just a Pi](embedded-computers/ark-just-a-pi/README.md)
     * [Getting Started](embedded-computers/ark-just-a-pi/getting-started.md)
+    * [ARK-OS](embedded-computers/ark-just-a-pi/ark-services/README.md)
+      * [Services](embedded-computers/ark-just-a-pi/ark-services/services.md)
     * [Flashing Guide](embedded-computers/ark-just-a-pi/flashing-guide/README.md)
       * [Pi CM5 Lite with Micro SD](embedded-computers/ark-just-a-pi/flashing-guide/pi-cm5-lite-with-micro-sd.md)
       * [Pi CM5 with EMMC](embedded-computers/ark-just-a-pi/flashing-guide/pi-cm5-with-emmc.md)
@@ -116,20 +118,20 @@
       * [USB Cameras and GPS](products/flight-controller/jetson-pabs/ark-jetson-pab-carrier-v3/usb-cameras-and-gps.md)
       * [Apt Upgrade Hold Back Risky Packages](products/flight-controller/jetson-pabs/ark-jetson-pab-carrier-v3/apt-upgrade-hold-back-risky-packages.md)
   * [ARK Pi6X Flow](flight-controller/ark-pi6x-flow/README.md)
-    * [Block Diagram](flight-controller/ark-pi6x-flow/block-diagram.md)
-    * [Pinout](flight-controller/ark-pi6x-flow/pinout.md)
-    * [3D Models](flight-controller/ark-pi6x-flow/3d-models.md)
     * [Flashing Guide](flight-controller/ark-pi6x-flow/flashing-guide/README.md)
       * [Pi CM4 Lite with Micro SD](flight-controller/ark-pi6x-flow/flashing-guide/pi-cm4-lite-with-micro-sd.md)
       * [Pi CM4 with EMMC](flight-controller/ark-pi6x-flow/flashing-guide/pi-cm4-with-emmc.md)
       * [After Flashing, Before Installing](flight-controller/ark-pi6x-flow/flashing-guide/after-flashing-before-installing.md)
       * [Wi-Fi Setup](flight-controller/ark-pi6x-flow/flashing-guide/wi-fi-setup.md)
       * [SSH](flight-controller/ark-pi6x-flow/flashing-guide/ssh.md)
-    * [ARK Services](flight-controller/ark-pi6x-flow/ark-services/README.md)
+    * [ARK-OS](flight-controller/ark-pi6x-flow/ark-services/README.md)
       * [Services](flight-controller/ark-pi6x-flow/ark-services/services.md)
     * [Autopilot Connections](flight-controller/ark-pi6x-flow/autopilot-connections/README.md)
       * [QGroundControl Connection](flight-controller/ark-pi6x-flow/autopilot-connections/qgroundcontrol-connection.md)
     * [Updating the Flight Controller Firmware](flight-controller/ark-pi6x-flow/updating-the-flight-controller-firmware.md)
+    * [Pinout](flight-controller/ark-pi6x-flow/pinout.md)
+    * [Block Diagram](flight-controller/ark-pi6x-flow/block-diagram.md)
+    * [3D Models](flight-controller/ark-pi6x-flow/3d-models.md)
   * [ARK VOXL2 RTK PAB Carrier](flight-controller/ark-voxl2-rtk-pab-carrier/README.md)
     * [Pinout](flight-controller/ark-voxl2-rtk-pab-carrier/pinout.md)
     * [Connectors and Cables](flight-controller/ark-voxl2-rtk-pab-carrier/connectors-and-cables.md)

embedded-computers/ark-just-a-pi/ark-services/README.md

@@ -0,0 +1,39 @@
+# ARK-OS
+
+[ARK-OS](https://github.com/ARK-Electronics/ARK-OS) is ARK's companion computer software suite: a set of systemd services for MAVLink routing, video streaming, flight log management, firmware updates, and network RTK corrections, plus a web UI to manage it all. It comes pre-installed on the golden image that ships with Just A Pi bundles.
+
+## ARK-UI
+
+The web UI is served at [http://just-a-pi.local](http://just-a-pi.local) (or the Pi's IP). Pages: **System** (hardware and resource info, hostname), **Autopilot** (status, firmware update, and reset for a USB-connected flight controller), **Connections** (WiFi/Ethernet/LTE, data usage), **Services** (start/stop, autostart, logs, config editing), **Video** (live camera stream), and **Logs** (flight log download and upload to Flight Review).
+
+<figure><img src="../../../.gitbook/assets/ark-ui-services-pi.png" alt=""><figcaption><p>Services page — start/stop services, toggle autostart, view logs, edit configs</p></figcaption></figure>
+
+## Services
+
+See the [Services](services.md) page for what each service does and which are enabled by default.
+
+## Command-Line Tools
+
+ARK-OS puts its operator scripts on `PATH` (open a login shell and run them by name):
+
+```
+mavlink_shell.py              # interactive PX4 NSH shell over MAVLink
+px4_shell_command.py <cmd>    # run a single PX4 console command
+flash_firmware.sh <fw.px4>    # flash flight controller firmware
+reset_fmu_fast.py             # reset the flight controller
+reset_fmu_wait_bl.py          # reset the flight controller into bootloader
+```
+
+## Installing and Updating ARK-OS
+
+ARK-OS is distributed as a Debian package on the [releases page](https://github.com/ARK-Electronics/ARK-OS/releases) — `ark-os-pi-trixie` for Raspberry Pi OS based on Debian 13, `ark-os-pi-bookworm` for Debian 12. The install script picks the right one automatically and is also the supported way to update. Run it from a clone of the repo on the Pi:
+
+```bash
+git clone https://github.com/ARK-Electronics/ARK-OS.git
+cd ARK-OS
+sudo ./packaging/install_ark_os.sh --ark-os-version=X.Y.Z
+```
+
+{% hint style="warning" %}
+Upgrading resets the service configuration under `/etc/ark-os/` to packaged defaults — reconfigure via the web UI afterward.
+{% endhint %}

embedded-computers/ark-just-a-pi/ark-services/services.md

@@ -0,0 +1,31 @@
+---
+description: What each ARK-OS service does.
+---
+
+# Services
+
+ARK-OS services are system-level [systemd services](https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html) running as the `pi` user. Manage them — including configuration editing — from the [ARK-UI](http://just-a-pi.local) **Services** page, or with `systemctl`. Configuration files live under `/etc/ark-os/`. Services that talk to a flight controller expect one connected over USB.
+
+## Enabled by Default
+
+**mavlink-router** routes MAVLink between a USB-connected flight controller (`/dev/ttyACM0`) and user-defined UDP/TCP endpoints such as QGroundControl. Default config: [main.conf](https://github.com/ARK-Electronics/ARK-OS/blob/main/services/mavlink-router/main.conf).
+
+**rtsp-server** streams the first CSI camera over RTSP at `rtsp://just-a-pi.local:5600/camera1` using gstreamer.
+
+**go2rtc** restreams the RTSP feed to the browser over WebRTC for the ARK-UI **Video** page.
+
+**ark-ui-backend**, **system-manager**, **service-manager**, **connection-manager**, **autopilot-manager** are the REST APIs behind the ARK-UI (hidden from the Services page).
+
+## Optional (installed, disabled by default)
+
+Enable from the ARK-UI Services page or with `systemctl enable --now <service>`.
+
+**dds-agent** bridges PX4 uORB topics to ROS 2 by running the [Micro XRCE-DDS Agent](https://github.com/eProsima/Micro-XRCE-DDS-Agent) on a serial connection to a flight controller. The bridged topics are defined in [PX4's dds\_topics.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/uxrce_dds_client/dds_topics.yaml).
+
+**logloader** downloads PX4 `.ulg` flight logs from the flight controller's SD card over MAVLink FTP and optionally uploads them to [Flight Review](https://review.px4.io/). Driven from the ARK-UI **Logs** page.
+
+**flight-review** hosts a local [PX4 Flight Review](https://github.com/PX4/flight_review) server at [http://just-a-pi.local/flight-review](http://just-a-pi.local/flight-review) for the logs downloaded by logloader.
+
+**polaris** receives network RTK corrections from the [Point One Polaris](https://pointonenav.com/polaris) service (subscription required) and publishes them to the flight controller over MAVLink.
+
+**pointperfect** receives GNSS corrections from the [u-blox PointPerfect](https://www.u-blox.com/en/product/pointperfect) NTRIP service and publishes them to the flight controller over MAVLink. For u-blox receivers it can also request AssistNow start-up assistance for a faster first fix.

embedded-computers/ark-just-a-pi/flashing-guide/README.md

@@ -1,6 +1,23 @@
 # Flashing Guide
 
-If you purchased just the Just a Pi and are installing your own Pi:
+Bundles that include a CM5 ship pre-imaged with ARK-OS — no flashing required. Follow this guide if you purchased just the carrier and are installing your own Compute Module.
+
+## Option 1: ARK Golden Image (recommended)
+
+The [ark\_pi\_image](https://github.com/ARK-Electronics/ark_pi_image) repository builds the same turnkey image that ships on bundles: Raspberry Pi OS with the carrier's `config.txt` configuration baked in and ARK-OS pre-installed. On a Linux host:
+
+```bash
+git clone https://github.com/ARK-Electronics/ark_pi_image.git
+cd ark_pi_image
+./build.sh --provision        # build the Just A Pi CM5 image with ARK-OS
+./flash.sh /dev/sdX           # write it to the SD card
+```
+
+No Raspberry Pi Imager and no manual `config.txt` edits. For a CM5 with onboard eMMC (no SD slot), short the `BOOT` jumper, connect USB-C, run [rpiboot](https://www.raspberrypi.com/documentation/computers/compute-module.html#flashing-the-compute-module-emmc) so the eMMC appears as a block device, then `./flash.sh` to it.
+
+## Option 2: Raspberry Pi Imager (manual)
+
+Flash stock Raspberry Pi OS, then configure the carrier by hand:
 
 {% content-ref url="pi-cm5-lite-with-micro-sd.md" %}
 [pi-cm5-lite-with-micro-sd.md](pi-cm5-lite-with-micro-sd.md)
@@ -10,3 +27,4 @@ If you purchased just the Just a Pi and are installing your own Pi:
 [pi-cm5-with-emmc.md](pi-cm5-with-emmc.md)
 {% endcontent-ref %}
 
+Then edit `config.txt` for the carrier ([After Flashing, Before Installing](after-flashing-before-installing.md)), boot, and [install ARK-OS](../ark-services/README.md).

embedded-computers/ark-just-a-pi/flashing-guide/pi-cm5-lite-with-micro-sd.md

@@ -10,8 +10,8 @@ If using Ubuntu:
 wget -O pi_imager.deb https://downloads.raspberrypi.org/imager/imager_latest_amd64.deb && sudo dpkg -i pi_imager.deb && rm pi_imager.deb
 ```
 
-{% hint style="warning" %}
-Select **Raspberry Pi OS (Legacy, 64-bit)**, which is based on Debian Bookworm. Newer Raspberry Pi OS releases based on Debian Trixie are not yet verified on this board.
+{% hint style="info" %}
+Select a **64-bit** Raspberry Pi OS. ARK-OS ships packages for both current Raspberry Pi OS (Debian 13 Trixie) and Legacy (Debian 12 Bookworm) — the install script picks the matching one automatically.
 {% endhint %}
 
 Apply OS customization to configure WiFi and enable SSH:

embedded-computers/ark-just-a-pi/getting-started.md

@@ -1,38 +1,56 @@
 # Getting Started
 
-The ARK Just A Pi is a compact carrier board for the Raspberry Pi Compute Module 5. This guide covers preparing the board and connecting to it for the first time.
+The ARK Just A Pi is a compact carrier board for the Raspberry Pi Compute Module 5.
 
-<!-- TODO: Document what comes pre-installed/pre-configured on bundle orders, if anything. -->
+## What's Pre-Installed
 
-## Flashing the Compute Module
+Bundles that include a CM5 ship pre-imaged and ready to use:
 
-If you are installing your own Compute Module, follow the [Flashing Guide](flashing-guide/README.md) to image the CM5 (micro SD for the CM5 Lite, or eMMC over USB-C) and prepare it for first boot.
+* **OS**: Raspberry Pi OS (64-bit) with the carrier configuration baked in and [ARK-OS](https://github.com/ARK-Electronics/ARK-OS) pre-installed
+* **Credentials**: Username `pi`, password `pi`, hostname `just-a-pi`
 
-If you set up the OS using the Raspberry Pi Imager customization options described in the flashing guide, the board comes up with:
+{% hint style="info" %}
+The default password is well known — change it (`passwd`) before putting the device on a network you don't control.
+{% endhint %}
 
-- **Username**: `pi`
-- **Password**: `pi`
-- **Hostname**: `just-a-pi`
+If you are installing your own Compute Module, follow the [Flashing Guide](flashing-guide/README.md) first.
 
 ## Connecting
 
-### Serial Debug Console
+### Option 1: WiFi Hotspot
 
-The **UART0 Debug** connector (6-pin JST-GH) exposes the Compute Module's serial console at 3.3V. Connect a 3.3V USB-to-serial adapter to reach the console before the network is configured. See the [Pinout](pinout.md) for the connector pin assignments.
+On first boot, if no known WiFi network is available, the Pi brings up a hotspot:
+
+* **Network**: `just-a-pi-<serial>`
+* **Password**: `password`
+
+Connect to the hotspot, open [http://just-a-pi.local](http://just-a-pi.local), and join your WiFi network from the **Connections** page:
 
-### SSH over the network
+<figure><img src="../../.gitbook/assets/ark-ui-connections-justapi.png" alt=""><figcaption><p>ARK-UI Connections page</p></figcaption></figure>
 
-Once Wi-Fi or Ethernet is configured (see [Wi-Fi Setup](flashing-guide/wi-fi-setup.md) and [SSH](flashing-guide/ssh.md)), connect over SSH:
+Once the Pi is on your network:
 
 ```bash
 ssh pi@just-a-pi.local
 ```
 
 If mDNS is not available on your network, use the Pi's IP address instead.
 
+### Option 2: Ethernet
+
+Plug either external Ethernet port into your network — the Pi requests an address over DHCP.
+
+### Option 3: Serial Debug Console
+
+The **UART0 Debug** connector (6-pin JST-GH) exposes the Compute Module's serial console at 3.3V. Connect a 3.3V USB-to-serial adapter to reach the console before the network is configured. See the [Pinout](pinout.md) for the connector pin assignments.
+
+## ARK-UI Web Interface
+
+ARK-OS hosts a web UI at [http://just-a-pi.local](http://just-a-pi.local) for managing the device: system info, network connections, services, and video streaming. See [ARK-OS](ark-services/README.md).
+
 ## Next Steps
 
-- [Flashing Guide](flashing-guide/README.md) – Image the Compute Module and prepare it for first boot
-- [Pinout](pinout.md) – Connector and pin assignments
-- [Block Diagram](block-diagram.md) – Board architecture overview
-- [3D Model](3d-model.md) – STEP files
+* [ARK-OS](ark-services/README.md) – The pre-installed services and web UI
+* [Flashing Guide](flashing-guide/README.md) – Image the Compute Module
+* [Pinout](pinout.md) – Connector and pin assignments
+* [Block Diagram](block-diagram.md) – Board architecture overview

flight-controller/ark-pi6x-flow/ark-services/README.md

@@ -1,20 +1,39 @@
-# ARK Services
+# ARK-OS
 
-ARK-OS is a collection of optional systemd services that provide convenience features for the ARK Pi6X Flow. These services are not required for basic operation but add useful functionality like automatic log downloading, web-based configuration, and network RTK corrections. If you purchased an ARK Pi6X Flow with a Pi included, these services come pre-installed.
-
-**Repository**: [https://github.com/ARK-Electronics/ARK-OS](https://github.com/ARK-Electronics/ARK-OS)
+[ARK-OS](https://github.com/ARK-Electronics/ARK-OS) is ARK's companion computer software suite: a set of systemd services for MAVLink routing, video streaming, flight log management, firmware updates, and network RTK corrections, plus a web UI to manage it all. Pi6X Flow bundles that include a Pi ship with ARK-OS pre-installed.
 
 ## ARK-UI
 
-ARK-UI is a web interface for managing your Pi. Access it at [http://pi6x.local](http://pi6x.local).
+The web UI is served at [http://pi6x.local](http://pi6x.local) (or the Pi's IP). Pages: **System** (hardware and resource info, hostname), **Autopilot** (status, firmware update, reset), **Connections** (WiFi/Ethernet/LTE, data usage), **Services** (start/stop, autostart, logs, config editing), **Video** (live camera stream), and **Logs** (flight log download and upload to Flight Review).
 
-From ARK-UI you can:
-- Configure WiFi networks and hotspot settings
-- Manage ARK-OS services (start, stop, enable, disable)
-- Update flight controller firmware
-- Edit service configurations
-- View system logs
+<figure><img src="../../../.gitbook/assets/ark-ui-services-pi.png" alt=""><figcaption><p>Services page — start/stop services, toggle autostart, view logs, edit configs</p></figcaption></figure>
 
 ## Services
 
-See the [Services](services.md) page for detailed documentation on each ARK-OS service.
+See the [Services](services.md) page for what each service does and which are enabled by default.
+
+## Command-Line Tools
+
+ARK-OS puts its operator scripts on `PATH` (open a login shell and run them by name):
+
+```
+mavlink_shell.py              # interactive PX4 NSH shell over MAVLink
+px4_shell_command.py <cmd>    # run a single PX4 console command
+flash_firmware.sh <fw.px4>    # flash flight controller firmware
+reset_fmu_fast.py             # reset the flight controller
+reset_fmu_wait_bl.py          # reset the flight controller into bootloader
+```
+
+## Installing and Updating ARK-OS
+
+ARK-OS is distributed as a Debian package on the [releases page](https://github.com/ARK-Electronics/ARK-OS/releases) — `ark-os-pi-bookworm` for Raspberry Pi OS based on Debian 12, `ark-os-pi-trixie` for Debian 13. The install script picks the right one automatically and is also the supported way to update. Run it from a clone of the repo on the Pi:
+
+```bash
+git clone https://github.com/ARK-Electronics/ARK-OS.git
+cd ARK-OS
+sudo ./packaging/install_ark_os.sh --ark-os-version=X.Y.Z
+```
+
+{% hint style="warning" %}
+Upgrading resets the service configuration under `/etc/ark-os/` to packaged defaults — reconfigure via the web UI afterward.
+{% endhint %}