Skip to content

Operating System

LightForce runs a minimal Linux distribution optimized for reliability and low overhead. The root filesystem is intentionally immutable to ensure the device boots into a known-good state after power cycles.

Filesystem

/
├── boot/                                  # Mounted boot partition
│   ├── Image                              # LightForce OS image
│   ├── *.dtb                              # CM5 related device-tree blobs
│   ├── cmdline.txt                        # Linux kernel command line arguments
│   ├── config.txt                         # CM5 bootloader configuration file
│   └── overlays/                          # Linux device-tree overlay files
├── disk/                                  # Mounted NVMe (non-volatile) partition
│   ├── data/                              # Logs from the flight data recorder
│   ├── log/                               # System and service logs
│   ├── param/                             # Application parameters
│   └── sv/                                # User services
├── etc/                                   # Various OS and services configurations
│   ├── env/                               # Default environmental variables
│   ├── inst/                              # Default LightForce instances
│   │   ├── generic/                       # Generic platform
│   │   │   └── ...                        # Runit service definitions
│   │   ├── fox_air/                       # Fixed wing glider instance (air unit)
│   │   │   └── ...                        # Runit service definitions
│   │   └── fox_gnd/                       # Ground station unit
│   │       └── ...                        # Runit service definitions
│   ├── rc/                                # Init scripts
│   ├── sv/                                # Runit services
│   ├── sv.d/                              # System services
│   └── ...
├── oxc/                                   # LightForce default applications
└── ...

Two writable partitions are used in addition to the immutable root:

  • /boot (mounted read-only by default) — contains the kernel, device trees and boot configuration. To modify this partition, remount it read-write from a device shell:
mount -o remount,rw /boot
  • /disk (read-write) — stores persistent data such as service configuration, logs and recorded flight data.

LightForce applications communicate via ZeroMQ (ZMQ) sockets using a publisher–subscriber pattern.

Services

Applications are typically run as supervised services using runit. Service definitions live in several locations:

  • /etc/sv.d/ — system-level services (e.g. chronyd, syslogd, watchdogd).
  • /etc/inst/ — instance-specific application sets for different device roles.
  • /disk/sv/ — user-defined services (persistent across reboots).

Running applications as services provides automatic supervision, centralized logging to /disk/log, and simple lifecycle commands:

sv up SERVICE
sv down SERVICE
sv restart SERVICE
sv status /etc/sv/*

Service logs are available under /disk/log/<service>/current and are rotated automatically.

Parameters

Many applications are configured via parameter files stored in /disk/param. Parameters enable reusing the same binary across different aircraft types and mission profiles. Edit parameters on-device or via your deployment workflow.

Troubleshooting

This section provides diagnostic steps for connectivity issues and the official procedure for recovering a device that has become unresponsive or failed to boot.

Initial Connectivity Diagnostics

If the LightForce unit is powered but appears unresponsive to the primary ground control station (GCS), first verify network connectivity via the integrated management interfaces.

When connected via USB-C or Ethernet, the LightForce unit assigns itself a static management IP. You can test the core system responsiveness by attempting to establish a Telnet connection:

  • USB-C Connection: Attempt to connect to 10.0.0.1
  • Ethernet Connection: Attempt to connect to 10.0.1.2

If you can reach the device via Telnet, the core OS is functional, and the issue likely resides in the flight stack configuration or peripheral wiring.

Recovering an Unresponsive Device (eMMC Recovery)

If the device fails to boot entirely or the filesystem has become corrupted, you can force the internal CM5 (Compute Module 5) into a low-level USB boot mode to re-flash the onboard eMMC storage.

Prerequisites

  • Host Utility: Install the rpiboot tool on your host computer. Instructions can be found at the Raspberry Pi usbboot GitHub repository.
  • Imaging Tool: Download a disk imaging utility such as Raspberry Pi Imager, dd, or a native OS disk utility.
  • System Image: Ensure you have the latest LightForce .img or Image file provided by our technical support.

Recovery Procedure

  1. Enter Bootloader Mode: Locate the physical Boot Button on the LightForce unit. Press and hold the button while connecting the USB-C cable from the unit to your host computer.
  2. Initialize the Connection: On your host computer, execute the rpiboot utility. This will push the necessary drivers to the CM5 and mount the internal eMMC as a standard mass storage device (removable drive).
  3. Identify the Drive: Once rpiboot completes, your operating system should recognize a new drive.
  4. Flash the Image: Open your imaging tool, select the LightForce system image, and target the newly mounted eMMC drive.
  5. Cycle Power: Once the flashing process is 100% complete, disconnect the USB-C cable and perform a hard power cycle on the LightForce unit to boot into the fresh OS.

Ensure you have selected the correct drive to avoid accidental data loss on your host machine.