LoRa RAW API Documentation
Available LoRa RAW APIs Summary
API Call |
Brief description |
|---|---|
lora.stats() |
displays the current stats of lora RAW |
lora.radio_params() |
set one or more radio parameter |
lora.callback() |
set a user level callback |
lora.send() |
transmit a given data over LoRa |
lora.recv() |
open a timed-out rx window to listen to any incoming data |
lora.recv_cont_start() |
switch to continuous rx mode |
lora.recv_cont_stop() |
close the continuous rx mode |
lora.tx_continuous_wave_start() |
start tx continuous wave operation |
lora.tx_continuous_wave_stop() |
stops tx continuous wave operation |
LoRa Raw Settings
To display the current settings of the lora RAW, use lora.stats(), Then you will experience something like this:
>>> lora.stats()
regional params
region : EU-868
frequency : 868000000 Hz
freq_khz : 868000.000 KHz
freq_mhz : 868.000 MHz
modulation params
sf : 12
bandwidth : 125 KHz
coding_rate : 4_7
packet params
preamble : 8
payload : 51
crc_on : False
lora tranceiver
chip : SX1262
max tx_power : +22 dBm
tx params
tx_power : +10 dBm
antenna_gain : +1.00 dBi
tx_power_eff : +9 dBm
tx_timeout : 6000 msec
tx_iq : False
rx params
rx_timeout : 6000 msec
rx_iq : False
Here is the meaning of each displayed parameter:
regional params: The parameters corresponding to the current region
region: The region in which the device will operate. frequency, freq_khz or freq_mhz: The required frequency in Hz, KHz or MHz respectively.
modulation params: The current modulation parameters which are; spreading-factor sf, bandwidth and coding_rate
packet params: parameters related to the packet data constraints such as preamble length, current maximum payload size, and if the crc_on is applied to the payload or not
lora tranceiver: shows the current info about the current used tranceiver such as the chip used and the maximum tx_power it can produce.
tx params: the current tx settings;
the current desired tx_power including the antenna gain the antenna_gain; should be set according to the current HW prescribed antenna gain to be taken into consideration while determining the chip output tx power the tx_power_eff which is the actual effective chip output power after subtracting the antenna gain from the desired tx_power tx_timeout the time-out of sending a message; it should be sufficient enough according to the time on air required for the current modulation parameters. tx_iq indicates whether inverted IQ polarity feature is enabled or not
rx params: the current rx settings;
rx_timeout the rx window time in non continuous reception rx_iq indicates whether inverted IQ polarity feature is enabled or not
To reset all parameters to the region defaults, provide reset_all flag like:
lora.radio_params(reset_all=True)
Modifying Radio Parameters
To change any radio parameter, use lora.radio_params() which takes its parameters as in the following BNF formatted description:
::=
"lora.radio_params(" ")"
::=
","
|
| ""
::=
reset_all "=" ; reset to factory settings
| region "=" ; change the region
| frequency "=" ; desired freq in Hz
| freq_khz "=" ; desired freq in KHz
| freq_mhz "=" ; desired freq in MHz
| tx_power "=" ; desired tx power
| sf "=" ; spreading factor
| coding_rate "=" ; coding rate
| preamble "=" ; preamble length
| bandwidth "=" ; band-width
| tx_iq "=" ; inverted IQ feature
::= "True" | "False"
::= "lora._region."
::=
"REGION_AS923" | "REGION_AU915" | "REGION_EU868" | "REGION_IN865" | "REGION_KR920"
| "REGION_RU864" | "REGION_US915"
::=
::=
::=
::= "7" | "8" | "9" | "10" | "11" | "12"
::= "lora._bw."
::= "BW_125KHZ" | "BW_250KHZ" | "BW_500KHZ"
::= "lora._cr."
::= "CODING_4_5" | "CODING_4_6" | "CODING_4_7" | "CODING_4_8"
Examples:
# set the tx power to 5 dBm
lora.radio_params(tx_power=5)
lora.stats()
# tx_power : +5 dBm --> desired tx-power
# antenna_gain : +2.15 dBi --> current set antenna-gain
# tx_power_eff : +2 dBm --> actual effective lora chip output power
lora.radio_params(antenna_gain=1) # the effective power will change accordingly
lora.stats()
# tx_power : +5 dBm --> desired tx-power
# antenna_gain : +1.00 dBi --> current set antenna-gain
# tx_power_eff : +4 dBm --> actual effective lora chip output power
# setting out of region valid tx power will be regicted for saftey
lora.radio_params(tx_power=45)
# error: invalid chip power +45 dBm -- chip SX1262 tx power range ( -8 ~ +23 ) dBm considering antenna gain 1.00 dBi
# error: invalid tx-power 45
# setting spreading factor to 8 and BW to 250 and coding rate to 4/6
lora.radio_params(sf = 8, bandwidth = lora._bw.BW_250KHZ, coding_rate = lora._cr.CODING_4_6)
# modulation params
# sf : 8
# bandwidth : 250
# coding_rate : 4_6
# setting wrong values will be regected and the whole parameters will be ignored
lora.radio_params(bandwidth=9, tx_power=44, sf=90) # gived the following reported errors
error: invalid chip power +44 dBm -- chip SX1262 tx power range ( -7 ~ +24 ) dBm considering antenna gain 2.15 dBi
error: invalid argument value 'tx_power'
error: invalid argument value 'sf'
error: invalid argument value 'bandwidth'
Note
Changing the region, will reset the entire radio parameters to the defaults of this new region
Note
The lora interface provides some class constants for some radio parameters:
lora._bw: contains all supported band width values
lora._cr: contains all supported coding rate values
lora._region: contains all supported regions values
# Example
# you can see the allowed values constans, by pressing the class names
# followed by double
>>> lora._bw. # press to see the following list
BW_125KHZ BW_250KHZ BW_500KHZ
>>> lora._cr. # press to see the following list
CODING_4_5 CODING_4_6 CODING_4_7 CODING_4_8
>>> lora._region. # press to see the following list
REGION_AS923 REGION_AU915 REGION_EU868 REGION_IN865 REGION_KR920
REGION_RU864 REGION_US915
Note
To change the frequency value, it can be done through one of these parameters (frequency, freq_khz or freq_mhz), however it is possible to specify one or more of those parameters. Hence in that case, the specified parameters will be considered in a priority fashion. frequency parameter has highest consideration priority and freq_mhz has lowest consideration priority.
# consider the current radio frequency parameter is 868.000 MHz
>>> lora.radio_params(frequency=868000000, freq_mhz=868.3)
# the specified `frequency` parameter will be considered first, but because
# it has the same value of the current frequency, it will be bypassed,
# then the next specified `freq_mhz` parameter will be considered, and
# the radio frequency will be changed accordingly.
# --> hence the current radio frequency parameter becomes 868.300 MHz
>>> lora.radio_params(freq_mhz=868.3, frequency=868000000)
# the highest priority parameter `frequency` will be considered first.
# and because it holds newer value than the current radio frequency, the
# radio frequency will be modified accordingly.
# --> hence the current radio frequency parameter becomes 868.000 MHz
# --> and the next specified `freq_mhz` parameter is neglicted
Setting LoRa RAW user Callback
To set a user level callback to listen the RX events, see the following example to know the available events that can come in the callback
Example:
def get_event_str(event, bytes):
if event == lora._event.EVENT_TX_CONFIRM:
return 'EVENT_TX_CONFIRM'
elif event == lora._event.EVENT_TX_DONE:
return 'EVENT_TX_DONE'
elif event == lora._event.EVENT_TX_TIMEOUT:
return 'EVENT_TX_TIMEOUT'
elif event == lora._event.EVENT_TX_FAILED:
return 'EVENT_TX_FAILED'
elif event == lora._event.EVENT_TX_CONFIRM:
return 'EVENT_TX_CONFIRM'
elif event == lora._event.EVENT_RX_DONE:
return 'EVENT_RX_DONE'
elif event == lora._event.EVENT_RX_TIMEOUT:
return 'EVENT_RX_TIMEOUT'
elif event == lora._event.EVENT_RX_FAIL:
return 'EVENT_RX_FAIL'
else:
return 'UNKNOWN'
pass
def lora_callback(event, evt_data):
print('lora event [ {} ] --> data: {}'
.format(get_event_str(event), evt_data))
lora.callback( handler = lora_callback )
Send (TX) Data
To send a specific data message, it takes the following parameters:
message: it is the normal data buffer, it could be a normal string or byte array
timeout: it is an optional argument to specify the tx operation deadline the default timeout will be the radio tx_timeout parameter
sync: it is an optional argument to perform this operation synchronously or asynchronously (default: sync=False)
Examples:
lora.send(“test message”) # sends a message asynchronously and with tx_timeout
# as a full tx operation timeout
# send a message asynchronously and the full tx operation shall canceled after 1 second
lora.send(“test message”, timeout=1000)
# send a message synchronously and the full tx operation shall canceled after 1 second
# in this case, the caller will be blocked until tx succeeded or timeout is over
lora.send(“test message”, timeout=1000, sync=True)
Receive (RX) Data
To receive a data and it takes the following parameters:
timeout: it is an optional argument to specify the tx operation deadline the default timeout will be the radio rx_timeout parameter
sync: it is an optional argument to perform this operation synchronously or asynchronously (default: sync=True)
sync the function will return the received message async the received message will be returned in the RX event in the callback
Example:
lora.recv() # waits for `rx_timeout` radio parameter or until a data is received
# wait for maximum 2 second or until a data is received
lora.recv(timeout=2000)
# place a receive request and return immediately
# - if a data is received before 3 second timeout, it will be returned in the callback
# - if timeout happened, the rx operation will be canceled and a timeout event will be
# fed back in the callback
lora.recv(timeout=3000, sync=True)
RX Continuous Mode
LoRa RAW can operate in continuous reception mode and any received data will be thrown in the registered user callback
Example:
lora.recv_cont_start() # starting the RX continuous mode
lora.recv_cont_stop() # exiting the RX continuous mode
Continuous TX Wave mode
Sets the radio tranciver to continuous transmission mode for testing.
The tx continuous wave mode does not use the normal parameters set by the lora.radio_params() method, but instead it uses the following parameters
tx_power the required tx power during the test
frequency the required test frequency in Hz (default: 868 MHz)
timeout an optional timeout in milliseconds (default: 10 seconds)
Remark: if the system is in sending or receiving operation, the operation will be cancelled and the system will start serving the tx continuous wave test command. After timeout is over, the system will go to its IDLE state.
Example:
lora.tx_continuous_wave_start( # starting the TX continuous wave mode
tx_power = 20, # use tx_power = 20dBm
frequency = 868000000, # test frequency 868 MHz
timeout = 20000) # timeout for the tx continuous wave 20 sec
lora.tx_continuous_wave_stop() # exiting the TX continuous wave mode