RAK811 Python 3 library for Raspberry Pi
About
RAK811 Python 3 library and command-line interface for use with the Raspberry Pi LoRa (p)HAT.
The library exposes the RAK811 module AT commands as described in the following documents:
- RAK811 Lora AT Command User Guide V1.5 for modules with the V2.0.x firmware.
- RAK811 AT Command Manual V1.0 for modules with the V3.0.x firmware.
The command-line interface exposes all API calls to the command line.
Requirements
- A Raspberry Pi!
- A RAK811 LoRa module (PiSupply IoT LoRa Node pHAT for Raspberry Pi / RAK811 WisNode - LoRa)
- On the Raspberry Pi the hardware serial port must be enabled and the serial console disabled (use
raspi-config) - The user running the application must be in the
dialoutandgpiogroups (this is the default for thepiuser)
Install the rak811 package
The package is installed from PyPI:
sudo pip3 install rak811The pip3 command is part of the python3-pip package. If it is missing on your system, run:
sudo apt-get install python3-pipPiSupply provides detailed instructions for configuring your Raspberry Pi.
Usage
Quick start with The Things Network
Identify your device
If you don't know the firmware level of you module run the following commands:
rak811 hard-reset
rak811 versionFor V2.0.x firmware use the rak811 command and python module, for V3.0.X use rak811v3 command and rak811_v3 python module.
Register your device
Register you device on TheThingsNetwork using the unique id of your RAK811 module (Device EUI).
You can retrieve your Device EUI with the following command (V2.0.x):
rak811 hard-reset
rak811 get-config dev_euiNote: the rak811 hard-reset command is only needed once after (re)booting your Raspberry Pi to activate the module.
or (V3.0.x):
rak811v3 set-config lora:join_mode:0
rak811v3 get-config lora:status | grep DevEuiHello World
Send your first LoRaWan message wit the following python code snippet:
(The App EUI and App Key are copied verbatim from the TTN console)
#!/usr/bin/env python3
# V2.0.x firmware
from rak811.rak811 import Mode, Rak811
lora = Rak811()
lora.hard_reset()
lora.mode = Mode.LoRaWan
lora.band = 'EU868'
lora.set_config(app_eui='70B3D5xxxxxxxxxx',
app_key='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
lora.join_otaa()
lora.dr = 5
lora.send('Hello world')
lora.close()#!/usr/bin/env python3
# V3.0.x firmware
from rak811.rak811_v3 import Rak811
lora = Rak811()
lora.set_config('lora:work_mode:0')
lora.set_config('lora:join_mode:0')
lora.set_config('lora:region:EU868')
lora.set_config('lora:app_eui:70B3D5xxxxxxxxxx')
lora.set_config('lora:app_key:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
lora.join()
lora.set_config('lora:dr:5')
lora.send('Hello world')
lora.close()Your first message should appear on the TTN console!
Next steps
See the example directory on GitHub:
-
api_demo.py: demo most of the V2.0.x API calls -
otaa.py/otaa_v3.py: OTAA example -
otaa_v3_class_c.py: OTAA example with device in Class C mode -
abp.py/abp_v3.py: ABP example -
p2p.py/p2p_v3.py: P2P example -
p2p.sh/p2p_v3.sh: P2P example based on the command-line interface (see below)
To run the examples, first copy the ttn_secrets_template.py to ttn_secrets.py and enter your LoRaWan TheThingsNetwork keys.
Note: you do not need to hard_reset the module each time you run a script.
However you must do it the first time after a (re)boot to activate the module.
balenaCloud
Sample code to use the library with balenaCloud: Basic RAK811 example with balenaCloud (V2.0.x firmware).
Command-line interface
V2.0.x firmware
The rak811 command exposes all library calls to the command line:
$ rak811 --help
Usage: rak811 [OPTIONS] COMMAND [ARGS]...
Command line interface for the RAK811 module.
Options:
-v, --verbose Verbose mode
--help Show this message and exit.
Commands:
abp-info Get ABP info.
band Get/Set LoRaWan region.
clear-radio-status Clear radio statistics.
dr Get/set next send data rate.
get-config Get LoraWan configuration.
hard-reset Hardware reset of the module.
join-abp Join the configured network in ABP mode.
join-otaa Join the configured network in OTAA mode.
link-cnt Get up & downlink counters.
mode Get/Set mode to LoRaWan or LoRaP2P.
radio-status Get radio statistics.
recv-ex RSSI & SNR report on receive.
reload Set LoRaWan or LoRaP2P configurations to default.
reset Reset Module or LoRaWan stack.
send Send LoRaWan message and check for downlink.
set-config Set LoraWAN configuration.
signal Get (RSSI,SNR) from latest received packet.
sleep Enter sleep mode.
version Get module version.
wake-up Wake up.Session example:
$ rak811 -v reset lora
LoRa reset complete.
$ rak811 -v set-config app_eui=70B3D5xxxxxxxxxx app_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
LoRaWan parameters set
$ rak811 -v join-otaa
Joined in OTAA mode
$ rak811 -v dr
5
$ rak811 -v dr 4
Data rate set to 4.
$ rak811 -v send Hello
Message sent.
No downlink available.
$ rak811 -v send --port 4 --binary '01020211'
Message sent.
Downlink received:
Port: 1
RSSI: -56
SNR: 31
Data: 123456Note: for your first session after boot, you will need to do a hard-reset instead of a reset lora command to activate the module.
V3.0.x firmware
The rak811v3 command exposes the following library calls to the command line:
$ rak811v3 --help
Usage: rak811v3 [OPTIONS] COMMAND [ARGS]...
Command line interface for the RAK811 module.
Options:
-v, --verbose Verbose mode
-d, --debug Debug mode
--version Show the version and exit.
--help Show this message and exit.
Commands:
get-config Execute get_config RAK811 command.
hard-reset Hardware reset of the module.
help Print module help.
join Join the configured network.
receive-p2p Get LoraP2P message.
run Exit boot mode and enter normal mode.
send Send LoRaWan message and check for downlink.
send-p2p Send LoRa P2P message.
send-uart Send data to UART.
set-config Execute set_config RAK811 command.
version Get module version.Session example:
$ rak811v3 -v set-config lora:work_mode:0
Configuration done
LoRa (R) is a registered trademark or service mark of Semtech Corporation or its affiliates. LoRaWAN (R) is a licensed mark.
RAK811 Version:3.0.0.14.H
UART1 work mode: RUI_UART_NORMAL, 115200, N81
UART3 work mode: RUI_UART_NORMAL, 115200, N81
LoRa work mode:LoRaWAN, join_mode:OTAA, MulticastEnable: false, Class: A
$ # The following is not necessary as in this case the module is already in OTAA mode!
$ rak811v3 -v set-config lora:join_mode:0
Configuration done
$ rak811v3 -v set-config lora:app_eui:70B3D5xxxxxxxxxx
Configuration done
$ rak811v3 -v set-config lora:app_key:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Configuration done
$ rak811v3 -v join
Joined!
$ rak811v3 get-config lora:status | grep 'Current Datarate'
Current Datarate: 4
$ rak811v3 -v set-config lora:dr:5
Configuration done
$ rak811v3 -v send 'Hello'
Message sent.
No downlink available.
$ rak811v3 -v set-config lora:confirm:1
Configuration done
$ rak811v3 -v send --port 4 --binary '01020211'
Message sent.
Send confirmed.
RSSI: -66
SNR: 6
