Pi Supply LoRa Node pHAT – Comprehensive list of Python Commands

The Python library for the LoRa Node pHAT is provided by Philippe Vanhaesendonck (AmedeeBulle). The Python library is based on the RAK811 AT commands and is written in Python3 programming language. This guide will show you a list of all available Python 3 commands and their parameters.

How to install the library

The python library has been package together using PyPi and can be install using pip3. Make sure you have pip3 installed first by running the following command:

sudo apt-get install python3-pip

Once installed you can now install the library with the following command:

sudo pip3 install rak811

RAK811 Python Library

Import library

You must ensure that for every python script you write that you import the library into your code. This will allow you to call the rak811 commands from within your script:

from rak811 import Mode, Rak811

lora = Rak811()

Reset RAK811 module

After booting the Raspberry Pi the module needs restarting to activate the module. This only needs to be done once but to ensure the module is ready it is common practice to add this command to the start of your code.

lora.hard_reset()

Setting the module mode

The RAK811 module can be set in two modes, LoRaWAN and P2P (Peer to Peer):

lora.mode = Mode.LoRaWAN

lora.mode = Mode.LoRaP2P

Setting the operation frequency

The RAK811 module is multifrequency and must be set to the desired frequency in your country. The LoRa module can be set to one of the following frequency bands:

lora.band = ‘EU868’

lora.band = ‘US915’

lora.band = ‘AU915’

lora.band = ‘KR920’

lora.band = ‘AS923’

lora.band = ‘IN865’

Set LoRaWAN Configuration

These parameters are required to join the TTN network. The LoRa module saves the relevant data in the EEPROM and it is not necessary to set values for each session. Usually only the following parameters are required to join TTN:

lora.set_config(

app_eui=’0000000000000000000′

app_key=’0000000000000000000′

)

The following parameters are accepted by the module and can be passed by the set_config command:

dev_addr: device address (4 bytes hex number)

dev_eui: device EUI (8 bytes hex number, default derived from the MCU’s UUID

app_eui: app EUI (8 bytes hex number)

app_key: app key (16 bytes hex number)

apps_key: application session key (16 bytes hex number)

nwks_key: network session key (16 bytes hex number)

tx_power: transmit power (in dBm — deprecated, use pwr_level)

pwr_level: transmit power (0-7 for EU868, region specific)

adr: adr flag (on/off)

dr: data rate (0-7 for EU868, region specific)

public_net: public_net flag (on/off)

rx_delay1: rx1 delay (0-65535 milliseconds)

ch_list: channel list, see RAK documentation

ch_mask: channel mask, see RAK documentation

max_chs: max channels used in the region (read-only)

rx2: rx2 data rate and frequency

join_cnt: join count for OTAA joins (number, region specific)

nbtrans: number of transmissions for unconfirmed uplink message (1-15, default 1)

retrans: number of retransmissions for confirmed uplink message (1-255, default 8)

class: LoRa class (0: A, 2: C)

duty: respect duty cycle flag (on/off)

Join configured network

When sending data to a gateway you must determine the method, ABP or OTAA.

ABP

ABP requires the following parameters to be set using set_config() prior to joining:

• dev_addr
• nwks_key
• apps_key

lora.join_abp

OTAA

OTAA requires the following parameters to be set using set_config() prior to joining:

• dev_eui
• app_eui
• app_key

lora.join_otaa()

Joining OTAA can return with the following errors:

• Rak811TimoutError: join didn’t succeed in time
• Rak811EventError: join failed

Setting the data rate

The data rate is different from spread factor and the value depends on the region. See the following article to determine your data rate value – https://docs.exploratory.engineering/lora/dr_sf/

lora.dr = 5

Sending LoRa data

Use to send LoRaWAN message. The send command must contain the following parameters:

• data: data to be sent. If datatype is bytes it will be sent as such. Strings will be converted to bytes.
• confirm: regular or confirmed send.
• port: port number to use

When using the following command it will use the default parameters set in the library, confirm=FALSE, port=1.

lora.send(‘Hello World’)

or

lora.send(‘Hello World’, confirm=TRUE, port=2)

Close the session

When you send the LoRa data to the gateway it is important that you then close the session to avoid any errors. Using the following command will terminate the read thread and close the serial port to the RAK module:

lora.close()

System commands for RAK811 module

Below is a list of system commands that can be called for the RAK811 module:

Get the current version number of the RAK811 module

lora.version()

Enter sleep mode

lora.sleep()

Wakeup the RAK811 module from sleep

lora.wake_up()

Reset the RAK811 module or LoRaWAN stack

lora.reset()

Set LoRaWAN or LoRaP2P configurations back to default

lora.reload()

Get status information

The following commands can be used to get the current status of the module or the packet information:

Get RSSI,SNR from latest received packet

lora.signal()

Get next send data rate

lora.dr()

Get up & downlink counters

lora.link_cnt()

Get ABP info

When using OTAA this will return the necessary information to then re-join in ABP mode. The following data is returned: NetworkID, DevAddr, Nwkskey, Appskey.

lora.abp_info

Get the number of downlink messages in the receive buffer

lora.nb_downlinks()

Get the downlink message from the receive buffer

lora.get_downlink()

retruns a dictionary with the following keys:

• port: port number
• rssi: RSSI (0 if recv_ex was disabled)
• snr: SNR (0 if recv_ex was disabled)
• len: data length
• data: data itself

LoRa P2P Commands

The following commands are specific for LoRaP2P configuration:

Get the current LoRaP2P configuration set:

lora.rf_config()

Will return the following values:

• freq: frequency in Mhz, range 860.000 – 929.000 Mhz
• sf: spread factor, range (6-12)
• bw: band width, values 0:125KHz, 1:250KHz, 2:500KHz
• cr: coding rate, values 1:4/5, 2:4/6, 3:4/7, 4:4/8
• prlen: preamble len, range 8-65536
• pwr: transmit power, range 5,10

Set LoRaWan P2P RF configuration parameters

If parameters are missing then default value set will be used.

lora.rf_config = {

‘freq’: 868.700,

‘sf’: 7,

‘bw’: 0

}

Default values are:

• freq = 868.100
• sf = 12
• bw = 0
• cr = 1
• prlen = 8
• pwr = 20

The RAK811 module saves the parameters to flash and it is not necessary to set the values for each session.

Send LoRa P2P command

Sending data using the pre-set RD parameters. For RF testing ‘cnt’ can be specified to send data multiple times. The module will stop sending messages after ‘cnt’ messages or when it received a tx_stop() command. Parameters passed:

• data: data to be sent. If datatype is bytes it will be sent as such. Strings will be converted to bytes.
• cnt: send message cnt times
• interval: when sending multiple times, interval in seconds between each message.

If sending the following command, default values are used for ‘cnt=1’ and ‘interval=60’:

lora.txc(‘hello world’)

lora.txc(‘hello world’, 2, 30)

Set RAK811 module in LoRaP2P receive mode

Module is put into receive mode until an rx_stop command is issued. Method will return immediately after the command is acknowledged.

lora.rxc()

Stop LoRaP2P Tx

Stop LoRaP2P transmission; radio will switch to sleep mode.

lora.tx.stop()

Stop LoRaP2P Rx

Stop LoRaP2P reception; radio will switch to sleep mode.

lora.rx_stop()

Get LoRaP2P message

This is a blocking call, it will either wait until it has received a message or timeout. The downlink receive buffer is populated, actual data is retrieved with get_downlink().

lora.rx_get()

Get radio statistics

Returns the following:

• TxSuccessCnt
• TxErrCnt
• RxSuccessCnt
• RxTimeOutCnt
• RxErrCnt
• Rssi
• Snr

lora.radio_status()