LoRa

This category contains functions specific to LoRaWAN devices.

api.loraSend(ack, timeout, msg)

Overview

Sends and receives LoRaWAN frames.

Arguments

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

• ack (integer) - 1 for acknowledged mode, 0 for unacknowledged mode
• timeout (integer) - The maximum execution time in milliseconds, used in acknowledged mode
• msg (string) - Message sent to LoRaWAN
• port (integer, optional) - Port number

Return

• status (integer) - Positive or zero for success, negative for failure
  • Positive = Number of bytes received
  • 0 = "No data received"
  • -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()

Overview

Sends join request.

info

Rejoining occurs automatically every 7 days by default. This interval can be modified using the api.loraSetup() function.

Arguments

api.loraJoin(int, dr)

• int (integer, optional) - 0 for security context check (if there is none, sends join request), 1 for forced join request
• dr (integer, optional) - sets join Data Rate (in range from 0 to 5)

Return

• status (integer) - Positive or zero for success, negative for failure
  • 0 = Success
  • -3 = "Timeout, busy!"
  • -4 = "General error!"
  • -5 = "No answer!"
  • -6 = "Error joining!"

Example

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

api.loraSetup(parameter, ...)

Overview

Configures LoRaWAN parameters.

warning

This function resets the previous activation settings. This means that if you repeatedly call api.loraSetup("ACTIVATION", "OTAA"), a join request will be sent each time the function is executed.

info

Before setting up the device to class B or C, verify it's supported/enabled by the network server you use. Otherwise, the device will not switch to the specified class.

Parameters

• "ACTIVATION" - Type of activation
• "ADR" - Adaptive Data Rate
• "DR" - Data Rate
• "DC" - Duty Cycle
• "RUN_FSM" - Run internal LoRaWAN FSM for x milliseconds
• "CLASS" - Sets or gets current LoRaWAN class
• "OTAA-REJOIN-CONFIRMED-FAILED-COUNTER" - Sets number of confirmed messages, which must fail before new join is forced
• "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
• "TIME_SYNC" - Schedule Time synchronization request (requires support by network server), compatible with LoRaWAN 1.0.3+

warning

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.

warning

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

Arguments

api.loraSetup(ACTIVATION, method)

• parameter (string)
• method (string) - OTAA or ABP

api.loraSetup(ADR, state)

• parameter (string)
• state (integer) - 1 for on, 0 for off

api.loraSetup(DR, value)

• parameter (string)
• value (integer) - Data Rate (0-5)

api.loraSetup(DC, state)

• parameter (string)
• state (string) - ON, OFF, DCTIME, GET

api.loraSetup(RUN_FSM, timeout)

• parameter (string)
• timeout (integer) - Run internal LoRaWAN FSM for x milliseconds

api.loraSetup(CLASS, class)

• parameter (string)
• class (string) - A, B, or C

api.loraSetup(OTAA-REJOIN-CONFIRMED-FAILED-COUNTER, value)

• parameter (string)
• value (integer) - Number of confirmed messages, which must fail before new join is forced

api.loraSetup(OTAA-MINIMAL-CONFIRMED-PERIOD, value)

• parameter (string)
• value (integer) - Period of time (in milliseconds) to send join request (by default 7 days)

api.loraSetup(OTAA-REJOIN-CONFIRMED-COUNTER, number)

• parameter (string)
• number (integer) - Maximum number of unconfirmed messages in a row (default and minimal values is 5), every Nth message is forcefully sent as confirmed

api.loraSetup(POWER, power)

• parameter (string)
• power (integer) - Power: 0, 2, 4, 6, 8, 10, 12, 14

api.loraSetup(TIME_SYNC)

• parameter (string)

Example

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

api.loraListenClassBC(timeout)

Overview

Listens for message until timeout in class B or C.

warning

The device needs to be set to Class B or Class C before using this function. Ensure that it is supported by the Network Server.

Arguments

api.loraListenClassBC(timeout, class)

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

Return

• status (integer) - Positive or zero for success, negative for failure
• port (integer) - nil or port on which the message was received
• 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(credential, ...)

Overview

Sets one LoRa credential.

info

When this function is called, the device automatically sends a Join Request.

Credentials

• devADDR - Device address
• devEUI - Device EUI
• nwkSKey - Network session key
• appSKey - Application session key
• appEUI - Application EUI

Arguments

api.loraSetCredential(devADDR, address)

• credential (string)
• address (string) - 32-bit address

api.loraSetCredential(devEUI, eui)

• credential (string)
• eui (string) - 64-bit end-device identifier

api.loraSetCredential(nwkSKey, key)

• credential (string)
• key (string) - 128-bit network session key

api.loraSetCredential(appSKey, key)

• credential (string)
• key (string) - 128-bit application session key

api.loraSetCredential(appEUI, eui)

• credential (string)
• eui (string) - 64-bit application identifier

Example

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

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

Overview

Sets LoRa credentials.

info

When this function is called, the device automatically sends a Join Request.

Arguments

• devADDR (string) - 32-bit address
• devEUI (string) - 64-bit end-device identifier
• nwsKey (string) - 128-bit network session key
• appsKey (string) - 128-bit application session key
• appEUI (string, optional) - 64-bit application identifier

Example

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

api.loraGetDevEui(format)

Overview

Retrieves the devEUI.

Arguments

• format (string) - Output format: "bin" or "hex"

Return

• eui (string) - 64-bit end-device identifier

Example

--Get LoRa devEUI
eui=api.loraGetDevEui("bin")
api.dumpArray(eui)

print(api.loraGetDevEui("hex"))