LoRa

This category contains functions specific to LoRaWAN devices.

api.loraSend(ack, timeout, msg, port)

Overview

Sends buffer msg to LoRa. Acknowledged or non-acknowledged transport can be used using ack parameter. Maximum execution time is limited by timeout in milliseconds.

Arguments

• ack (integer) - Selects acknowledged (1) or non-acknowledged (0) transmission mode
• timeout (integer) - The maximum execution time in milliseconds, used in acknowledged mode
• msg (string) - String to be sent to LoRa
• port (integer) - Port number (OPTIONAL)

Return

• status (integer) - Positive or zero for success, negative for failure
  • -1 = "Not acknowledged" ("NACK")
  • -2 = "Cannot send, LoRaMAC keeps busy!"
  • -3 = "Failed sending!"
  • -4 = "Failed sending LoRaWAN frame! (sent count = %d"
  • -5 = "Cannot send - too long payload for current SF!"
• port (integer) - Nil or port on which the answer was received
• answer (string) - Nil or non-zero length string containing gateway answer

Example

--sends 0xCCBBAA35 to LoRa with 20s timeout and acknowledged mode
msg = pack.pack('<b4', 0xCC, 0xBB, 0xAA, 0x35)
status, port, answer = api.loraSend(1,20000, msg)
 
if status >= 1 then       --checks if device received more than one 1 byte
  api.dumpArray(answer)   --if true, print the data
end

api.loraJoin(int, dr)

Overview

Sends join request.

Rejoin is made automaticaly once per 7 days by default, but it can be changed using following "api.loraSetup" function.

Arguments

• int (integer) - if the number is 0, then it checks for security context (which is stored in memory after successful join request), if there's none, the it sends join request. If the number is 1, join request is forced.
• dr (integer)(optional) - *sets join Data Rate (in range from 0 to 5) *

Example

-- check if joined, if not join ...
api.loraJoin()
 
-- join!
api.loraJoin(1)

api.loraSetup(s1, s2)

Overview

Sets parameters defined by strings s1 and s2.

This function resets previous activation settings. Meaning, if you call repeatedly api.loraSetup("ACTIVATION", "OTAA") it'll send join request each time this function is called.

Before setting up the device to class B or C, verify it's supported/enabled by the Network server you use. Otherwise, it won't switch the class.

Arguments

• s1 (string) - Defining parameter to be set. Here's a list of those parameters:

  • “ACTIVATION” - Type of activation
  • “ADR” - Adaptive Data Rate
  • “DR” - Data Rate
  • “DC”- Duty Cycle
  • “RUN_FSM”- Run internal LoRaWAN FSM for x milliseconds
    • timeout (integer) (optional) - run FSM for given number of milliseconds (defaults to 1000 ms)
  • “CLASS”- Sets or gets current LoRaWAN class
    • in case no other argument is provided - returns current value as string ("A", "B" or "C")
    • new class (string) (optional) - in case new class is specified, switch is executed
      • returns integer execution status value - 0 on success, negative on error
  • “OTAA-REJOIN-CONFIRMED-FAILED-COUNTER" - Sets number of confirmed messages, which must fail before new join is forced (cannot be lower than 5, which is also default number)
  • "OTAA-MINIMAL-CONFIRMED-PERIOD" - Sets period of time (in milliseconds) to send join request (by default 7 days)
  • "OTAA-REJOIN-CONFIRMED-COUNTER" - Sets maximum of unconfirmed messages in row (default and minimal values is 5), every nth message is forcefully sent as confirmed
  • "POWER" - Sets the power to defined value in dBm
    • power (integer) - power (0, 2, 4, 6, 8, 10, 12, 14)
  • "TIME_SYNC" - Schedule Time synchronization request (requires support by network server), compatible with LoRaWAN 1.0.3+

• s2 (string, integer) options in case of:

  1. ACTIVATION - "OTAA", "ABP"
  2. ADR - select between 1 (on) and 0 (off)
  3. DR - chose number in range from 0 to 5
  4. DC - "ON", "OFF", "DCTIME", "GET"

If ADR is turned off and DR is manually set, please keep in mind if the join request is performed (by calling api.loraSend after startup, or by calling api.loraJoin), it will assign a different DR value during the join request.

If activation type ABP is used and ADR is on, when attempting to set DR, it will always assign DR = 0.

Example

--set activation type as ABP
api.loraSetup("ACTIVATION", "ABP")
 
--set data rate to 0
api.loraSetup("DR", 0)

api.loraListenClassBC(timeout, class)

Overview

Listens for message until received or timeout in class C.

Firstly set the device to class B or C before using this function and verify it's supported by the Network server.

Arguments

• timeout (integer) - Timeout of listening in milliseconds
• class (string) - Class to use, B or C, default to C (OPTIONAL)

Return

• status (integer) - Positive or zero for success, negative for failure
• port (integer) - Communication port
• buffer (string) - Message received from LoRa

Example

--Listen on LoRa for a message with timout of 10 seconds
api.loraSetup("CLASS", "C")
status, port, buffer = api.loraListenClassBC(10000)

api.loraSetCredential(var1, var2)

Overview

Sets only one LoRa credential.

By Calling this function, the converter also sends Join request.

Arguments

• var1 (string) - selects one credential to be changed - devADDR, devEUI, nwkSKey, appSKey, appEUI
• var2 (string) - desired string for selected credential

Example

--Set one LoRa credential (in this case devEUI) 
api.loraSetCredential("devEUI", "3333333333333333")

api.loraSetCredentials(devADDR, devEUI, nwsKey, appsKey, appEUI)

Overview

Sets LoRa credentials.

By Calling this function, the converter also sends Join request.

Arguments

• devADDR (string) - Device ADDR
• devEUI (string) - Device EUI
• nwsKey (string) - NWS key
• appsKey (string) - APPS key
• appEUI (string) - Application EUI (OPTIONAL)

Example

--Set LoRa credentials 
api.loraSetCredentials("22011221","3333333333333333","44444444444444444444444444444444","55555555555555555555555555555555","70B344440013333")

api.loraGetDevEui(arg)

Overview

Function to retrieve the DevEUI.

Arguments

• arg (string) - Specifies the output type:
  • "bin" - returns memory content
  • "hex" - returns memory content in hexadecimal (ASCII) format.

Example

--Set LoRa credentials
eui=api.loraGetDevEui("bin")
api.dumpArray(eui)

print(api.loraGetDevEui("hex"))