Quick Start

1. What you need

• A Pico 2 plus an SI4463 module, or an RF Baseboard Rev A
• A 70 cm antenna appropriate for your module
• A USB cable (USB-C if you are using RFBB-A)
• A 3.3 V UART adapter — strictly speaking optional on the Pico 2 but strongly recommended for the first boot, because the bootstrap code is printed on the debug log
• Python 3.11 or newer on the host
• Either pipx (recommended) or a virtualenv to install the management tool into

You do not need the source tree, a C++ toolchain, or CMake to bring up a node from a release. Building from source is a development activity and lives in the project README; this page walks through the everyday user path instead — download the prebuilt artifacts, flash them, and start managing the device.

2. Get the firmware and management tool

Open the GitHub Releases page and download two things from the latest release:

• the firmware UF2 for your board:
  • packetrf_fw-pico2-release.uf2 for a Raspberry Pi Pico 2,
  • packetrf_fw-rfbb-a-release.uf2 for the RF Baseboard Rev A,
• the management tool wheel:
  • packetrf_mgmt-<version>-py3-none-any.whl.

The UF2 is the firmware image you will copy onto the device in the next step. The wheel is the host-side Python package that gives you the prf-mgmt command; it gets installed in step 5.

3. Flash the firmware

Flashing on RP2350 is drag-and-drop. No tools, no picotool, no serial bootloader incantations:

1. Hold the BOOTSEL button on the board.
2. While holding it, plug the USB cable in (or press RESET if the board is already powered).
3. The board will appear on your host as a USB mass-storage volume — typically named RP2350 or similar.
4. Drag the packetrf_fw-*.uf2 file you downloaded onto that volume.
5. The board reboots automatically once the file has been copied. The mass-storage volume disappears, and the device comes up running PacketRF.

That is the whole flashing procedure for users. There is no separate "erase" step in this path; copying a new UF2 replaces the firmware atomically.

4. Watch the first boot

A freshly flashed device does not go straight into normal runtime. PacketRF requires an explicit bootstrap before it will route traffic, run the radio, or generally trust anyone. That is what step 5 is about; for now you just want to see the bootstrap code.

Connect a 3.3 V UART adapter to the debug UART and open a terminal at 115200 8N1. On Pico 2 the UART is on physical pin 1 (TX), pin 2 (RX), pin 3 (GND); on RFBB-A it is on header J1. Power the board and you will see, within a few seconds, repeated lines like:

[     10072 ms] [ERROR] device not provisioned, bootstrap code=1000, install first admin key

The four digits — 1000 in the example above — are the bootstrap code. You will need them in step 5.

On RF Baseboard hardware the same code is also displayed on the four LEDs next to the USB-C connector, MSB on the left. So 1000 shows up as ON / OFF / OFF / OFF. That means RFBB-A users do not strictly need the UART adapter to bootstrap, although attaching one for the full debug log could still be usefull.

Note that PacketRF exposes two different serial paths and they are not the same thing:

• the debug UART described above, on the breakout pins, used by the firmware logger,
• a USB CDC ACM serial path, intended for management with prf-mgmt over the local serial transport.

The bootstrap code only needs the debug UART; the management transport is described in step 5.

5. Install the management tool

PacketRF firmware is talked to from the host using prf-mgmt. The same tool handles the bootstrap install, day-to-day administration, interface configuration, schema discovery and so on. It does not matter whether you reach the device over the local USB serial management channel or over IP via CoAP — the commands are the same. The full reference is the Management CLI Guide; what follows is enough to get past first boot.

For users running off a release, the recommended install path is via pipx so the tool ends up isolated and globally callable:

pipx install ./packetrf_mgmt-<version>-py3-none-any.whl

If you prefer a plain virtualenv:

python -m venv .venv
. .venv/bin/activate
python -m pip install ./packetrf_mgmt-<version>-py3-none-any.whl

If you are working from the repository sources, the easiest way to get an interactive shell with auto-detected serial URI is:

make mgmt

That runs uv sync --project tools/mgmt under the hood and starts prf-mgmt shell. To run individual commands without entering the shell:

uv run --project tools/mgmt prf-mgmt --help

The walkthrough below is written as prf-mgmt …; if you are running from sources, prepend uv run --project tools/mgmt everywhere and the commands are otherwise the same.

Generate your admin key

The first thing to do — once, not once per device — is to generate your admin keypair:

prf-mgmt admin-key generate default

This creates a keypair called default. The name is just a local alias for your convenience; you can call it whatever you want, and you can have more than one. Keys are stored under ~/.config/packetrf/. Treat that directory like an SSH private key directory: it is the credential that will let you administer your devices, and there is no remote recovery path if you lose it.

6. Bootstrap the device

You now have a device printing a bootstrap code, and a host with an admin key. The bootstrap install is one signed request that says "this is my public key, please install it as the first trusted admin key", along with the displayed bootstrap code as proof of physical access:

prf-mgmt --uri serial:/dev/ttyACM0 --admin-key default bootstrap 1000

Replace 1000 with the actual code shown by your device, and /dev/ttyACM0 with whatever serial path the device shows up under on your host. (On Linux it is typically /dev/ttyACM0 for the first device; on macOS it is something like /dev/tty.usbmodemNNNN.)

If everything checks out — bootstrap mode active, code matches, nonce fresh, signature verifies — the debug log will show:

[    212804 ms] [WARNING] system: reboot scheduled in 600 ms by control request
[    213498 ms] [WARNING] system: rebooting now (requested by control interface)

The device then:

1. stores your public key as trusted and admin,
2. schedules a reboot,
3. comes back up in normal runtime — radio, networking, the full command tree.

What happens under the hood, and the exact list of checks the firmware runs before accepting a bootstrap install, is documented in the Control module page, in the Bootstrap mode and Bootstrap install request sections.

7. Talk to the device

After bootstrap you can talk to the device either over the local USB serial management transport or over IP using CoAP. The default USB CDC-NCM service interface (us0) lives on 192.168.42.1, allocated from pool2, so the IP path works on a default device without any extra configuration.

A small selection of useful commands:

# health check
prf-mgmt --uri serial:/dev/ttyACM0 /system/status
prf-mgmt --uri coap://192.168.42.1 /system/status

# what interfaces are up, in what state
prf-mgmt --uri serial:/dev/ttyACM0 /interface/list

# look at the NPR side
prf-mgmt --uri serial:/dev/ttyACM0 /interface/np2/status

# read and edit a config section (admin key required for writes)
prf-mgmt --uri coap://192.168.42.1 /interface/us0/config
prf-mgmt --uri coap://192.168.42.1 --admin-key default \
         /interface/np2/set callsign=OKnABC-PRF

# device public key, for adding into a host trust store
prf-mgmt --uri serial:/dev/ttyACM0 /crypto/device

# clean reboot
prf-mgmt --uri coap://192.168.42.1 --admin-key default /system/reboot

There is more in the Management CLI Guide and beyond that in the PacketRF Operating Guide.

8. From here

You now have a node that boots, runs the radio, accepts authenticated management, and behaves like a normal IP interface from your host. The reasonable next steps depend on what you want to do:

• If you want to actually use the radio: PacketRF Operating Guide walks through master vs slave configuration, modulation profile choice, address allocation, and the things that actually go wrong on first deployment.
• If you want to understand how NPR behaves: read New Packet Radio in PacketRF, Modulation Profiles, Managed TDMA, and Latency and Ping Expectations.
• If you want to understand how the firmware is built: start with Platform Architecture.