Version: Next

Common

This category contains functions that are used for all the devices.

api.ledControl(state)

Overview
Arguments
Example

Turns ON or OFF the on board LED.

tip

It can be also used for debugging purposes.

state (integer) - 1 for ON, 0 for OFF

--turns on blue LED
api.ledControl(1)

api.delayms(ms)

Overview
Arguments
Examples

Pauses the execution for ms milliseconds.

`api.delayms(ms, mode)`

ms (integer) - The number of milliseconds to delay (in range from 0 to 2147483647)
mode (integer, optional) - use sleep in longer intervals:
- 1 - if the interval ms is longer than 10 ms, sleep
- 2 - sleep for defined amount of milliseconds

api.delayms(1000) --delay one second

api.ledControl(1) -- turn on blue LED
api.delayms(1000) -- wait 1 second
api.ledControl(0) -- turn off blue LED

api.delayms(1000,2) -- sleep for one second, then continue in the process

api.randInt(min, max)

Overview
Arguments
Return
Example

Generates random number within given range.

warning

Available only for LoRaWAN devices (function uses it's module to generate random number)

min (integer) - beginning number of the interval (in range from 0 to 2147483647)
max (integer) - end number of the interval (in range from 0 to 2147483647)

-- generates random number within interval from 5 to 20
ran=api.randInt(5, 20)

api.getUniqueNumber()

Overview
Return
Example

Generates unique number.

info

Function increases uint32_t variable by one every time this function is called then it returns it's value. It's in range (in range from 0 to 2^32)*

num (integer) - Unique number (in range from 0 to 2^32)*

--get an unique number
num = api.getUniqueNumber()

api.getBatteryVoltage()

Overview
Return
Example

Retrieves the current voltage level of the battery in mV.

--get battery voltage value in mV
mv = api.getBatteryVoltage()

api.getTick()

Overview
Arguments
Return
Example

Returns current number of milliseconds since startup.

info

Counts up to 2^32 and then restarts from 0. By default it's using RTC derived tick which is incremented during sleep, but it's possible to explicitly select systick, which is not.

`api.getTick(clock, reset)`

clock (integer, optional)
- 3 to use systick, which returns seconds and ms
- 2 to use RTC derived tick and return value in seconds
- 1 to use RTC derived tick and return value in ms (default)
- 0 to use systick (value in ms)
reset (integer, optional) (if first argument is 0)
- 1 - reset systick value to 0
- 0 - do not reset the systick (default)

--get a timestamp, can be used for timing
timestamp = api.getTick()
-- to show the amount of milliseconds you can use print() function
print(timestamp)

--get a timestamp in ms
ms = api.getTick(1)

--get a timestamp in seconds and ms
seconds, ms = api.getTick(3)

api.dumpArray(str)

Overview
Arguments
Example

Prints contents of variable as hexadecimal string (dumps array into console).

`api.dumpArray(str, opt)`

str (string) - variable to print
opt (string, optional) - optional argument defining type of print
- "normal" - printing method used by default
- "raw" - prints only the raw values
- "return" - returns the hex string

--print string "123ef" as hexadecimal
api.dumpArray("123ef")
-- output
-- 00 : 31 32 33 65 66

--print string "123ef" as hexadecimal raw
api.dumpArray("123ef","raw")
-- output
-- 31 32 33 65 66

--return string "123ef" as hexadecimal string
ret = api.dump("123ef","return")

api.float(operation, form, arg1, arg2)

Overview
Operations
Arguments
Return
Examples

Performs operation with given floating point data.

danger

Only available if it's allowed by the firmware.

"add" - addition
"sub" - substraction of arg2 from arg1
"mul" - multiplication
"div" - division of arg1 by arg2
"coerce" - coercion, unary operation using only arg1
"convert" - conversion of integer to float, unary operation using only arg1

op (string) - The operation to perform
form (string) - Two or three characters specifying the format of input/output data: "B" - binary, "S" - string, "I" - integer, "N" - little endian integer
- first position is for arg1
- second parameter either specifies the format of arg2 or if it is the last parameter, specifies the format of the return data, as both share the same format
- by adding “N” to end of a string it coerces and returns little endian integer (optional)
arg1 (string) - The first operation argument, formated as specified in format
arg2 (string) - The second operation argument, formated as specified in format

-- Multiply IEE 754 float with a floating point constant and return coerced value
-- S - string float representation, e.g. “2.234”
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string

ret = api.float("mul", "SSN", "12.8", "1000.0")
print(ret)
-- output = 12800

ret = api.float("mul", "SSS", "12.8", "1000.0")
print(ret)
-- output = 12800.0000

-- hexadecimal interpretation of a number 12.8 is 0x414CCCCD (IEE 754)

x=string.char(0xCD,0xCC,0x4C,0x41)
ret = api.float("mul", "BSS", x, "1000.0")
print(ret)

-- output = 12800.0000

-- Convert integer to IEE 754 float
-- N - Input in little endian integer(for convert only)/Returns ouput as little endian integer
-- I - Binary little endian integer representation as 4 characters/bytes in a string(for convert only).
-- B - binary little endian IEEE 754 representation as 4 characters/bytes in a string
-- > - returns result as big endian, if used as output IEEE 754 representation as 4 characters/bytes in a string
-- < - returns result as little endian, if used as output IEEE 754 representation as 4 characters/bytes in a string (default value)

y=string.char(0xCD,0xCC,0x4C,0x42)
ret = api.float("convert", "IB", y)
api.dumpArray(ret)
-- output = 9A 99 84 4E

y=125
ret = api.float("convert", "NB>", y)
api.dumpArray(ret)
-- output = 42 FA 00 00

api.setVar(index, ...)

Overview
Arguments
Examples

Saves a persistent variable value.

info

Can be used between different wake up iterations.

`api.setVar(index, value, bool)`

index (integer) - Index of the variable to write, index 0 to 15 is available for RAM variables (lost on reset), index 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and index 48 to 1071 is available for variables stored in EEPROM (100k writes).
value (integer) - Value to store at index (in range from 0 to 2147483647)
bool (boolean, optional) - Optional argument, which stores bitwise negation of stored value into address higher by one

`api.setVar(index, mode, value)`

index (integer) - Index of the variable to write, index 0 to 15 is available for RAM variables (lost on reset), index 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and index 48 to 1071 is available for variables stored in EEPROM (100k writes).
mode (string) - Explicit memory mode, currently "bytes" mode supported
value (string) - String array buffer to write

--set persistent variable value from index 1000 to value of 3424
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
api.setVar(1000, 3424)

myVariable = "This is some string to store to eeprom"
api.setVar(29, #myVariable) -- save the length for later readout
api.setVar(30, "bytes", myVariable) -- consumes in total ceil(#myVariable / 4) 32-bit indexes in EEPROM/RAM/HEE

api.getVar(index)

Overview
Arguments
Returns
Examples

Returns persistent variable value.

info

Can be used between different wake up iterations.

`api.getVar(index, default)`

index (integer) - Index of the variable to read, 0 to 15 is available for RAM variables (lost on reset), 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and 48 to 1071 is available for variables stored in EEPROM (100k writes).
default (integer, optional) - Default value, which is returned if value stored in the address is same as bitwise negation of value stored in address higher by one

`api.getVar(index, mode, length)`

index (integer) - Index of the variable to read, 0 to 15 is available for RAM variables (lost on reset), 16 to 47 for High Endurance EEPROM (HEE) variables (6.4M writes) and 48 to 1071 is available for variables stored in EEPROM (100k writes).
mode (string) - Mode to use, currently supported "bytes"
length (integer) - Length in bytes to read

--get persistent variable value from index 1000
--can be used to send different data between wake-ups
--for variables persistent between device reset,
--use indexes 48 to 1071
slotNumber = api.getVar(1000)

stringLength = api.getVar(29)
myReadout = api.getVar(30, "bytes", stringLength)
print(myReadout) -- should print "myVariable" content!

api.wakeUpAt(day, hour, minute, second)

Overview
Arguments
Return
Example

Schedules the next wake up event of the device to provided day of month, hour, minute and second.

info

The provided wake up date is therefore absolute and not relative as in api.wakeUpIn().

`api.wakeUpAt(day, hour, minute, second, resetOnFail)`

day (integer) - Day of month, range from 1 to 31
hour (integer) - Hour, range from 0 to 23
minute (integer) - Minute, range from 0 to 59
second (integer) - Second, range from 0 to 59
resetOnFail (integer, optional) - Reboot device when setting of wake-up event failed: 1 - true, 0 or nothing - false

status (integer) - Execution status, zero for success and -1 for error

--schedules next wake up to the 25th, 2:22:58
status = api.wakeUpAt(25, 2, 22, 58)

api.wakeUpIn(day, hour, minute, second)

Overview
Arguments
Return
Example

Schedules the next wake up event of the device after specified time interval.

info

The provided wake up date is therefore relative and not absolute as in api.wakeUpAt().

note

The input arguments are not limited, but the total period specified must not exceed 31 days. (e.g. hour = 40, days = 2 gives a period of 3 days and 16 hours).

day (integer) - Day, range from 0 to 31
hour (integer) - Hour, range (in range from 0 to 2147483647)
minute (integer) - Minute, range (in range from 0 to 2147483647)
second (integer) - Second, range (in range from 0 to 2147483647)
resetOnFail (integer, optional) - Reboot device when setting of wake-up event failed: 1 - true, 0 or nothing - false
millisecond (integer, optional) - Millisecond, range (in range from 0 to 2147483647)

status (integer) - Execution status, 0 for success and -1 for error

--schedules next wake up in 1 day and 122 minutes
status = api.wakeUpIn(1, 0, 122, 0)

api.getTimeDate()

Overview
Return
Example

Returns current date and time set on this device.

info

The time can be synchronized over LoRa, or when uploading LUA script using LUA scripting interface.

`api.getTimeDate(timezone)`

timezone (integer, optional) - Return time zone shift: 1 - ON, 0 - OFF

--read current date and time
y,M,d,h,m,s = api.getTimeDate()

api.setTimeDate(...)

Overview
Arguments
Example

Set date and time on this device, or calculate the difference and synchronize the date and time.

`api.setTimeDate(year, month, day, hour, minute, second, subsecond, timezone)`

year (integer) - Range from 2016 to any value greater than 2016
month (integer) - Range from 1 to 12
day (integer) - Range from 1 to 31
hour (integer) - Range from 0 to 23
minute (integer) - Range from 0 to 59
second (integer) - Range from 0 to 59
subsecond (integer, optional)
timezone (integer, optional) - Time zone shift in minutes

`api.setTimeDate("DIFF", day, hour, minute, second)`

day (integer) - Range from 1 to 31
hour (integer) - Range from 0 to 23
minute (integer) - Range from 0 to 59
second (integer) - Range from 0 to 59

Calculate and check date based on given values, if there is a difference, synchronize.

--set date and time
api.setTimeDate(2022, 1, 31, 23, 59, 0)

api.voltageSourceState(state)

Overview
Arguments
Example

Controls voltage source.

danger

Only for variants with voltage source. The adjustable voltage option is only available for variant with adjustable voltage source.

`api.voltageSourceState(state, voltage)`

state (integer) - 1 for ON, 0 for OFF
voltage (integer, optional) - Sets the voltage (mV) to the closest possible value (Only available for variant with adjustable option!)

`api.voltageSourceState(operation, voltage)`

operation (string) - Operation to perform:
- "measure" - return source voltage value
- "set-comp-value" - set comparator value
- "get-comp-value" - get comparator value
voltage (integer, optional) - Sets the voltage (mV) to the closest possible value (Only available for variant with adjustable option!)

New generation (NG) of voltage source supports operations

--turn on voltage source
api.voltageSourceState(1)
--turn off voltage source
api.voltageSourceState(0)

api.stdin(option, ...)

Overview
Options
Arguments
Return

Reads stdin (standard input) data or control button (get status, wait for button).

note

This function is using serial line, therefore use of this function in an interactive console (GUI) is not possible.

`api.stdin("start", size)`

option (string)
size (integer, optional) - Memory size (default 1024)

`api.stdin("stop")`

option (string)

`api.stdin("waitbutton", timeout)`

option (string)
timeout (integer, optional) - 0 by default

`api.stdin("read", maxsize)`

option (string)
maxsize (integer, optional) - Maximum size of data, default is 0

`api.stdin("readblock", maxsize, timeout)`

option (string)
maxsize (integer, optional) - Maximum size of data, default is 0
timeout (integer, optional) - 0 by default

`api.stdin("readuntil", maxsize, stopByte, timeout)`

option (string)
maxsize (integer, optional) - Maximum size of data, default is 0
stopByte (integer, optional) - "\n" by default
timeout (integer, optional) - 0 by default

api.stdout(out)

Overview
Arguments

Writes to stdout (standard output) without adding line termination.

tip

Can be useful when implementing raw serial protocols.

`api.stdout(out, size, offset)`

out (string) - String buffer to print to serial console (without adding newlines, raw print)
size (integer, optional) - Size of out to print (default prints entire out in other words #out)
offset (integer, optional) - Number of bytes to skip in out, default is 0

api.bsprintf(binData, format)

Overview
Arguments
Example

Formats binary stream data according to various format specifiers, including support for characters, integers, short and long integers, floats, and doubles.

`api.bsprintf(binData, format, offset, endian)`

binData (string) - String buffer to print to serial console (without adding newlines, raw print)
format (string) - Size of out to print (default prints entire out in other words #out)
offset (integer, optional) - Number of bytes to skip in out (default 0)
endian (string, optional) - "little" (default) or "big"

Supported formats:

Character: "c"
Short integers: "hd", "hi", "hu", "hx", "hX", "ho", "hb", "h"
Long long integers: "lld", "lli", "llu", "llx", "llX", "llo", "llb", "ll"
Integers: "d", "i", "u", "x", "X", "o", "b"
Doubles: "e", "E", "g", "G", "lf"
Floats: "f", "F"

-- binary string
x=pack.pack("b8",1,2,3,4,5,6,7,8)
-- memory print
api.dumpArray(x) -- 00 : 01 02 03 04 05 06 07 08

y=api.bsprintf(x,"%d") -- format 4-byte integer, little endian

print(y) -- output: 67305985

api.setVerbosity(num)

Overview
Arguments
Example

Controls the number of messages printed to the serial line.

`api.setVerbosity(num, opt)`

num (integer) - Sets general verbosity level:
- 0 - NONE
- 1 - IMPORTANT
- 2 - ERROR
- 3 - WARNING
- 4 - INFO (set by default)
- 5 - SLOW
- 6 - MAX
opt (string, optional) - Specifying verbosity to specific function:
- "LORA"
- "LORA_HW"
- "RADIO"
- "LORA_TIMER"
- "NBIOT"
- "RTC"
- "HWAPI_COMMON"
- "HWAPI_DALI"
- "HWAPI_DIO"
- "HWAPI_DS18B20"
- "HWAPI_LORA"
- "HWAPI_MBUS"
- "HWAPI_MEMORY"
- "HWAPI_RS485"
- "HWAPI_S0"
- "HWAPI_SENSIRION"
- "HWAPI_TIME"
- "HWAPI_UART"
- "HWAPI_WMBUS"
- "WMBUS_HW"

List of available specifiers depending on the version of the converter

`####` api.setVerbosity(num, "TIMESTAMP_MODE")`

num (integer) - Sets verbosity level in case of "TIMESTAMP_MODE" specified:
- 0 - NONE
- 1 - TICK
- 2 - RTC_TICK
- 3 - TIME
- 4 - DATETIME
opt (string, optional) - Specifier

Configuration of timestamp verbosity

--turn off timestamp
api.setVerbosity(0,"TIMESTAMP_MODE")

api.exec(command, ...)

Overview
Commands
Arguments
Return
Example

Executes a system command or Lua fragment.

info

Additionally uploaded Configuration API extension, according to https://ieeexplore.ieee.org/document/8733437.

"_get_wake_info" - Returns wake-up reason, serial status, and NB-IoT serial status
"_free_mem" - Returns number of free heap memory in bytes
"_sysinfo" - Returns table with system information
"_format_eeprom" - Erases internal device EEPROM to value 0xFF

Deletes last Lua error report and all values set by api.setVar()
"_get_last_error" - Returns last error entry
"_current_serial_log" - Returns current serial log history (1024 byte string)
"_sleep" - Sleeps for provided time
"acrComTx" - Send payload as "acrCom" communication protocol frame (used internally with gui.acrios.com)
"_reset" - Resets the device, starting again by running bootloader
"_interactive_line_maxlen" - Set or get max length of input for interactive mode
"_cpu_temp" - Returns CPU temperature in Celsius (+-5 deg. C)
"_acrComHeader" - Returns ACR-COM header
"_print_mode" - Configures print mode
"clearSwWdogNoCom" - Clears no-communication watchdog

If the function api.nbSend() or api.loraSend() isn't called for certain time (7 days by default), device resets. You can prevent this by using this function.
"clearSwWdogNoSleep" - Clears no-sleep watchdog

If device doesn't go to sleep for certain time (3 days by default), it resets. To prevent this from happening, you can call this function.
"setSwWdogNoComReloadValue" - Sets no-communication watchdog value
"setSwWdogNoSleepReloadValue" - Sets no-sleep watchdog value
"_set_crlf_handler" - Sets CRLF handling
"_has_new_reset_log" - Flag showing whether asynchronous serial log was detected
"_get_unix_time" - Returns ime/date as single seconds value since the Epoch (1.1. 1970) (UNIX timestamp)
"_set_unix_time" - Sets time/date using UNIX format
"_serialInterrupt" - Configures serial interrupt
"_sysclk" - Sets clock of the Microcontroller in Hz
"_reset_reason" - Returns string describing reset reason
"_sleep_mode" - *Sets sleep mode globally (same mode as in api.delayms())
"_keep_source_in_sleep" - *Keep the supply ON during sleep mode (Only available for converters variants with power supply!)
"_cc" - *Returns specified information from Coulomb Counter (Only available for converters variants with Coulomb Counter!)
"_sc" - Controls supercapacitor
"_SENSUS_BUP_parse" - Parses Bubble Up Protocol message
"_hw_features" - Checks for the (specified) hardware features
"_fastWake" - Controls fast wake-up function - skips onWake() event
"_noNBIOTinit" - Controls SIM module initialization

`api.exec("_get_wake_info")`

command (string)

`api.exec("_free_mem")`

command (string)

`api.exec("_sysinfo")`

command (string)

`api.exec("_format_eeprom", filler)`

command (string)
filler (string, optional) - Erases internal device EEPROM to provided value

`api.exec("_get_last_error", reportType, action, start, end)`

command (string)
reportType (string) - Type of report to read:
- "SHORT" - Short description of Lua error
- "TRACEBACK" - Text traceback including global and local variables values
- "STDOUT" - Last 1024 bytes of stdout prints before the crash
- "STDOUT_RAW" - As "STDOUT" but uncompressed, printable
- "TRACEBACK_RAW" - As "TRACEBACK" but uncompressed, printable
- "ALL" - "TRACEBACK" and "STDOUT" combined
action (string/integer) - Action to execute with given entry type:
- "len" - Returns length of given type in bytes
- "clear" - Clears last error entry
- Bytes offset since start of entry type to return, default is 0
end (integer) - End index of buffer to return, use -1 to return all

Check LUA script for example

`api.exec("_current_serial_log")`

command (string)

`api.exec("_sleep", seconds, milliseconds)`

command (string)
seconds (integer, optional) - Number of seconds to sleep, default is 0
milliseconds (integer, optional) - Number of milliseconds to sleep, default is 0

Sleeps for provided number of seconds or if seconds is 0, sleeps without RTC timeout, use with caution!

`api.exec("acrComTx", data)`

command (string)
data (string) - Send payload as "acrCom" communication protocol frame

`api.exec("_reset", softReset)`

command (string)
softReset (int, optional) - 1 for soft reset (restart application only)

`api.exec("_interactive_line_maxlen", value)`

command (string)
value (integer, optional) - Size of input command buffer in bytes, default is 2048 bytes

`api.exec("_cpu_temp")`

command (string)

`api.exec("_acrComHeader", data)`

command (string)

data (string) - String buffer to use to compute the header from

def CB_calculateCrc16(data):
  def crc16_ccitt_update(byte, crc):
      # For each bit in the data byte, starting from the leftmost bit
      for i in range(7, -1, -1):
          # If leftmost bit of the CRC is 1, we will XOR with
          # the polynomial later
          xor_flag = (crc & 0x8000) != 0

          # Shift the CRC, and append the next bit of the
          # message to the rightmost side of the CRC
          crc = crc << 1
          if (byte & (1 << i)) != 0:
              crc = crc | 1

          # Perform the XOR with the polynomial
          if xor_flag:
              crc = crc ^ 0x1021
      return crc & 0xFFFF

  retCrc = 0xFFFF

  # last is the payload
  for i in range(len(data)):
      retCrc = crc16_ccitt_update(data[i], retCrc)

  # Augment 16 zero-bits
  for i in range(2):
      retCrc = crc16_ccitt_update(0, retCrc)
  return retCrc

Python code for CRC16 calculation

`api.exec("_print_mode", mode)`

command (string)
mode (string) - Print mode configuration:
- "ALL" - Print even if no serial line is not connected (default)
- "CONNECTED" - Print only when serial line is connected
- "NONE" - Do not print

`api.exec("clearSwWdogNoCom")`

command (string)

`api.exec("clearSwWdogNoSleep")`

command (string)

`api.exec("setSwWdogNoComReloadValue", value)`

command (string)
value (integer) - Value of no-communication watchdog, default is 7 days

`api.exec("setSwWdogNoSleepReloadValue", value)`

command (string)
value (integer) - Value of no-sleep watchdog, default is 3 days

`api.exec("_set_crlf_handler", mode)`

command (string)
mode (string) - Settings of CRLF handling:
- "noprint" - Removes CRLF
- "asis" - Leaves CRLF as is
- "space" - Replaces CRLF with space
- "newline" - Replaces CRLF with newline ("\n")

`api.exec("_has_new_reset_log")`

command (string)

`api.exec("_get_unix_time")`

command (string)

`api.exec("_set_unix_time", time)`

command (string)
time (integer) - UNIX timestamp

`api.exec("_serialInterrupt", enable, waitConfig)`

command (string)
enable (boolean) - true for enable, false for disable
waitConfig (boolean) - Wait for config inside of onWake function: true for enable, false for disable

`api.exec("_sysclk", clock)`

command (string)
clock (integer) - Clock of the Microcontroller in Hz:
- 32000000 - 32000000 Hz (default)
- 48000000 - 48000000 Hz
- 24000000 - 24000000 Hz
- 16000000 - 16000000 Hz
- 2000000 - 2000000 Hz
- 1000000 - 1000000 Hz
- 800000 - 800000 Hz
- 400000 - 400000 Hz
- 200000 - 200000 Hz
- 100000 - 100000 Hz

`api.exec("_reset_reason")`

command (string)

`api.exec("_sleep_mode", mode)`

command (string)
mode (integer) - Sleep mode globally:
- 1 - If the interval ms is longer than 10 ms, sleep
- 2 - Sleep for defined amount of milliseconds

`api.exec("_keep_source_in_sleep", state)`

command (string)
state (integer) - 1 for enable, 0 for disable

Only available for converters variants with power supply!

`api.exec("_cc", cmd)`

command (string)
cmd (string, optional) - Command for Coulomb Counter:
- "set" - Set Coulomb Counter
  - value (integer) - Value to set
- "dump" - Dump Coulomb Counter

If no command is provided, the Coulomb Counter values are returned. Only available for converters variants with Coulomb Counter!

`api.exec("_sc", option)`

command (string)
option (integer) - 1 - force connect supercapacitor, 2 - force disconnect supercapacitor, 3 - leave supercapacitor as floating

`api.exec("_SENSUS_BUP_parse", data, key, keyIndex)`

command (string)
data (string) - Input data to parse
key (string, optional) - If no key is defined, the default key is used
keyIndex (integer, optional) - Key index

`api.exec("_hw_features", option)`

command (string)
option (string, optional) - Option to check, if empty, the full hardware report is returned
- "SIM7022" - If the SIM7022 module is present
- "SC" - If supercapacitor is present
- "SC_CAP" - If 1F - 220 F supercapacitor is present
- "NB" - NB-IoT variant
- "SX1261" - SX1261 is present
- "CC" - Coulomb counter is present
- "SC_MNGMNT" - Management for supercapacitor is present
- "LIC" - Supercapacitor based on LiC is present
- "AC" - EAC variant
- "MBUS" - M-Bus variant
- "RS485" - RS485/Modbus variant
- "ADJSRC" - Variable additional source is present
- "EXTSRC" - Additional source is present
- "MBUSNG" - New generation of MBUS

`api.exec("_fastWake", state)`

command (string)
state (integer) - 1 for enable, 0 for disable

`api.exec("_noNBIOTinit", state)`

command (string)
state (integer) - 1 for enable, 0 for disable

`api.exec("_get_wake_info")`

wake-up reason (string)
- "button" - Button was pressed
- "serial" - Serial interface connected
- "timer" - RTC wake-up timer
serial status (string)
- "connected" - Serial line is connected
- "disconnected" - Serial line is disconnected (not detected)
NB-IoT serial status (string)
- "active" - Module serial output (transmit) is high - module is active
- "inactive" - Module likely sleeps, serial line is low

`api.exec("_free_mem")`

freeheap (integer) - Free heap memory in bytes

`api.exec("_sysinfo")`

values (table)
- values["SN"] - Returns Serial Number of the device (-1 for old devices)
- values["ver"] - Firmware version in format 2.9.12 (major.minor.bugfix)
  - values["ver"]["major"] - Major firmware version
  - values["ver"]["minor"] - Minor firmware version
  - values["ver"]["bugfix"] - Bugfix firmware version
  - values["ver"]["sha"] - SHA reference to git repository
- values["tim"] - Build time
  - values["tim"]["hour"] - Build hour
  - values["tim"]["min"] - Build minute
  - values["tim"]["sec"] - Build second
- values["date"] - Build date
  - values["date"]["yr"] - Build year
  - values["date"]["mon"] - Build month
  - values["date"]["day"] - Build day of month
- values["model"] - Device model information
  - values["model"]["name"] - Name of device model of ACR-CV, e.g. "ACR_CV_101N_W_D2_DEDICATED"
  - values["model"]["source"] - Power source name, "ac" or "battery"

`api.exec("_get_last_error", reportType, action, start, end)`

error (string) - Last error entry

`api.exec("_current_serial_log")`

log (string) - Current serial log history (1024 bytes)

`api.exec("_interactive_line_maxlen", value)`

length (integer) - Max length of input for interactive mode

`api.exec("_cpu_temp")`

temperature (integer) - CPU temperature in Celsius (+-5 deg. C)

`api.exec("_acrComHeader", data)`

header (string) - ACR-COM header containing 7 bytes: [0x00][little endian data length (2 bytes)][bitwise negation of previous field (2 bytes)][CRC16-CCIT (2 bytes)]

`api.exec("_print_mode", mode)`

mode (string) - Print mode
- "ALL" - Print even if no serial line is not connected (default)
- "CONNECTED" - Print only when serial line is connected
- "NONE" - Do not print

`api.exec("_has_new_reset_log")`

flag (boolean) - Flag showing whether asynchronous serial log was detected

`api.exec("_get_unix_time")`

time (integer) - Time/date as single seconds value since the Epoch (1.1. 1970) (UNIX timestamp)

`api.exec("_set_unix_time", time)`

time (integer) - Time/date as single seconds value since the Epoch (1.1. 1970) (UNIX timestamp)

`api.exec("_sysclk", clock)`

clock (integer) - Clock of the Microcontroller in Hz

`api.exec("_reset_reason")`

number (integer) - Reset reason number
reason (string) - Reset reason

`api.exec("_sleep_mode", mode)`

mode (integer) - Global sleep mode

`api.exec("_keep_source_in_sleep", state)`

state (integer) - Keep the supply ON during sleep mode

`api.exec("_cc", cmd)`

"set":
- result (integer) - Result of register write (0 - success, negative on error)
"dump":
- Dumps registers from the coulomb counter

Default:

result (integer) - Result of register readout (0 - success, negative on error)
mAh (integer) - Accumulated charge in mAh
ESR (integer) - Equivalent Series Resistance estimate of battery [mOhm]
in100V (integer) - Input (battery) voltage, when 100 mA is sourced from battery [mV]
inV (integer) - Input (battery) voltage, when battery is disconnected (ultra low power mode) [mV]
SC100 (integer) - Output (super-capacitor) voltage, when 100 mA is sourced from battery [mV]
SC (integer) - Output (super-capacitor) voltage, when battery is disconnected (ultra low power mode) [mV]
temp (integer) - Temperature in °C

`api.exec("_SENSUS_BUP_parse", data, key, keyIndex)`

meterId (string) - Meter ID
value (string) - Value
flags (string) - Flags
frameType (string) - Frame type
originalFrame (string) - Original frame

`api.exec("_hw_features", option)`

hwCheck (boolean) - true if the specified hardware feature is present, false if not

If no option is provided, the full hardware report is returned
boardVersion (string) - Board Version
productionTime (string) - Production Time
featureSet (string) - Feature Set
variantChar1 (string) - Variant char 1
variantChar2 (string) - Variant char 2
variantChar3 (string) - Variant char 3
variantChar4 (string) - Variant char 4
variantMajor (string) - Variant major
variantMinor (string) - Variant minor
variantBugfix (string) - Variant bugfix
variantFormFactor (string) - Variant formFactor

-- get converter model and power source

print(api.exec("_sysinfo")["model"]["name"]) --result e.g.: ACR_CV_101N_R_EAC

print(api.exec("_sysinfo")["model"]["source"]) --result e.g.: ac

hasNGMbus = api.exec("_hw_features", "MBUSNG:1")

print(hasNGMbus) -- return true/false

api.table(operation, ...)

Overview
Operations
Arguments
Return
Example

Interface to create and manipulate memory-efficient tables and maps.

tip

Check multimode script or sendOnce script for example usage.

`api.table("set-max-id", maxId)`

operation (string)
maxId (integer) - Maximum table index, must be >= 1

`api.table("get-max-id")`

operation (string)

`api.table("new", tableId, type, maxLength)`

operation (string)
tableId (integer) - ID of newly created table, please use set-max-id first!
type (string) - Type of the table:
- "U32" - Table is a list of integers of unsigned 32bit length
- "I8" - Table is a list of signed 8bit integers
- "U32-I8" - Table is a map/dictionary with U32 as key and I8 as value
- "STR" - Table is a list of strings
maxLength (integer) - Maximum number of table entries

`api.table("dispose", tableId)`

operation (string)
tableId (integer) - ID of an existing table

`api.table("insert", tableId, value)`

operation (string)
tableId (integer) - Table ID
U32 or I8 type:
- value (integer) - Value to insert at the end of list
U32-I8 type:
- key (integer) - Key to use in the map/dictionary
- value (integer) - Value to store at given key entry
STR type:
- value (string) - String to insert

`api.table("index-of", tableId, value)`

operation (string)
tableId (integer) - Table ID
value (integer) - Value to search a key for

`api.table("get-index", tableId, index)`

operation (string)
tableId (integer) - Table ID
index (integer) - Returns value at given key/index

`api.table("get-index-length", tableId, index)`

operation (string)
tableId (integer) - Table ID
index (integer) - Returns length at given key/index

`api.table("set-index", tableId, index, value)`

operation (string)
tableId (integer) - Table ID
index (integer) - Key or index to set the value at
value (integer) - Value to set

`api.table("used", tableId)`

operation (string)
tableId (integer) - Table ID to check

`api.table("clear", tableId)`

operation (string)
tableId (integer) - Table ID to clear

`api.table("get-max-id")`

maxId (integer) - Maximum table index

`api.table("insert", tableId, value)`

status (integer) - 0 on success
used (integer) - Number of entries in the table
maxLength (integer) - Maximum number of entries in the table

`api.table("index-of", tableId, value)`

index (integer) - Index of the first occurrence of value in the table, nil if not found

`api.table("get-index", tableId, index)`

value (integer) - Value at given index, nil if not found

`api.table("get-index-length", tableId, index)`

length (integer) - Length of the value at given index, nil if not found

`api.table("used", tableId)`

used (integer) - Number of entries in the table

Example how to insert string into table:

--Setup table--
api.table("set-max-id", 1)
api.table("new", 1, "STR", 100)

--Inserting the value--
api.table("insert", 1, "Hello")

--Getting the value--
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: Hello

--Getting index with the value--
s=api.table("index-of",1,"Hello") print(s)
--Response--
~> [STDOUT]: 1

--Getting the length of the index--
a=api.table("get-index-length",1,1) print(a)
--Response--
~> [STDOUT]: 5

--Clearing the table--
api.table("clear",1,1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [STDOUT]: nil

--Removing table--
api.table("dispose",1)
y=api.table("get-index", 1, 1) print(y)
--Response--
~> [HWAPI_COMMON]: Cannot index in non-existent table ID 1
~> [STDOUT]: -1

api.aes(operation, data, iv, key)

Overview
Arguments
Example

Encrypts or decrypts provided payload using a key and IV with AES-CTR.

tip

See this section for more information and examples.

operation (string) - "encrypt" or "decrypt"
data (string) - Data to encode or decode
iv (string) - Initialization vector (16 bytes)
key (string) - Key (16 bytes)

--assemble initialization vector
--fill wmbusID, wmbusID, transmissionCounter, transmissionCounter values
function getIV()
    return pack.pack("<I4", wmbusID, wmbusID, transmissionCounter, transmissionCounter)
end

--example of encryption (payload is the data to encrypt)
encpayload = api.aes("encrypt",payload, getIV(), key)

api.ledControl(state)

api.delayms(ms)

api.delayms(ms, mode)​

api.randInt(min, max)

api.getUniqueNumber()

api.getBatteryVoltage()

api.getTick()

api.getTick(clock, reset)​

api.dumpArray(str)

api.dumpArray(str, opt)​

api.float(operation, form, arg1, arg2)

api.setVar(index, ...)

api.setVar(index, value, bool)​

api.setVar(index, mode, value)​

api.getVar(index)

api.getVar(index, default)​

api.getVar(index, mode, length)​

api.wakeUpAt(day, hour, minute, second)

api.wakeUpAt(day, hour, minute, second, resetOnFail)​

api.wakeUpIn(day, hour, minute, second)

api.getTimeDate()

api.getTimeDate(timezone)​

api.setTimeDate(...)

api.setTimeDate(year, month, day, hour, minute, second, subsecond, timezone)​

api.setTimeDate("DIFF", day, hour, minute, second)​

api.voltageSourceState(state)

api.voltageSourceState(state, voltage)​

api.voltageSourceState(operation, voltage)​

api.stdin(option, ...)

api.stdin("start", size)​

api.stdin("stop")​

api.stdin("waitbutton", timeout)​

api.stdin("read", maxsize)​

api.stdin("readblock", maxsize, timeout)​

api.stdin("readuntil", maxsize, stopByte, timeout)​

api.stdout(out)

api.stdout(out, size, offset)​

api.bsprintf(binData, format)

api.bsprintf(binData, format, offset, endian)​

api.setVerbosity(num)

api.setVerbosity(num, opt)​

#### api.setVerbosity(num, "TIMESTAMP_MODE")`​

api.exec(command, ...)

api.exec("_get_wake_info")​

api.exec("_free_mem")​

api.exec("_sysinfo")​

api.exec("_format_eeprom", filler)​

api.exec("_get_last_error", reportType, action, start, end)​

api.exec("_current_serial_log")​

api.exec("_sleep", seconds, milliseconds)​

api.exec("acrComTx", data)​

api.exec("_reset", softReset)​

api.exec("_interactive_line_maxlen", value)​

api.exec("_cpu_temp")​

api.exec("_acrComHeader", data)​

api.exec("_print_mode", mode)​

api.exec("clearSwWdogNoCom")​

api.exec("clearSwWdogNoSleep")​

api.exec("setSwWdogNoComReloadValue", value)​

api.exec("setSwWdogNoSleepReloadValue", value)​

api.exec("_set_crlf_handler", mode)​

api.exec("_has_new_reset_log")​

api.exec("_get_unix_time")​

api.exec("_set_unix_time", time)​

api.exec("_serialInterrupt", enable, waitConfig)​

api.exec("_sysclk", clock)​

api.exec("_reset_reason")​

api.exec("_sleep_mode", mode)​

api.exec("_keep_source_in_sleep", state)​

api.exec("_cc", cmd)​

api.exec("_sc", option)​

api.exec("_SENSUS_BUP_parse", data, key, keyIndex)​

api.exec("_hw_features", option)​

api.exec("_fastWake", state)​

api.exec("_noNBIOTinit", state)​

api.exec("_get_wake_info")​

api.exec("_free_mem")​

api.exec("_sysinfo")​

api.exec("_get_last_error", reportType, action, start, end)​

api.exec("_current_serial_log")​

`api.delayms(ms, mode)`

`api.getTick(clock, reset)`

`api.dumpArray(str, opt)`

`api.setVar(index, value, bool)`

`api.setVar(index, mode, value)`

`api.getVar(index, default)`

`api.getVar(index, mode, length)`

`api.wakeUpAt(day, hour, minute, second, resetOnFail)`

`api.getTimeDate(timezone)`

`api.setTimeDate(year, month, day, hour, minute, second, subsecond, timezone)`

`api.setTimeDate("DIFF", day, hour, minute, second)`

`api.voltageSourceState(state, voltage)`

`api.voltageSourceState(operation, voltage)`

`api.stdin("start", size)`

`api.stdin("stop")`

`api.stdin("waitbutton", timeout)`

`api.stdin("read", maxsize)`

`api.stdin("readblock", maxsize, timeout)`

`api.stdin("readuntil", maxsize, stopByte, timeout)`

`api.stdout(out, size, offset)`

`api.bsprintf(binData, format, offset, endian)`

`api.setVerbosity(num, opt)`

`####` api.setVerbosity(num, "TIMESTAMP_MODE")`

`api.exec("_get_wake_info")`

`api.exec("_free_mem")`

`api.exec("_sysinfo")`

`api.exec("_format_eeprom", filler)`

`api.exec("_get_last_error", reportType, action, start, end)`

`api.exec("_current_serial_log")`

`api.exec("_sleep", seconds, milliseconds)`

`api.exec("acrComTx", data)`

`api.exec("_reset", softReset)`

`api.exec("_interactive_line_maxlen", value)`

`api.exec("_cpu_temp")`

`api.exec("_acrComHeader", data)`

`api.exec("_print_mode", mode)`

`api.exec("clearSwWdogNoCom")`

`api.exec("clearSwWdogNoSleep")`

`api.exec("setSwWdogNoComReloadValue", value)`

`api.exec("setSwWdogNoSleepReloadValue", value)`

`api.exec("_set_crlf_handler", mode)`

`api.exec("_has_new_reset_log")`

`api.exec("_get_unix_time")`

`api.exec("_set_unix_time", time)`

`api.exec("_serialInterrupt", enable, waitConfig)`

`api.exec("_sysclk", clock)`

`api.exec("_reset_reason")`

`api.exec("_sleep_mode", mode)`

`api.exec("_keep_source_in_sleep", state)`

`api.exec("_cc", cmd)`

`api.exec("_sc", option)`

`api.exec("_SENSUS_BUP_parse", data, key, keyIndex)`

`api.exec("_hw_features", option)`

`api.exec("_fastWake", state)`

`api.exec("_noNBIOTinit", state)`

`api.exec("_get_wake_info")`

`api.exec("_free_mem")`

`api.exec("_sysinfo")`

`api.exec("_get_last_error", reportType, action, start, end)`

`api.exec("_current_serial_log")`

`api.exec("_interactive_line_maxlen", value)`

`api.exec("_cpu_temp")`

`api.exec("_acrComHeader", data)`

`api.exec("_print_mode", mode)`

`api.exec("_has_new_reset_log")`

`api.exec("_get_unix_time")`

`api.exec("_set_unix_time", time)`

`api.exec("_sysclk", clock)`

`api.exec("_reset_reason")`

`api.exec("_sleep_mode", mode)`

`api.exec("_keep_source_in_sleep", state)`

`api.exec("_cc", cmd)`

`api.exec("_SENSUS_BUP_parse", data, key, keyIndex)`

`api.exec("_hw_features", option)`

`api.table("set-max-id", maxId)`

`api.table("get-max-id")`

`api.table("new", tableId, type, maxLength)`

`api.table("dispose", tableId)`

`api.table("insert", tableId, value)`

`api.table("index-of", tableId, value)`