> ## Documentation Index
> Fetch the complete documentation index at: https://docs.t3gemstone.org/llms.txt
> Use this file to discover all available pages before exploring further.

# PX4

> PX4 Autopilot

<Warning>
  PX4 support for Gemstone is still in the development phase. It runs on the
  main-domain R5F core, and some peripherals on the board, such as CAN Bus, are
  not yet available.
</Warning>

PX4 is an open-source autopilot platform for drones and other unmanned vehicles.
It provides a complete flight-control stack, from low-level sensor drivers up to
vehicle control and mission execution. On the Gemstone board, PX4 runs on the
R5F cores on top of NuttX, using the same custom `t3-gem-o1` configuration
created for the bare NuttX build.

Unlike a standalone NuttX build, PX4 vendors both NuttX and its application
framework as git submodules. A recursive clone therefore pulls the correct,
Gemstone-tuned NuttX automatically, so there is no need to download or build
NuttX separately.

## 1. Compilation

### 1.1. Installing Dependencies and Toolchain

PX4 is compiled with the `gcc-arm-none-eabi` cross‑compiler for the ARM
Cortex‑R5F cores, and its build system additionally relies on a set of Python
tools such as `kconfiglib`, `empy` and `jinja2`.

On Ubuntu/Debian systems, install the toolchain and the general prerequisites
with the package manager:

```bash theme={"system"}
sudo apt update
sudo apt install git make cmake ninja-build gcc-arm-none-eabi python3-venv
```

Because recent Debian/Ubuntu releases restrict system‑wide `pip` installations,
install the Python tools into a virtual environment:

```bash theme={"system"}
python3 -m venv ~/px4-venv
source ~/px4-venv/bin/activate
pip install -r Tools/setup/requirements.txt
```

The `requirements.txt` file lives inside the PX4 source tree, so run the
`pip install` step after downloading the sources (section 1.2). Activate the
environment with `source ~/px4-venv/bin/activate` in every new shell before
building.

### 1.2. Downloading Source Codes

PX4 references the Gemstone NuttX and NuttX‑apps as git submodules, so the
sources are downloaded with a single recursive clone:

```bash theme={"system"}
# Clone PX4 together with its submodules
git clone --recursive https://github.com/t3gemstone/PX4-Autopilot.git

# Change to your main working directory
cd PX4-Autopilot
```

The `--recursive` flag checks out the correct NuttX (the Gemstone `px4` branch)
and NuttX‑apps into the `platforms/nuttx/NuttX` directory, so a separate NuttX
download is not required. If you cloned without `--recursive`, fetch the
submodules afterwards with `git submodule update --init --recursive`.

### 1.3. Compiling the Project

PX4 builds a specific board target directly, so no separate configuration step
is required. With the Python environment from section 1.1 active, compile the
Gemstone board image:

```bash theme={"system"}
make t3gemstone_o1_default
```

This performs a parallel build and produces
`build/t3gemstone_o1_default/t3gemstone_o1_default.elf` (the image loaded onto
the R5F core) along with `.bin` and `.px4` files.

## 2. Running

Like the bare NuttX image, PX4 runs on the main-domain R5F core and is loaded
from Linux or U-Boot using the `remoteproc` mechanism. While PX4 runs on the R5F
core, Linux continues to run on the A53 cores.

<Tip>
  To use the `remoteproc` mechanism in U-Boot, you can refer to the [2.8. Running the Compiled Project in U-Boot](/en/boards/o1/peripherals/mcu#2-8-running-the-compiled-project-at-the-u-boot-stage)
  section.
</Tip>

Program files to be loaded onto the cores via remoteproc must be copied to the
`/lib/firmware` directory with predefined names. At system startup, the
remoteproc mechanism will automatically load the programs onto the relevant
cores. Follow the steps below to run PX4 using remoteproc.

1. Copy the `build/t3gemstone_o1_default/t3gemstone_o1_default.elf` file
   resulting from the compilation to the `/lib/firmware` directory with the
   name `j722s-main-r5f0_0-fw`.
2. Reboot the board.
3. You can access NuttShell by connecting a USB-to-TTL device to the
   UART-MAIN1's GPIO-14 (TX) and GPIO-15 (RX) pins on the 40-pin HAT.
4. From the opened `nsh` console you can inspect the running system with
   commands such as `ver all`, `top`, and `uorb status`.

## 3. Using the Sensors

The on‑board InvenSense ICM‑20948, a 9‑axis IMU with an accelerometer,
gyroscope and an integrated AK09916 magnetometer, is connected to the R5F over
SPI. Start its driver from the `nsh` console:

```bash theme={"system"}
nsh> icm20948 -s -b 1 -c 3 -M start
```

Here `-s` selects the SPI interface, `-b 1` the SPI bus, `-c 3` the
chip‑select, and `-M` additionally enables the magnetometer. Once the driver is
running, you can stream the live sensor data through PX4's uORB middleware with
the `listener` command:

```bash theme={"system"}
nsh> listener sensor_accel
nsh> listener sensor_gyro
nsh> listener sensor_mag
```

To observe the overall system, `uorb top` lists the publication rates of all
active topics and `work_queue status` shows the timing of the driver's work
queue.