Wenet TX Payload Instructions
Last Updated: 2024-07-21
This page documents the steps required to set up a Raspberry Pi (2A, Zero, ZeroW) as a Wenet transmitter. These instructions assume that you already have a Raspbian installation set up on a Raspberry Pi, and have SSH access to it.
WARNING - Wenet still depends on the Python PiCamera library, which is starting to be deprecated. For now support is still available in Raspbian bullseye ("Raspberry Pi OS (Legacy, 32-bit), Lite"), but I'll look into updating to whatever comes next. There's some initial support for the PiCamera2 library now in this repository (wenet_picamera2_gps.py), though it should be treated as 'very very beta'.
IMPORTANT NOTE: On Raspberry Pi units with Bluetooth (Pi 3, Pi Zero W), you will need to enable the pi3-disable-bt hardware overlay. Refer to this guide (about halfway down the page) for more information. In short, you will probably want to add the dtoverlay=pi3-disable-bt line to your /boot/config.txt file.
The Wenet codebase currently supports using either a HopeRF RFM22B or a HopeRF RFM98W radio module as the FSK modulator. The RFM22B is now obsolete, so the RFM98W option is probably better.
UpuTronics sells a suitable RFM98W Raspberry Pi shield, with shield sizes suitable for a RPi2 Model A, and a Pi Zero/W.
In both cases, the shield must be modified with the addition of a single wire, connecting the DIO2 pin (GPIO2 on the RFM98W) to the TXD pin (pin 8) on the Raspberry Pi's header. We use this wire to modulate the RFM98W in 'direct asynchronous' 2-FSK mode.
The above image shows how this can be implemented on one of the UpuTronics shields. A length of re-work wire is used to join the two pins, and is held down with silicone.
Adafruit also sell a suitable shield which is known to work with Wenet. Make sure you buy the "LoRa RFM96W 433 MHz" version. This board also has easier to solder pads for connecting the RPi TX line to the DIO2 input on the module. Note that this board uses SPI CE1, which will need to be configured later.
See the following diagram for details on what has to be connected on the board for Wenet operation:
The Wenet code is intended to be used with a PiCamera. Both the v1, v2 and HQ cameras have been used and work well.
The Wenet transmitter code can optionally get payload position information from a uBlox GPS module (accessed via USB-Serial), and overlay the position on the downlinked image. This must be a uBlox module, as we use uBlox protocol to ensure the module is in airborne mode.
USB-connected uBlox GPS units are available fairly cheaply on eBay, under the name 'VK-172 G-mouse'. These have a uBlox 7 chipset (or at least a very good clone of one...) and have been tested up to 37km altitude. They appear as an ACM serial device, and later on in the setup process a udev rule is added to provide a symlink to the serial port at /dev/ublox.
Mount them away from everything else in your payload box (especially the camera cables!) to avoid GPS lock issues due to RFI.
Install the required dependencies from apt-get using:
$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install git build-essential vim python3-dev python3-numpy python3-picamera python3-crcmod python3-spidev python3-pip python3-serial python3-rpi.gpio imagemagick
We need fsphil's 'slow-scan digital video' compression utility available on the system. From the home directory, run:
$ git clone https://github.com/fsphil/ssdv.git
$ cd ssdv
$ make
$ sudo make install
Run:
$ cd
$ git clone https://github.com/projecthorus/wenet.git
$ sudo cp ~/wenet/tx/99-usb-serial.rules /etc/udev/rules.d/
In turn, this:
- Grabs a copy of the Wenet git repository
- Copies udev rules to be able to easily access a uBlox GPS unit at /dev/ublox
Finally, we need to compile the LDPC Encoding library:
$ cd ~/wenet/tx/
$ gcc -fPIC -shared -o ldpc_enc.so ldpc_enc.c
Run sudo raspi-config, and under Interfacing options, enable:
- Camera (This is called Legacy-Camera in Raspbian bullseye)
- SPI
- Serial (When prompted, set 'Enable Login Shell' to NO, and 'Serial Port Hardware Enabled' to YES.)
If required, the attached GPS unit can be used to synchronise the system clock, via NTPd's Shared Memory Interface.
To use this, we need to grab the ntpdshm python library from pip, and also install the NTPD server:
$ sudo apt-get install ntp
$ sudo pip3 install ntpdshm
The NTP config file (/etc/ntp.conf) then need to be edited, and the following lines added at the end of the file:
server 127.127.28.2 minpoll 4 maxpoll 4
fudge 127.127.28.2 time1 0.09 flag1 1 refid PYTH stratum 2
Restart NTPD using sudo systemctl restart ntp
This section assumes you have a Wenet Receiver available.
Before testing with a camera, is is useful to transmit some test images to check the FSK modulator is working. The test_images directory contains a set of test images that you can transmit. Run:
$ cd ~/wenet/test_images
$ python3 compress_test_images.py
This will produce SSDV-compressed versions of the JPEG images, and may take a few minutes to run (depending on the RPi board in use).
Now, we need to start up the radio module:
$ cd ~/wenet/tx
$ python3 init_rfm98w.py --frequency <freq>
Replace <freq> with a frequency in MHz that you are licensed to use. Note that the transmitted signal is over 300 kHz wide, so is in breach of the ISM regulations in most countries. Here in Australia, we run our Wenet payloads on 443.500 MHz, under an Advanced amateur radio licence, though it's possibly to run this with even a Foundation level license.
Depending on your LoRa shield, your module might be using a different chip-select line than the default (CE0). To select the other chip-select line, you can add --spidevice 1 to the command above. Note that you will also need to add this in any startup scripts you might use later.
A carrier should now be transmitted a bit above the supplied frequency.
We can now start transmitting the test images using:
$ python3 tx_test_images.py
Hopefully images will start appearing on your Wenet receiver!
To check that the RPi can communicate with an attached uBlox GPS unit, run:
$ cd ~/wenet/tx
$ python3 ublox.py /dev/ublox
A large amount of JSON objects should be written to the terminal, containing the various GPS parameters (latitude, longitude, time, etc)
If you set up NTPD earlier, you can run ntpq -p, and you should see a SHM(2) entry in the list of NTP peers.
The WenetPiCam.py file contains a test script which will capture and transmit images. This can be run with:
$ python3 WenetPiCam.py YOURCALL
Debug information on the scripts current actions will be written to the terminal. Images should be captured, re-sized, and transmitted via the FSK modulator.
You can get a 'live' video stream from your camera over a network by using the raspivid utility, which can be started with:
$ raspivid -t 0 -l -o tcp://0.0.0.0:3333
Access the stream by opening VideoLan Player (VLC) and opening a network address of: tcp/h264://your.pi.ip.address:3333
If you're worried about Raspbian locking up, you can setup a hardware watchdog. Some information on this is available here: https://diode.io/raspberry%20pi/running-forever-with-the-raspberry-pi-hardware-watchdog-20202/
The tx_picam_gps.py Python script will automatically capture images and GPS data, overlay GPS position information at the top of the image, and transmit images. Note that this needs to be run as root, as it will try and write into NTPD shared memory by default to set the system time, or as a fallback, will just use timedatectl to set the system time on first GPS lock.
The start_tx_systemd.sh script in ~/wenet is designed to be started up by systemd on boot, and will enable and configure the radio module, then start tx_picam_gps.py. Edit this file and adjust the MYCALL and TXFREQ parameters as necessary, and any changes as needed as described in the script.
The systemd service file ( wenet_tx.service) shouldn't need any changes if you are running as the 'pi' user. If you're running as a different user, you will probably need to change the paths (/home/pi/wenet) in the .service file.
Install the systemd service file using:
$ sudo cp wenet_tx.service /etc/systemd/system/
Test it using:
$ sudo systemctl start wenet_tx
... which will start up the wenet transmitter, and start capturing and sending images. Confirm you can receive this using a local Wenet receiver.
The Wenet transmit process will by default write any log output to /home/pi/wenet/tx/debug.log (this output mirrors the text messages which are also transmitted through the Wenet downlink). You can follow this log by running:
$ tail -f /home/pi/wenet/tx/debug.log
2024-07-21T05:25:29.238885,TXing Text Message #238: PiCam Debug: Capturing Image 1 of 5
2024-07-21T05:25:30.371565,TXing Text Message #239: PiCam Debug: Capturing Image 2 of 5
2024-07-21T05:25:31.473176,TXing Text Message #240: PiCam Debug: Capturing Image 3 of 5
2024-07-21T05:25:32.777074,TXing Text Message #241: PiCam Debug: Capturing Image 4 of 5
2024-07-21T05:25:33.903736,TXing Text Message #242: PiCam Debug: Capturing Image 5 of 5
2024-07-21T05:25:35.170286,TXing Text Message #243: PiCam Debug: Choosing Best Image.
2024-07-21T05:25:35.190281,TXing Text Message #244: PiCam Debug: Copying image to storage with filename ./tx_images//20240721-042529Z_picam.jpg
2024-07-21T05:25:35.370014,TXing Text Message #245: PiCam Debug: Running Image Post-Processing
2024-07-21T05:25:35.376563,TXing Text Message #246: Adding overlays to image.
... many more lines
To start the wenet_tx service on boot, run:
$ sudo systemctl enable wenet_tx
Note that it will take ~30-40 seconds after boot for transmissions to start.
If for whatever reason you need to stop the transmitter processes, you can run:
$ sudo systemctl stop wenet_tx
Some further configuration may be required depending on your payload setup. The main things you may want to change are the capture & transmit resolutions, and whether horizontal/vertical flip is used (depends on your camera orientation). These settings are all around line 138.