PacketRF Operating Guide

This is the operational manual: what to actually configure on a PacketRF node and in what order to make it work as part of a real NPR network. It assumes you have already gone through Quick Start, so the device is built, flashed, bootstrapped with your admin key, and answering management.

The original NPR documentation by Guillaume F4HDK — the NPR specification and the Advanced user guide on the Hackaday project page — is the authoritative reference for the protocol itself. This page is the PacketRF-specific counterpart, focused on what an operator types and what an operator should expect to see, on PacketRF firmware specifically.

Before you transmit

Two paragraphs that everyone is tempted to skip. Please do not.

NPR uses the 70 cm amateur band. In most regions you are licensed operator on that band only if you actually are a licensed operator; in some regions there is a slot reserved for NPR-style use (e.g. the DARC 200 kHz duplex slot in Germany), in others you choose your own frequency inside the band plan. Check your local rules first. The firmware will not stop you from using a frequency you should not be on; nothing in this project tries to be your regulator.

The hardware in front of you, especially if it is a hand-wired SI4463 module, is probably clean enough on the air at low power and low symbol rate, but you should verify rather than assume. Look at the output on an SDR. Check harmonics. Add filtering between the module and the antenna if needed. Wider modulation profiles are genuinely wide. PacketRF is meant to be a friendly member of the band, and the hardware needs to be one too. See the RF reality check paragraph in Supported Hardware.

Roles: master vs slave

An NPR network has exactly one master. Everyone else is a slave (or client — the terms are interchangeable). Pick the role for this node before configuring anything else; quite a few decisions cascade from that choice.

Run a master if:

  • this is your repeater site — you have a fixed antenna, mains power, an upstream IP path, and you want to provide service to surrounding stations,
  • you want to test PacketRF as a standalone two-node setup on the bench, with another node as a slave.

Run a slave if:

  • you are joining an existing network and someone else is operating the master,
  • this is a portable or home-station node connecting to an NPR repeater somewhere else.

Most nodes are slaves. Master deployments are the smaller fraction. This guide documents both.

Configuring a slave

The good news first: slave configuration is minimal on purpose. Once a slave connects to a master, the master imposes the IP configuration of the radio side, and a lot of what you would otherwise have to set is decided for you.

What you need to set on the slave to get on the air:

  • frequency (must match the master),
  • modulation profile (must match the master),
  • radio network ID (must match the master — the NPR equivalent of CTCSS),
  • callsign (your callsign, has to be unique within the network),
  • TX power, sensibly chosen for your path,
  • client_req_size — how many IP addresses you want behind your modem; 1 is the right answer for almost everyone,
  • radio_on_at_start = yes once you are happy with the configuration.

The slave keeps a static IP configuration on np2 only as a placeholder before the radio link is up. Once the master accepts the connect, the master pushes the real IP configuration down — modem IP, client IP range, mask, gateway — and overwrites whatever was there. You do not have to align slave IP defaults to the master subnet, and trying to is a common newcomer mistake. Leave it alone.

A small example session, over a fresh USB management link:

prf-mgmt --uri coap://192.168.42.1 --admin-key default \
         /interface/np2/set \
            callsign=OKnABC-PRF \
            modulation_id=22 \
            center_frequency_mhz=434.000 \
            radio_network_id=12 \
            client_req_size=1 \
            radio_on_at_start=yes
prf-mgmt --uri coap://192.168.42.1 --admin-key default /system/reboot

After reboot, watch /interface/np2/status. A connected slave should show, within a few seconds to about a minute (depending on modulation profile and master standby state):

  • a non-empty assigned IP range on np2,
  • a non-zero connected state,
  • a small but growing TA estimate (timing advance),
  • RSSI numbers on downlink and uplink.

If it does not connect, the most common causes — in order — are: modulation mismatch, radio network ID mismatch, frequency mismatch, TX power below what the master can hear over the path, and antenna issues. Check those before suspecting firmware.

Configuring a master

Master configuration is more substantial because the master is the authority. It picks the IP plan, the modulation profile, the allocation policy, and how the rest of the network is reached.

The PacketRF master takes its NPR-side IP configuration from the pool referenced by npr1.master_pool. The factory default is pool3, a static pool covering 192.168.43.0/24 with the master at .31 and slave allocations starting at .32. That is enough for a small bench network out of the box; for a real deployment you almost certainly want to redesign the addressing.

A typical master setup involves four steps, in this order:

  1. Pick an IP plan. Decide the subnet for the NPR side, the master's own address inside it, the address range to hand out to slaves, and where the upstream router lives. The address range for slaves does not have to be aligned to a power of two — NPR allocates per-IP, so you can hand out exactly as many addresses as you actually need. Be conservative: most slaves only need one. For a worked example, see the corresponding section in F4HDK's NPR advanced user guide; the principles transfer directly to PacketRF.
  2. Configure the master pool. Edit the pool3 section (or any other pool you point npr1.master_pool at) so it covers your chosen subnet, mask, master address, gateway and slave range.
  3. Configure NPR. Edit npr1 with role = master, your callsign, the modulation profile, the center frequency, the radio network ID, and the TX power.
  4. Configure routing. The master's et1 (or us0, depending on how you built it) needs to know how to reach the upstream network — typically through a normal default route. The routing1 config section is the place that lives.

A short example for a 70 cm master at 434.000 MHz, profile 22, network ID 12, with the NPR side on 192.168.43.0/24 and the upstream router on the wired Ethernet:

# 1. master pool
prf-mgmt --uri coap://192.168.42.1 --admin-key default \
         /pool/pool3/set \
            type=static \
            ip_start=192.168.43.32 \
            ip_size=32 \
            subnet_mask=255.255.255.0 \
            gateway=192.168.43.1 \
            gateway_active=yes \
            max_allocations=8

# 2. NPR
prf-mgmt --uri coap://192.168.42.1 --admin-key default \
         /interface/np2/set \
            role=master \
            callsign=OKnABC-PRF \
            modulation_id=22 \
            center_frequency_mhz=434.000 \
            radio_network_id=12 \
            tx_power=20 \
            radio_on_at_start=yes \
            master_pool=pool3

# 3. wired side
prf-mgmt --uri coap://192.168.42.1 --admin-key default \
         /interface/et1/set mode=dhcp

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

The exact key names are subject to change as the schema evolves; if something here drifts, the schema at /schema (or prf-mgmt /schema) is the authoritative listing for the running firmware. Trust the running device, not a committed documentation file.

Choosing a modulation profile

The full discussion is in Modulation Profiles; the operational summary is short:

  • Long, weak, rural paths: use 20 or 21. They are slower but they actually work through marginal conditions.
  • Strong, well-engineered point-to-point links: 23 or 24 will give you a noticeably better experience.
  • Mobile use: stay on 11, 20 or 21. Higher symbol rates do not forgive multipath.
  • A general-purpose master that does not yet know who its slaves will be: 21 or 22 is a reasonable default. You can always retune once you have real users.

If you change profiles later, every slave has to follow. There is no way for a profile-22 slave to talk to a profile-24 master.

IP and addressing

The combined "this all looks like one Ethernet segment" feel of NPR comes from PARP — the Proxy ARP mechanism implemented on each modem. The full discussion is in Interface and Addressing Model, and the longer narrative is on uart.cz.

In operational terms:

  • All NPR modems on one network share one IPv4 subnet. The master picks it, the slaves learn their addresses from the master, the PARP machinery on each modem makes the rest look flat.
  • The default route — the way out of the NPR network into the rest of the Internet, into Hamnet, or wherever — has to live on the master side of the network. It cannot live on a slave. A slave is an access modem, not a transit point.
  • If you would rather run the network as a routed backbone instead of a pseudo-bridge, that is a legitimate choice; it just means turning PARP off and configuring routes per modem. See the same pages above for the trade-off.

MTU

NPR can carry IPv4 packets up to 1500 bytes, but performance is substantially better at MTU 750 — that size fits exactly into three NPR radio frames at the segmentation boundary. F4HDK's recommendation in the original advanced guide stands: if you are chasing throughput, set MTU to 750 on the host attached to the client modem (or use MSS clamping at 710 if you are routing through an upstream router).

Daily operations

A few notes from running PacketRF nodes for a while.

  • The master should be rebooted on a regular cadence. Long uptimes are not a virtue on a constrained device; nightly or weekly reboots are good hygiene. PacketRF has a watchdog and is designed to come back up cleanly, but a planned reboot is always nicer than a panic.
  • /system/mem reports allocator-level memory separately for FreeRTOS, newlib and lwIP. If something is leaking, it shows up here clearly. Aggregate "free heap" numbers hide the actual source.
  • /system/status includes the schema id and the device serial number. Use the schema id to detect when host-side automation has drifted from the firmware running on the device.
  • Adding more admin keys is sensible. Any one of them can manage the device. Losing one is then an issue but not a disaster.

Recovery scenarios

These belong here, not in the quick-start.

Lost admin key

If you have lost the only admin key, the device is yours physically but you cannot manage it. The clean recovery path is:

  1. factory-reset the configuration storage (or full erase + reflash),
  2. boot the device — it will come up in bootstrap-required mode,
  3. generate a new admin key on the host,
  4. bootstrap normally, as in Quick Start.

Suspected key compromise

Treat it as a security incident, not as a configuration issue:

  1. take the device out of trusted operation immediately,
  2. erase the configuration and key material,
  3. generate a new admin key on the host,
  4. bootstrap a fresh trust state,
  5. reapply intended configuration.

If the same admin key was used across several devices, repeat the process on every device the key reached. The whole point of admin-key bootstrap is that this is straightforward to do; do it.

Master changed addressing

If the master's IP plan changes, slaves notice automatically — the master pushes the new IP configuration on connect, and the slaves just follow. The hosts behind the slaves are a different question: they get their addresses through whatever DHCP or static configuration you set up locally, and you have to update those yourself if the slave's IP range moved.

Where to read next