NB IoT

This category contains functions specific to NB-IoT devices.

api.nbSend(addr, port, msg, timeout, type, nownewdatatimeout, rxport)

Overview

Sends buffer msg to NB on specified IP, port and protocol type. Maximum length of Rx and Tx messages is 512 Bytes. Maximum execution time is limited by timeout milliseconds.

Arguments

• addr (string) - IP address
• port (integer) - Port
• msg (string)(integer) - String to be sent to NB
  • if number is provided instead of string, scratchpad (api.nbReceiveBuffer) buffer is sent in given length
• timeout (integer) - The maximum execution time in milliseconds
• type (string) - Protocol type, either UDP, TCP or DTLS.
• nownewdatatimeout (integer, optional) - The maximum delay between data chunks on reception
• rxport (integer, optional) - Port to use for reception, if not specified, Port value is used

Example

UDP

-- sends "test message" string to IP 185.8.239.192 on port 5566 with 6s timeout
status,answer = api.nbSend("185.8.239.192", 5566, "test message", 6000, "UDP")

TCP

-- sends "test message" string to IP 185.8.239.192 on port 5566 with 6s timeout
status,answer = api.nbSend("185.8.239.192", 5566, "test message", 6000, "TCP")

api.nbReceiveBuffer(...)

Overview

Function to activate, configure and use NB-IoT scratchpad buffer.

Arguments

There are two options:

1. api.nbReceiveBuffer(option, size):

• option (string) - arguments to manipulate with the buffer:
  • "activate" - activate the buffer
  • "deactivate" - deactivate the buffer
  • "dump" - dump content of the buffer
  • "set-size" - set size of the buffer
  • "get-size" - get size of the buffer
• size (integer) - in combination with arguments
  • "dump" - define size to dump (optional)
  • "set-size" - define size of the buffer

2. api.nbReceiveBuffer(start, len, toWrite):

• start (string) - index/location where the first byte will be written
• len (string) - length of data to write into the buffer
• toWrite (string) - data to write into the buffer

Example

-- activate the buffer
api.nbReceiveBuffer("activate")
-- set size
api.nbReceiveBuffer("set-size", 128)
-- insert first byte
api.nbReceiveBuffer(0,1,pack.pack("b",0xF3))
-- send byte (starting from buffer index 1)
api.nbSend("185.8.239.192", 5566, 1, 6000, "UDP")

api.nbAT(command, arg2, arg3, success, err, tryMore, setAwakeBefore, pollBeforeCommand, setAwakeOffAfter, receiveFixedBytes)

Overview

Sends an AT command to NB module with specified timeout. Or use one of the defined commands.

danger

api.nbAT() is a direct access to the AT command interface of the NB-IoT module. It is advanced and should be used with caution.

warning

For a backward-compatible interface, avoid using AT commands directly. Instead, use only api.nbSend() for sending.

Commands

• "AT_DEBUG_OFF" - turn OFF printing of AT commands
• "AT_DEBUG_ON" - turn ON printing of AT commands
• "REINITIALIZE" - re-initialize the NB-IoT module
• "ICCID?" - returns ICCID value of current SIM card
• "IMSI?" - returns IMSI value of current SIM card
• "IMEI?" - returns IMEI value of the modem
• "DOWNLINK_MAX_PERIOD" - If there is no downlink for given value, set timeout to 30 seconds and re-initialize the module.
• "REINIT_HARD_LIMIT_RETRY" - If NB-IoT module is initialized 5 times in a row -> sleep 4 hours and then reset
• "FORCED_REINIT_DONE?" - monitors if "DOWNLINK_MAX_PERIOD" happened (1=true)
• "PSM" - returns power saving mode network status
  1. PSM state
  2. Edrx state
  3. Edrx Requested Value (Period)
  4. Edrx Requested Value (PTW)
  5. Keep Socket Open
  6. Force Rai Single UL
  7. Force Rel 13
  8. Compensate Timeout For Inact Timer
• "ON_TAU_EVENT" - enable/disable on tau event
• "SLEEP_MONITOR" - enable/disable sleep monitor, returns:
  1. Sleep Monitor status (enabled/disabled)
  2. Last Module Suspended Timestamp
  3. Module Sleep Failure Count
• "AT_DEBUG_ON_TX" - turn ON printing of AT commands on transmission
• "SET_CEREG_TRESHOLD" - set AT+CEREG switch threshold
• "TAU_BLANKING" - set Tau blanking interval
• "NET_STATUS?" - returns network status
  • Last Tac
  • Last Cell Id
  • Last Periodic Tau
  • Last Active Time
  • Last Provided Edrx Value
  • Last Provided Edrx Ptw Value
  • Edrx Negotiated
  • Compensate Timeout For Inact Timer Value
• "RADIO_OFF_SLEEP" - turn OFF radio sleep (PSM)
• "UPDATE" - switch to SIM module update mode
• "DTLS" - change PSK and PSK ID for DTLS
• "TIME_SYNC" - synchronize time with SIM module (by deafult done automatically on month change)

Arguments

Default

• command (string) - AT command
• arg2 (integer) - The maximum execution time in milliseconds
• arg3 (integer, optional) - Sending 1 will make sure that module is not asleep

Default SIMCom

• command (string) - AT command
• arg2 (integer) - The maximum execution time in milliseconds
• arg3 (integer, optional) - Sending 1 will make sure that module is not asleep
• success (string, optional) - Specifies a custom success message. The default is "OK"
• err (string, optional) - Specifies a custom error message. The default is "ERROR"
• tryMore (integer, optional) - Number of retries, maximum number of retries is 5, 0 - no answer awaited
• setAwakeBefore (integer, optional) - Sending 1 will set module awake before command
• pollBeforeCommand (integer, optional) - Sending 1 will test if module is listening
• setAwakeOffAfter (integer, optional) - Sending 1 will set module asleep after command
• receiveFixedBytes (integer, optional) - Number of bytes to receive

Other

• "DOWNLINK_MAX_PERIOD" arg2 (integer) - time in milliseconds
• "REINIT_HARD_LIMIT_RETRY" arg2 (integer) - value defining how many times it will re-initialize module before reset
• "DTLS" arg2 (string) - PSK, arg3 (string) - PSK ID

Return

• answer (string) - Nil or non-zero length string with an answer to a AT command
• status (integer) - Zero for success, negative for failure

Example #1

-- Get IMSI number of SIM card with timeout of 4 seconds 
res = api.nbAT("AT+CIMI", 4000)
print(res)

Example #2

-- IMEI --
x=api.nbAT("AT+CGSN")
start = string.find(x, "\n")
finish = string.find(x, "\r", start+1)
imei = string.sub(x,(start+1),(finish-1))
print("IMEI: " .. imei)

Example #3

-- Get signal strength
res,b = api.nbAT("AT+CSQ")
print(res)

Example #4

-- AT_DEBUG_OFF - turn off 
-- AT_DEBUG_ON - turn on
-- REINITIALIZE - re-initialize the NB-IoT module
-- ICCID? - returns ICCID value of current SIM card
-- IMSI? - returns IMSI value of current SIM card
-- IMEI? - returns IMEI value of the modem
api.nbAT("AT_DEBUG_ON")

Example #5

-- If there is no downlink for given value, set timeout to 30 seconds and re-initialize the module.
- api.nbAT("DOWNLINK_MAX_PERIOD", 3*24*3600*1000)

--if NB-IoT module is initialized 5 times in a row -> sleep 4 hours and then reset
- api.nbAT("REINIT_HARD_LIMIT_RETRY", 5)

-- "1" if DOWNLINK_MAX_PERIOD situation happened since reset.
- api.nbAT("FORCED_REINIT_DONE?")

Example #6

-- Starting MQTT connection
mqtt_server =  "server.cz"   --mqtt server
mqtt_user = "uuuuu"
mqtt_password = "pppppp"
mqtt_port = 1883             --mqtt port

at("AT+CSQ")
at("AT+CEREG?")
at("AT+COPS?")
--at("AT+CSSLCFG=\"authmode\",0,0") --,2 for SSL
at("AT+CMQTTSTART", 5000, 0, "+CMQTTSTART: 0") -- start mqtt
at('AT+CMQTTACCQ=0,"'.. getIMSI() .. '"') -- ,1 for SSL
at("AT+CMQTTCONNECT=0,\"tcp://".. mqtt_server..":".. mqtt_port .."\",60,1,\""..mqtt_user.."\",\""..mqtt_password.."\"", 10000, 0, "+CMQTTCONNECT: 0,0")

api.nbReceiveBuffer(str)

Overview

Enables internal buffer to receive NB data. Increases memory efficiency.

Arguments

• str has 3 options:
  • "activate" - activates the internal buffer
  • "deactivate" - deactivates the internal buffer
  • "dump" - dumps the internal buffer

Return

• When "dump" option is used, functions returns the content of the buffer.