Links

LoRa

Python Library for Microchip RN2XX3 LoRa Module.

Python Library

Turta_LoRa library is responsible for handling all LoRa communication.
To make Raspberry Pi communicate with the LoRa module, you should swap the serial ports of the Raspbian OS. Set "/dev/ttyAMA0" to 'serial0'. Also, disable the console on 'serial0'. For a how-to, visit swapping the serial ports topic.

Initialization

Add the following statement to the top of your Python code.
from turta_lorahat import Turta_LoRa
Then, create an instance of the RN2XX3 class.
lora = Turta_LoRa.RN2XX3()
Now you're ready to access the library by calling its instance.

Initialization Parameters

RN2XX3

Initiates the RN2XX3 LoRa module to handle LoRa communication.
Turta_LoRa.RN2XX3(region, auto_config, freq_us, freq_eu)
  • Parameters
    • REGIONS region: LoRa Module region. (Default is REGIONS.US_RN2903)
    • CONFIG_MODES auto_config: LoRa Module operating mode. NONE is for manual configuration. LORA_TX and LORA_RX are for automatic configuration. (Default is MODES.CONFIG_MODES.NONE)
    • Int freq_us: LoRa radio frequency for US version auto configuration. (Default is 915000000)
    • Int freq_eu: LoRa radio frequency for EU version auto configuration. (Default is 868000000)

Basic Members

Basic members work on autoconfiguration mode.

Send

Broadcasts data for auto TX mode operation.
send(data)
  • Parameters
    • String data: Data to send (Max 255 characters).
  • Returns
    • str: Response from the LoRa module.

Check Data

Checks the serial port buffer for received data.
check_data()
  • Parameters
    • None
  • Returns
    • str: If auto mode is selected, the function returns received data. If manual mode is selected, it returns the LoRa module's raw output.

System Commands (Advanced)

System Commands

Sys Sleep

Puts the system to sleep for the specified number of milliseconds.
sys_sleep(length)
  • Parameters
    • Int length: Number of milliseconds the system is put to sleep (100 to 4294967296).
  • Returns
    • String: Response from the module.
Sys Reset
Resets and restarts the LoRa module; stored LoRaWAN protocol settings will be loaded automatically upon reboot.
sys_reset()
  • Parameters
    • None.
  • Returns
    • String: Response from the module.
Sys Factory Reset
Resets the module’s configuration data and user EEPROM to factory default values and restarts the module.
sys_factory_reset()
  • Parameters
    • None.
  • Returns
    • String: Firmware version and release date (RN2XX3 X.Y.Z MMM DD YYYY HH:MM:SS).
Sys Set NVM
Allows the user to modify the user EEPROM at with the value supplied by.
sys_set_nvm(address, data)
  • Parameters
    • String address: Hexadecimal number representing user EEPROM address (300 to 3FF)
    • String data: Hexadecimal number representing data (00 to FF)
  • Returns
    • String: Response from the module.
Sys Get Ver
Returns the information related to the hardware platform, firmware version, release date and time-stamp on firmware creation.
sys_get_ver()
  • Parameters
    • None.
  • Returns
    • String: Firmware version and release date (RN2XX3 X.Y.Z MMM DD YYYY HH:MM:SS).
Sys Get NVM
Returns the data stored in the user EEPROM of the RN2XX3 module at the requested location.
sys_get_nvm(address)
  • Parameters
    • String address: Hexadecimal number representing user EEPROM address (300 to 3FF).
  • Returns
    • String: 00–FF (hexadecimal value from 00 to FF) if the address is valid.
Sys Get VDD
Gets the Voltage applied to the VDD pins.
sys_get_vdd()
  • Parameters
    • None.
  • Returns
    • String: mV Measured on the VDD pins (0 to 3600).
Sys Get HWEUI
Reads the preprogrammed EUI node address from the RN2XX3 module.
sys_get_hweui()
  • Parameters
    • None.
  • Returns
    • String: Hexadecimal number representing the preprogrammed EUI node address.

MAC Commands (Advanced)

LoRaWAN Class A and Class C Protocol Commands (MAC)
MAC Reset
Sets default values for most of the LoRaWAN parameters. Everything set prior to this command will lose its set value, being reinitialized to the default value, including setting the cryptographic keys to 0.
mac_reset(band)
  • Parameters
    • EU_FREQ_BANDS band: Frequency Band for EU version. Set 'NONE' for US version.
  • Returns
    • String: Response from the module.
MAC Tx
Automatically reset the software LoRaWAN stack and initialize it with the default parameters.
mac_tx(uplink_payload_type, portno, data)
  • Parameters
    • UPLINK_PAYLOAD_TYPES uplink_payload_type: Uplink payload type, either confirmed or unconfirmed.
    • Int portno: Port number (1 to 223).
    • String data: Hexadecimal value; the length of bytes capable of being transmitted are dependent upon the set data rate.
  • Returns
    • String: First response from the device; this command may reply with multiple responses.
MAC Join
Informs the RN2XX3 module it should attempt to join the configured network.
mac_join(mode)
  • Parameters
    • JOIN_PROCEDURE_TYPES mode: Join procedure type.
  • Returns
    • String: First response from the device; this command may reply with two responses.
MAC Save
Saves the LoRaWAN protocol configuration parameters to the EEPROM. Upon the next system reset the LoRaWAN protocol configuration will be initialized with the last saved parameters.
mac_save()
  • Parameters
    • None.
  • Returns
    • String: Response from the module.
MAC Force Enable
Restores the module’s connectivity by allowing it to send data.
mac_force_enable()
  • Parameters
    • None.
  • Returns
    • String: Response from the module.
MAC Pause
Pauses the LoRaWAN stack functionality to allow transceiver (radio) configuration.
mac_pause()
  • Parameters
    • None.
  • Returns
    • String: The number of milliseconds the MAC can be paused (0 to 4294967295).
MAC Resume
Resumes LoRaWAN stack functionality, in order to continue normal functionality after being paused.
mac_resume()
  • Parameters
    • None.
  • Returns
    • String: Response from the module.
MAC Set Appkey
Sets the application key for the module. The application key is used to derive the security credentials for communication during over-the-air activation.
mac_set_appkey(appkey)
  • Parameters
    • String appkey: 16-byte hexadecimal number representing the application key.
  • Returns
    • String: Response from the module.
MAC Set Appskey
Sets the application session key for the module. This key provides security for communication between module and application server.
mac_set_appskey(appsesskey)
  • Parameters
    • String appsesskey: 16-byte hexadecimal number representing the application session key.
  • Returns
    • String: Response from the module.
MAC Set AR
Sets the state of the automatic reply.
mac_set_ar(state)
  • Parameters
    • AR_STATES state: Automatic reply state.
  • Returns
    • String: Response from the module.
MAC Set Bat
Sets the battery level required for Device Status Answer frame in use with the LoRaWAN Class A protocol.
mac_set_bat(level)
  • Parameters
    • Int level: The level of the battery (0 to 255) 0 Means external power, 1 means low level, 254 means high level, 255 means the end device was not able to measure the battery level.
  • Returns
    • String: Response from the module.
MAC Set Ch Freq
Sets the operational frequency on the given for the EU version. The default channels (0-2) cannot be modified in terms of frequency.
mac_set_ch_freq(channel_id, frequency)
  • Parameters
    • Int channel_id: The channel number (from 3 to 15).
    • Int frequency: The frequency in Hz (863000000 to 870000000 or 433050000 to 434790000).
  • Returns
    • String: Response from the module.
MAC Set Ch Dcycle
Sets the duty cycle used on the given for the EU version.
mac_set_ch_dcycle(channel_id, duty_cycle)
  • Parameters
    • Int channel_id: The channel number (0 to 15).
    • Int duty_cycle: The duty cycle (0 to 65535).
  • Returns
    • String: Response from the module.
MAC Set Ch Drrange
Sets the operating data rate range, min. to max., for the given.
mac_set_ch_drrange(channel_id, min_range, max_range)
  • Parameters
    • Int channel_id: The channel number (0 to 71 for the US, 0 to 15 for the EU).
    • Int min_range: The minimum data rate (0 to 3 for the US, 0 to 7 for the EU).
    • Int max_range: The maximum data rate (0 to 3 for the US, 0 to 7 for the EU).
  • Returns
    • String: Response from the module.
MAC Set Ch Status
Sets the operation of the given.
mac_set_ch_status(channel_id, status)
  • Parameters
    • Int channel_id: The channel number (0 to 71).
    • CH_STATUS status: The state (on or off).
  • Returns
    • String: Response from the module.
MAC Set Class
Sets the end device LoRaWAN operating clas.
mac_set_class(device_class)
  • Parameters
    • DEVICE_CLASS device_class: The LoRaWAN device class (a or c).
  • Returns
    • String: Response from the module.
MAC Set Devaddr
Configures the module with a 4-byte unique network device address. The address must be unique to the current network.
mac_set_devaddr(address)
  • Parameters
    • String address: 4-byte hexadecimal number representing the device address (00000000 to FFFFFFFF).
  • Returns
    • String: Response from the module.
MAC Set Deveui
Sets the globally unique device identifier for the module.
mac_set_deveui(deveui)
  • Parameters
    • String deveui: 8-byte hexadecimal number representing the device EUI.
  • Returns
    • String: Response from the module.
MAC Set Dnctr
Sets the value of the downlink frame counter that will be used for the next downlink reception.
mac_set_dnctr(f_cnt_down)
  • Parameters
    • Int f_cnt_down: The value of the downlink frame counter that will be used for the next downlink reception (0 to 4294967295).
  • Returns
    • String: Response from the module.
MAC Set DR
Sets the data rate to be used for the next transmission.
mac_set_dr(datarate)
  • Parameters
    • Int datarate: Data rate (0 to 4 for US, 0 to 7 for EU, but within the limits of the data rate range for the defined channels).
  • Returns
    • String: Response from the module.
MAC Set Linkchk
Sets the time interval for the link check process to be triggered periodically.
mac_set_linkchk(linkcheck)
  • Parameters
    • Int linkcheck: The time interval in seconds for the link check process (0 to 65535).
  • Returns
    • String: Response from the module.
MAC Set Mcast
Sets the end device multicast state (mcast) to either be enabled or disabled.
mac_set_mcast(state)
  • Parameters
    • MCAST_STATES state: End device multicast state (on or off).
  • Returns
    • String: Response from the module.
MAC Set Mcastappskey
Sets the multicast application session key for the module.
mac_set_mcastappskey(mcast_application_session_key)
  • Parameters
    • String mcast_application_session_key: 16-byte hexadecimal number representing the application session key.
  • Returns
    • String: Response from the module.
MAC Set Mcastdevaddr
Configures the module with a 4-byte multicast network device address.
mac_set_mcastdevaddr(mcast_address)
  • Parameters
    • String mcast_address: 4-byte hexadecimal number representing the device multicast address (00000000 to FFFFFFFF).
  • Returns
    • String: Response from the module.
MAC Set Mcastdnctr
Sets the value of the multicast downlink frame counter that will be used for the next downlink reception.
mac_set_mcastdnctr(f_mcast_cntdown)
  • Parameters
    • Int f_mcast_cntdown: The value of the multicast downlink frame counter (0 to 4294967295).
  • Returns
    • String: Response from the module.
MAC Set Mcastnwkskey
Sets the multicast network session key for the module.
mac_set_mcastnwkskey(mcast_network_session_key)
  • Parameters
    • String mcast_network_session_key: 16-byte hexadecimal number representing the network session key.
  • Returns
    • String: Response from the module.
MAC Set Nwkskey
Sets the network session key for the module.
mac_set_nwkskey(nwk_sess_key)
  • Parameters
    • String nwk_sess_key: 16-byte hexadecimal number representing the network session key.
  • Returns
    • String: Response from the module.
MAC Set Pwridx
Sets the output power to be used on the next transmissions.
mac_set_pwridx(pwr_index)
  • Parameters
    • Int pwr_index: Index value for the output power (5 to 10 on the US 902-928 frequency band).
  • Returns
    • String: Response from the module.
MAC Set Retx
Sets the number of retransmissions to be used for an uplink confirmed packet, if no downlink acknowledgment is received from the server.
mac_set_retx(re_tx_nb)
  • Parameters
    • Int re_tx_nb: The number of retransmissions for an uplink confirmed packet (0 to 255).
  • Returns
    • String: Response from the module.
MAC Set Rx2 US
Sets the data rate and frequency used for the second Receive window, for US version.
mac_set_rx2_us(data_rate, frequency)
  • Parameters
    • Int data_rate: Data rate (8 to 13).
    • FREQUENCIES frequency: Frequency (923300000 to 927500000 Hz in 600kHz steps).
  • Returns
    • String: Response from the module.
MAC Set Rx2 EU
Sets the data rate and frequency used for the second Receive window, for EU version.
mac_set_rx2_eu(data_rate, frequency)
  • Parameters
    • Int data_rate: Data rate (0 to 7).
    • Int frequency: Frequency in Hz (863000000 to 870000000 or 433050000 to 434790000).
  • Returns
    • String: Response from the module.
MAC Set Rxdelay1
Sets the delay between the transmission and the first Reception window to the in milliseconds.
mac_set_rxdelay1(rx_delay)
  • Parameters
    • Int rx_delay: The delay between the transmission and the first Reception window in milliseconds (0 to 65535).
  • Returns
    • String: Response from the module.
MAC Set Sync
Sets the synchronization word for the LoRaWAN communication.
mac_set_sync(synch_word)
  • Parameters
    • String synch_word: One byte long hexadecimal number representing the synchronization word for the LoRaWAN communication.
  • Returns
    • String: Response from the module.
MAC Set Upctr
Sets the value of the uplink frame counter that will be used for the next uplink transmission.
mac_set_upctr(f_cnt_up)
  • Parameters
    • Int f_cnt_up: The value of the uplink frame counter that will be used for the next uplink transmission (0 to 4294967295).
  • Returns
    • String: Response from the module.
MAC Get Adr
Returns the state of the adaptive data rate mechanism.
mac_get_adr()
  • Parameters
    • None.
  • Returns
    • String: State of the adaptive data rate mechanism (on or off).
MAC Get Appeui
Returns the application identifier for the module. The application identifier is a value given to the device by the network.
mac_get_appeui()
  • Parameters
    • None.
  • Returns
    • String: 8-byte hexadecimal number representing the application EUI.
MAC Get AR
Returns the current state for the automatic reply (AR) parameter.
mac_get_ar(parameter)
  • Parameters
    • None.
  • Returns
    • String: The state of the automatic reply (on or off).
MAC Get Ch Freq
Returns the frequency on the requested.
mac_get_ch_freq(channel_id)
  • Parameters
    • Int channel_id: Channel number (0 to 71).
  • Returns
    • String: The frequency of the channel.
MAC Get Ch Dcycle
Returns the duty cycle on the requested.
mac_get_ch_dcycle(channel_id)
  • Parameters
    • Int channel_id: Channel number (0 to 15).
  • Returns
    • String: Duty cycle of the channel (0 to 65535).
MAC Get Ch Drrange
Returns the allowed data rate index range on the requested.
mac_get_ch_drrange(channel_id)
  • Parameters
    • Int channel_id: Channel number (0 to 71 for US, 0 to 15 for EU).
  • Returns
    • String: Minimum and maximum data rate of the channel.