LollosoSi / rf24tunlink

Point to Point TUN link via NRF24L01 radio modules
0 stars 1 forks source link

rf24tunlink

Point to Point TUN link via NRF24L01 radio modules

Video or audio streaming demo

Video or PTT

Preamble

This software is distributed free of charge under GNU GPLv2 license.
If you found my work helpful, consider supporting it through a donation

Index

How it works

Upon launch, the program creates the TUN interface (arocc) and sets up for the selected radio.
The code structure is designed with expandability in mind, enabling fast addition of different radio modules, packetizers and packet sources.
Scheme: rf24tunlink components

There are 3 core components:

TUN handlerHandles packets from the packetizer, into the linux system and vice versa. Sets everything about the system interface (be it TUN, UART or else).
PacketizerReceives packets from the TUN handler, splits them into segments suitable for radio transfer and recomposes them on the latter end of the bridge.
RadioHandles everything regarding a particular radio. Receives segments from the packetizer and sends them through the medium. Reads segments from the medium and sends them to the packetizer.

You must select each component using the config files (look into the presets folder) You must also declare which is the primary and secondary radio.
Almost everything can be done through the config files.
Primary and secondary have these addresses respectively: 192.168.10.1 and 192.168.10.2 (unless you change them)

Notable setups

two-RF24The primary radio streams their packets (and if configured, empty packets) and reads the Ack Payloads of the secondary radio.
Note: A good portion of the total received packets are discarded automatically from the modules in the two-RF24 setup, just because there usually are a couple corrupted bytes out of 32.
four-RF24Full duplex communication with higher performance compared to the two-RF24 setup.
Each end of the bridge has two NRF24L01 radio modules.
The four-RF24 setup is strongly recommended because it allows for advanced error correction, meaning theoretically larger range.
Pico RF24 adapterYou can enable non-raspberry debian computers to connect to the bridge by building a pico adapter: it's a raspberry pico board with two NRF24L01 modules and a program to exchange settings and packets with rf24tunlink.
Works via USB

You should be able to ping each other when everything is set up correctly. Test the bridge speed using iperf.

Error Correction


Here is a representation of the errors in close range, before RS ECC was implemented
Just out of my room
Here is one test done after implementing the RS ECC
RS ECC
Note that error correction is available only for the four-RF24 setup.
Unfortunately for two-RF24 you cannot disable ack payloads unless you intend to send a one way stream (unsupported at the moment)

Performance

Results depend on the configuration used.
For a four-RF24 setup, with 30 bytes of data and 2 bytes for ECC:
Throughput (close range): 1.2Mbps
Ping: 2-4ms

A realistic expectation would be using more bytes for ECC and streaming continously no more than 200-400Kbps. You will experience increased ping and/or dropped packets if signal is lost for too long.

PCB

A PCB is in the works and will be released later this year.
Meant for a stable point to point communication or a remote-RC car/drone setup. Have a look at this announcement page
Sneak peek:

Installation (Raspberry Pi)

From here, an automated install script is available:
wget -qO /tmp/install_script.sh https://raw.githubusercontent.com/LollosoSi/rf24tunlink/main/install_script.sh && bash /tmp/install_script.sh

Usage

Note: During the transition to version 2, not all features might be available.
CSV exporting or the bridge info are some of the unfinished features.

You can generate a text file with all the available settings (most have comments with explanations in them) by running the program with no arguments: ./rf24tunlink2.
Just create your files or use the ones in presets.
Presets might not always be updated and I might change them as a result of testing, it's a good idea to have a look into them when downloading for the first time.

Examples of config files can be found in the presets folder.
Once everything is tuned to your liking, run the program with all your files as arguments.
Here is an example which runs the four-RF24 setup:
Primary device:
sudo ./rf24tunlink2 presets/tunlink_config.txt presets/harq_config.txt presets/radio_config.txt presets/primary
Secondary device:
sudo ./rf24tunlink2 presets/tunlink_config.txt presets/harq_config.txt presets/radio_config.txt presets/secondary
This is cool beacuse you can edit your configs once then sync everything in one folder.

Systemd service

Use this after you've found and tested a working configuration
Install the service to run rf24tunlink at boot by running ./installservice.sh primary/secondary
A file named .progconf will be created. This one contains the config file paths. Edit as necessary.
Note: rs_config and radio_pb_config are used to change the data bytes, ECC bytes and the NRF24L01 modules data rate and power on the fly.
You lose this ability if these lines are removed.
To change these settings during execution, use the scripts
./power_bitrate_config.sh (0 to 3: power) (0 to 2: bitrate) and ./ecc_config.sh (data) (ecc) with the correct arguments.
Data+ECC should always be 32 or less if using NRF24L01. Performance will be worse if you use less than 32 bytes total.

Shortcuts to control the service are provided: ./stopservice.sh ./startservice.sh ./servicestatus.sh ./restartservice.sh

Wiring

You can select CE, CSN and IRQ based on your project needs.

Radio 0
CE: GPIO 25
CSN: GPIO 8 (CE 0) - write 0 in the config for CE 0, or 1 for CE 1
MISO: GPIO 9
MOSI: GPIO 10
SCK: GPIO 11
IRQ: GPIO 5
Radio 1
CE: GPIO 26
CSN: GPIO 18 (CE 1.0) - write 10 in the config (for CE 1.1, write 11. And for 1.2, write 12)
MISO: GPIO 19
MOSI: GPIO 20
SCK: GPIO 21
IRQ: GPIO 6

Stability advice

Checklist for long range links

In order to land a long range communication you must check a couple things first:

Setting up video streaming

I've tested this command for streaming to the primary device of the link:
rpicam-vid -t 0 --inline --level 4.2 -b 50k --framerate 24 --width 480 --height 360 --codec libav --libav-video-codec h264_v4l2m2m -o udp://192.168.10.1:5000
Edit bitrate (-b 50k) and resolution (--width 480 --height 360) to fit your needs.
Consider the worst case scenario first: must work in 250Kbps modulation, then tune it up.
Later on, we could always consider including some kind of speed negotiation based on packet latency and signal losses.

Optional: in the receiver RPi, reroute the packets to multicast in the local network:
sudo socat udp-listen:5000,reuseaddr,fork udp-datagram:239.255.0.1:5001,sp=5000
Note that you can't do this in things like phone hotspots and these might add latency. It's best to use your home network or use the receiving RPi as access point

And in the machine(s) where you want to watch the stream:
ffplay udp://@239.255.0.1:5001 -fflags nobuffer -flags low_delay -framedrop
Adjust the address if you aren't using multicast.

RPi as hotspot

To enable RPi as hotspot I put together this bash script and seems to work with low enough latency (RPi 4) ``` #!/bin/bash # Stop dnsmasq service systemctl stop dnsmasq # Delete any existing connection named TEST-AP nmcli con delete TEST-AP # Add a new Wi-Fi connection in Access Point mode nmcli con add type wifi ifname wlan0 mode ap con-name TEST-AP ssid TEST autoconnect false # Configure Wi-Fi settings nmcli con modify TEST-AP wifi.band bg nmcli con modify TEST-AP wifi.channel 3 nmcli con modify TEST-AP wifi.cloned-mac-address 00:12:34:56:78:9a # Configure Wi-Fi security nmcli con modify TEST-AP wifi-sec.key-mgmt wpa-psk nmcli con modify TEST-AP wifi-sec.proto rsn nmcli con modify TEST-AP wifi-sec.group ccmp nmcli con modify TEST-AP wifi-sec.pairwise ccmp nmcli con modify TEST-AP wifi-sec.psk "mypassword" # Configure IP settings nmcli con modify TEST-AP ipv4.method shared ipv4.address 192.168.4.1/24 nmcli con modify TEST-AP ipv6.method disabled # Bring up the connection nmcli con up TEST-AP # Set the transmit power of the wlan0 interface to a low value (e.g., 1 dBm) iw dev wlan0 set txpower fixed 100 # Enable multicast on wlan0 interface # ip link set dev wlan0 multicast on ip route add 224.0.0.0/4 dev wlan0 ```

Dependencies: RF24 library, CMake, pigpio