LTE Beacon: Micro-app API reference
Micro-apps are written in JavaScript. All of ECMAScript 5.1 is supported. Select things from ECMAScript 2015 (also known as the “6th edition”, or “ECMAScript 6”) are also supported:
- arrow functions
- classes
- enhanced object literals (shorthands & computed/dynamic property names)
- default function arguments
- template literals
- promises
-
ArrayBuffer
and typed arrays Object.keys
Some notably-not-supported ES2015 features:
-
let
andconst
- destructuring
- spread and rest
...
operators - iterators and
for ... of
-
Object.values
and.entries
-
DataView
,Map
,Set
- (and more)
None of ES2016 and beyond is supported at this time, most notable ommision being async
and await
.
Other than that, here’s a list of LTE-Beacon–specific functions and APIs.
Valid for firmware 0.1.5. See API reference for other firmware versions.
- Global functions
- Timer functions
- Bluetooth Low Energy functions
- Creating BLE packets
- Input/Output
- Accelerometer
- Battery
- Temperature
- Cloud communication
- Data synchronisation
- Storage
- Location
- UWB ranging
- System
- LTE
- Application
Global functions
print(text)
Description: Prints message on debug console.
Note: This is a blocking function when connected via Bluetooth. It may slow down application.
Arguments:
- text (stringable) - Text that will be displayed on console.
toHex
toHex(array)
Description: Converts arraybuffer/array of numbers to hex string
Arguments:
- array (object) - Array of numbers or
ArrayBuffer
that will be converted to hex string.
Returns: object
setTimeout
Warning: This is a deprecated API and it is subject to change or removal.
setTimeout(callback, interval)
Description: Start single shot timer (alias for timers.single(...)
)
Arguments:
-
callback (function) - Callback function that will be called when timer fires
Function signature:
() => ...
-
interval (number, unit: ms) - Number of milliseconds that timer will wait before invoking callback
Returns: handle object
Handler object methods:
- handler.stop() - Stops timer. Calling on stoped timer has no effect.
Errors thrown:
- ESR0004 Not enough resources
setInterval
Warning: This is a deprecated API and it is subject to change or removal.
setInterval(callback, interval)
Description: Start repeated timer (alias for timers.repeat(...)
)
Arguments:
-
callback (function) - Callback function that will be called when timer fires
Function signature:
() => ...
-
interval (number, unit: ms) - Number of milliseconds that timer will wait before invoking callback
Returns: handle object
Handler object methods:
- handler.stop() - Stops timer. Calling on stoped timer has no effect.
Errors thrown:
- ESR0004 Not enough resources
clearTimeout
Warning: This is a deprecated API and it is subject to change or removal.
clearTimeout(handler)
Description: Stops timer. Alias for timerHandler.stop()
Arguments:
- handler (pure_object) - Timer handler object returned by setTimeout
clearInterval
Warning: This is a deprecated API and it is subject to change or removal.
clearInterval(handler)
Description: Stops timer. Alias for timerHandler.stop()
Arguments:
- handler (pure_object) - Timer handler object returned by
setInterval
Timer functions
Timer functions that allow to schedule tasks asynchronously
single
timers.single(interval, callback)
Description: Start single shot timer
Arguments:
- interval (interval, unit: ms) - Number of milliseconds that timer will wait before invoking callback
-
callback (function) - Callback function that will be called when timer fires
Function signature:
() => ...
Returns: handle object
Handler object methods:
-
handler.stop() - Stops timer. Calling on stoped timer has no effect.
-
handler.reset(interval = 0) - Resets timer. Calling on stoped timer will schedule it again.
- interval (interval, unit: ms, optional) - New interval in milliseconds. If ommited (or 0) previous interval will be used.
Errors thrown:
- ESR0004 Not enough resources
repeat
timers.repeat(interval, callback)
Description: Start repeated timer.
Arguments:
- interval (interval, unit: ms) - Number of milliseconds that timer will wait before invoking callback
-
callback (function) - Callback function that will be called when timer fires
Function signature:
() => ...
Returns: handle object
Handler object methods:
-
handler.stop() - Stops timer. Calling on stopped timer will have no effect.
-
handler.restart(interval = 0) - Restarts repeated timer. Works only on stopped timer.
- interval (interval, unit: ms, optional) - New interval in milliseconds. If ommited (or 0) previous interval will be used.
Errors thrown:
- ESR0004 Not enough resources
at
timers.at(timestamp, callback)
Description: Invoke timer at specified UTC time.
Arguments:
- timestamp (any) - UTC time in milliseconds or
Date
object -
callback (function) - Callback function that will be called when timer fires.
Function signature:
() => ...
Returns: handle object
Handler object methods:
- handler.stop() - Stops timer. Calling on stopped timer will have no effect.
Errors thrown:
- ESR0004 Not enough resources
Bluetooth Low Energy functions
Bluetooth Low Energy scanning and advertising functions
advertise
Variant 1:
ble.advertise(callback)
Description: This variant will call given function that will provide BLE packet that will be advertised.
Arguments:
-
callback (function) - Callback function that will provide packet each time it will be advertised. Returned object has to have similar structure to scan records received by
ble.startScan(...)
function.Function signature:
(txPower) => ...
- txPower (number, since: 0.0.8) - Transmit power used to send this advertisement for convinient adjusting measured power.
Variant 2:
ble.advertise(data)
Description: This variant will advertise statically defined packet.
Arguments:
- data (object) - Packet that will be advertised. Similar to the structure of scan records received by
ble.startScan(...)
function.
Returns: handle object
Handler object methods:
-
handler.stop() - Stops advertiser
-
handler.interval(interval) - Sets new advertising interval. Shorter interval - more power consumed. Longer interval - more difficult to quickly detect.
- interval (interval, unit: ms, min: 100) - Interval in milliseconds
-
handler.power(interval) - Sets new advertising power (in dBm).
- interval (number, unit: dBm, min: -40, max: 20) - Power in dBm. Allowed values are -40, -20, -16, -12, -8, -4, 0, 4, 8, 20.
If different value is passed, advertising power will set to highest valid value lower than the value given (eg. 7 will snap to 4).
- interval (number, unit: dBm, min: -40, max: 20) - Power in dBm. Allowed values are -40, -20, -16, -12, -8, -4, 0, 4, 8, 20.
Errors thrown:
- ESR0004 Not enough resources
startScan
ble.startScan(callback, duration = 10000)
Description: Start scanning for BLE packets. It returns promise that will be resolved when scan stops (either from timeout or ble.stopScan(...)
).
Arguments:
-
callback (function) - Callback function that will be called when new packet is detected.
Using blocking functions (likeprint
) in this callback may slow down scanning and miss some packets. Note that in the example packet is only printed out when it was succesfully recognized as Estimote Location to minimize blocking byprint
.Function signature:
(scanRecord) => ...
- scanRecord (object) - Raw BLE advertising packet.
Object fields:
- rssi (number, unit: dBm) - Received packet signal strength (RSSI)
- channel (number, since: 0.0.8) - Channel number (37,38,39) on which packet was received
- scanResponse (bool, since: 0.0.9) - ‘true’ if received packet is a scan response
- connectable (bool, since: 0.0.9) - ‘true’ if received packet is connectable
- addr (arraybuffer) - MAC device address
- name (string, optional) - Device advertised name
- manufData (arraybuffer, optional) - Manufacturers data
- serviceData (object, optional) - Service data map. Key (service UUID) is a string, value is an arraybuffer.
- serviceUUIDs (array, optional) - Array of arraybuffers with UUIDs of services.
- txPower (number, unit: dBm, optional) - Advertised transmit power
- flags (number, optional) - Advertised packet flags
Example:
{ "rssi": -67, "channel": 37, "scanResponse": false, "connectable": true, "addr": "feab1214112c", "name": "MyDevice", "manufData": "fe34567689", "serviceData": { "fe9a": "fe124566783234534" }, "serviceUUIDs": [ "fe9a" ], "txPower": 4, "flags": 2 }
-
duration (interval, unit: ms, optional) - Scan duration. 0 if there is no time limit. Default value is 10000ms (10s).
Invocation example:
ble.startScan((scanRecord) => {
var packet = ble.parse(scanRecord)
if (packet && packet.type === 'est_loc') {
print(JSON.stringify(packet))
}
}, 10000)
Returns: promise
parse
ble.parse(scanRecord)
Description: Parses scanned raw BLE advertisement and extracts data. It can recognize most common packets like iBeacon or Eddystone and Estimote.
Arguments:
- scanRecord (object) - Raw BLE packet scanned provided by startScan callback
Returns: object
stopScan
ble.stopScan(resolvePromise = true)
Description: Stop BLE scanning immediately.
Arguments:
- resolvePromise (bool, optional) - If true then the startScan promise will be resolved
Invocation example:
ble.stopScan(true)
Creating BLE packets
Builders that will construct most popular packets like iBeacon, Eddystone or Estimote proprietary
eddystoneUrl
ble.build.eddystoneUrl(url, measuredPower = -20)
Description: Builds EddystoneURL packet
Arguments:
- url (string) - URL to be advertised
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 0m)
Invocation example:
ble.build.eddystoneUrl("https://estimote.com", -20)
Returns: object
eddystoneTlm
ble.build.eddystoneTlm()
Description: Builds single EddystoneTLM packet. Since it generates single packet you need to pass whole function to ble.advertise to make packet change over time.
Returns: object
eddystoneUid
ble.build.eddystoneUid(namespace, instance, measuredPower = -20)
Description: Builds EddystoneUID packet
Arguments:
- namespace (arraybuffer) - ArrayBuffer or hex string with namespace ID (10 bytes)
- instance (arraybuffer) - ArrayBuffer or hex string with instance ID (6 bytes)
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 0m)
Invocation example:
ble.build.eddystoneUid("123456789ABCDEF01234", "349012AEB2E3", -20)
Returns: object
iBeacon
ble.build.iBeacon(uuid, major, minor, measuredPower = -50)
Description: Builds iBeacon packet
Arguments:
- uuid (arraybuffer) - ArrayBuffer or hex string with UUID
- major (number, min: 1, max: 65535) - iBeacon major number from 1 to 65535
- minor (number, min: 1, max: 65535) - iBeacon minor number from 1 to 65535
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 1m)
Invocation example:
ble.build.iBeacon("123e4567-e89b-12d3-a456-426655440000", 1024, 512, -50)
Returns: object
altBeacon
ble.build.altBeacon(id, manufacturerId, measuredPower = -50, reserved = 0)
Description: Builds AltBeacon packet
Arguments:
- id (arraybuffer) - ArrayBuffer or hex string with beacon ID. At least 16 bytes long but no longer than 20 bytes
- manufacturerId (number, min: 1, max: 65535) - Manufacturer ID
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 1m)
- reserved (number, min: 0, max: 256, optional) - Reserved value
Invocation example:
ble.build.altBeacon("123e4567-e89b-12d3-a456-426655440000", 1024, -50, 0)
Returns: object
estimoteLocation
ble.build.estimoteLocation(measuredPower = -50)
Description: Builds Estimote Location packet
Arguments:
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 1m)
Invocation example:
ble.build.estimoteLocation(-50)
Returns: object
estimoteLocationTrigger
ble.build.estimoteLocationTrigger(measuredPower = -50)
Description: Builds Estimote Location trigger packet. It should be advertised with 100ms and -4 dBm txPower.
Arguments:
- measuredPower (number, unit: dBm, min: -127, max: 127, optional) - Measured power in dBm (measured at 1m)
Invocation example:
ble.build.estimoteLocationTrigger(-50)
Returns: object
estimoteTelemetry
ble.build.estimoteTelemetry()
Description: Builds single Estimote Telemetry packet. Since it generates single packet you need to pass whole function to ble.advertise(...)
to make packet change over time.
Invocation example:
ble.advertise(ble.build.estimoteTelemetry)
Returns: object
Input/Output
led
Variant 1:
io.led(id, state)
Description: Sets LED on or off
Arguments:
- id (number) - RGB segment number
- io.Led.LTE = 100 → LTE side LED
- io.Led.GPS = 101 → GPS side LED
- io.Led.BLE = 102 → BLE side LED
- state (bool) - Set true to turn on LED
Invocation example:
io.led(1, true)
Variant 2:
io.led(state)
Description: Turn on or off all LEDs (on the ring)
Arguments:
- state (bool) - Set true to turn on all LEDs (on the ring)
Invocation example:
io.led(true)
setLedColor
Variant 1:
io.setLedColor(id, color)
Description: Sets LED RGB color
Arguments:
- id (number) - RGB segment number (from 0 to 2)
- io.Led.LTE = 100 → LTE side LED
- io.Led.GPS = 101 → GPS side LED
- io.Led.BLE = 102 → BLE side LED
- color (array) - Array containing three numbers for red, green and blue colors from 0.0 to 1.0 (max ilumination). Predefined set of colors can be found in enum
io.Color
- io.Color.RED = [1, 0, 0] → Red color
- io.Color.GREEN = [0, 1, 0] → Green color
- io.Color.BLUE = [0, 0, 1] → Blue color
- io.Color.YELLOW = [1, 1, 0] → Yellow color
- io.Color.WHITE = [1, 1, 1] → White color
- io.Color.CYAN = [0, 1, 1] → Cyan color
- io.Color.MAGENTA = [1, 0, 1] → Magenta color
- io.Color.ORANGE = [0.99, 0.41, 0.002] → Orange color
Invocation example:
io.setLedColor(1, [0.5, 0.0, 1.0])
Variant 2:
io.setLedColor(id, htmlColor)
Description: Sets LED RGB color
Arguments:
- id (number) - RGB segment number (from 0 to 2)
- io.Led.LTE = 100 → LTE side LED
- io.Led.GPS = 101 → GPS side LED
- io.Led.BLE = 102 → BLE side LED
- htmlColor (string) - HTML style color description.
Invocation example:
io.setLedColor(1, "#FF77EB")
Variant 3:
io.setLedColor(color)
Description: Sets RGB color for all LEDs (on the ring)
Arguments:
- color (array) - Array containing three numbers for red, green and blue colors from 0.0 to 1.0 (max ilumination). Predefined set of colors can be found in enum
io.Color
Invocation example:
io.setLedColor([0.5, 0.0, 1.0])
Variant 4:
io.setLedColor(htmlColor)
Description: Sets RGB color for all LEDs (on the ring)
Arguments:
- htmlColor (string) - HTML style color description.
Invocation example:
io.setLedColor("#FF77EB")
setLedBrightness
Variant 1:
io.setLedBrightness(id, brightness)
Description: Sets LED brightness
Arguments:
- id (number) - RGB segment number (from 0 to 2)
- io.Led.LTE = 100 → LTE side LED
- io.Led.GPS = 101 → GPS side LED
- io.Led.BLE = 102 → BLE side LED
- brightness (number) - Number from 0 to 1.0 with LED brightness.
Invocation example:
io.setLedBrightness(1, 0.5)
Variant 2:
io.setLedBrightness(brightness)
Description: Sets brightness for all LEDs (on the ring)
Arguments:
- brightness (number) - Number from 0 to 1.0 with LED brightness.
Invocation example:
io.setLedBrightness(0.5)
press
Variant 1:
io.press(callback, pressType = 0)
Description: Listen for button press. You can assign different callback to each press type (long, short, very long)
Arguments:
-
callback (function) - Function called when button is pressed
Function signature:
() => ...
-
pressType (number, optional) - Button press type
- io.PressType.SHORT = 0 → Short press, lest than 1 second
- io.PressType.LONG = 1 → Long press, more than 3 second
- io.PressType.VERY_LONG = 2 → Very long press, more than 5s
Invocation example:
io.press(() => print("short press"), io.PressType.SHORT)
io.press(() => print("long press"), io.PressType.LONG)
Variant 2:
io.press(buttonId, callback, pressType = 0)
Description: Listen for button press. You can assign different callback to each press type (long, short, very long)
Arguments:
- buttonId (number) - Button type
- io.Button.MAIN = 0 → Main button
- io.Button.SIDE = 1 → Side button (when available)
-
callback (function) - Function called when button is pressed
Function signature:
() => ...
- pressType (number, optional) - Button press type
- io.PressType.SHORT = 0 → Short press, lest than 1 second
- io.PressType.LONG = 1 → Long press, more than 3 second
- io.PressType.VERY_LONG = 2 → Very long press, more than 5s
Invocation example:
io.press(io.Button.MAIN, () => print("short press"), io.PressType.SHORT)
io.press(io.Button.MAIN, () => print("long press"), io.PressType.LONG)
Accelerometer
Accelerometer control functions.
getAccel
sensors.imu.getAccel()
Description: Returns acceleration vector in G
Returns: object
Object fields:
- x (number, unit: g) - Accelertion value in X axis
- y (number, unit: g) - Accelertion value in Y axis
- z (number, unit: g) - Accelertion value in Z axis
Example:
{
"x": 0.514,
"y": 0.00134,
"z": 0.9878
}
getGyro
sensors.imu.getGyro()
Description: Returns rotation rate vector in deg/s (AI Beacon only)
Returns: object
Object fields:
- x (number, unit: g) - Rotation rate in X axis
- y (number, unit: g) - Rotation rate in Y axis
- z (number, unit: g) - Rotation rate in Z axis
Example:
{
"x": 0.514,
"y": 0.00134,
"z": 0.9878
}
setSens
sensors.imu.setSens(level)
Description: Sets sensitivity
Arguments:
- level (number) - Sets accelerometer sensitivity level
- sensors.imu.Level.LOWEST = 0 → Lowest level
- sensors.imu.Level.LOW = 1 → Low level
- sensors.imu.Level.MEDIUM = 2 → Medium level
- sensors.imu.Level.HIGH = 3 → High level
- sensors.imu.Level.HIGHEST = 4 → Highest level
Invocation example:
sensors.imu.setSens(sensors.imu.Level.MEDIUM)
Returns: undefined
setResp
sensors.imu.setResp(level)
Description: Sets sensitivity
Arguments:
- level (number) - Sets accelerometer responsivness level
- sensors.imu.Level.LOWEST = 0 → Lowest level
- sensors.imu.Level.LOW = 1 → Low level
- sensors.imu.Level.MEDIUM = 2 → Medium level
- sensors.imu.Level.HIGH = 3 → High level
- sensors.imu.Level.HIGHEST = 4 → Highest level
Invocation example:
sensors.imu.setResp(sensors.imu.Level.MEDIUM)
Returns: undefined
setRange
sensors.imu.setRange(range)
Description: Sets sensitivity
Arguments:
- range (number) - Sets accelerometer range
- sensors.imu.Range.RANGE_2G = 0 → ± 2g
- sensors.imu.Range.RANGE_4G = 1 → ± 4g
- sensors.imu.Range.RANGE_8G = 2 → ± 8g
- sensors.imu.Range.RANGE_16G = 3 → ± 16g
Invocation example:
sensors.imu.setRange(sensors.imu.Range.RANGE_2G)
Returns: undefined
onMotion
Variant 1:
sensors.imu.onMotion(callback)
Description: Invokes callback function when device is in motion
Arguments:
-
callback (function) - Callback function that will be called when motion is detected
Function signature:
(motion) => ...
- motion (bool) - True if device is in motion
Invocation example:
sensors.imu.onMotion((motion) => {
print(`Is moving: ${motion}`)
})
Variant 2:
sensors.imu.onMotion(null)
Description: Unregisters motion callback
Returns: undefined
Battery
Battery diagnostic functions.
getVoltage
sensors.battery.getVoltage()
Description: Returns battery volatage in V
Returns: number
isExtPower
sensors.battery.isExtPower()
Description: Returns true
if external power is available.
Returns: bool
isCharging
sensors.battery.isCharging()
Description: Returns true
if battery is charging. Note that isExtPower
may be true, but isCharging
may return false because batter is full.
Returns: bool
getPerc
sensors.battery.getPerc()
Description: Energy left in battery in %
Returns: number
setPowerListener
Variant 1:
sensors.battery.setPowerListener(callback)
Description: Register power state listener. It will be called when device power state has changed (external power connected/disconnected, battery charging started, stopped). Registering new handler will overwrite previous.
Arguments:
-
callback (function) -
Function signature:
(externalPower, charging) => ...
- externalPower (bool) - Is
true
if external power was applied - charging (bool) - Is
true
if battery is charging
- externalPower (bool) - Is
Variant 2:
sensors.battery.setPowerListener(null)
Description: Clears power listener
Returns: undefined
Temperature
Temperature reading functions.
get
sensors.temp.get()
Description: Temperature in C
Returns: number
setFastMode
sensors.temp.setFastMode(enabled)
Description: Enables fast measurement mode
Arguments:
- enabled (bool) - If true then temperature measurement will be takes in shorter intervals
Invocation example:
sensors.temp.setFastMode(true)
Returns: undefined
Cloud communication
Cloud communications functions.
enqueue
cloud.enqueue(type, message, options = enqueue_default_options())
Description: Enqueues a message to be sent to cloud whenever a next synchronisation event occurs. The message should be delivered eventually (if is set to be non-volatile), but can be delayed due to a long synchronisation period being set, bad cellular reception, or a critically low battery. Max serialized message size is about 8kB (this value may change in the future). Function returns size of enqued data in bytes.
Device ID and timestamp are automatically included in the event so there is not need to include them inside event message.
This function may block, so avoid using is frequently because it may slow down execution of other parts of your code.
Arguments:
- type (string) - Event type name
- message (pure_object) - Serializable user data object - any JSON compatible object is valid. Promises, functions, handles (eg. from timers) inside object will throw an exception.
-
options (object, optional) - Individual event options. Volatile means that message can be removed if there is not enough storage space.
Object fields:
- volatile (bool, optional) - If event is volatile it means it can be deleted when there is not enough space in storage (to make space for new events).
Example:
{ "volatile": false }
Invocation example:
cloud.enqueue("status", {battery: 0.98, temp: 23.5}, {volatile: true})
Returns: number
Errors thrown:
- ESR0203 Not serializable
- ESR0204 Message too big
- ESR0201 Storage error
- ESR0202 No storage space
- ESR0104 Execution interrupted
onReceive
Variant 1:
cloud.onReceive(msgHandler)
Description: Receives message from cloud. It overwrites previous callback. Setting null
will disable callback. Receiving messages happens during synchornization with Cloud.
Arguments:
-
msgHandler (function) - Function that will receive and process messages from Cloud
Function signature:
(msg) => ...
- msg (object) - Envelope with a message received from Cloud
Object fields:
- type (string) - Message type
- ts (number, unit: ms) - Enqueue timestamp
- payload (object) - Message payload (JSON-like object)
Example:
{ "type": "start_scan", "ts": 12345465456534, "payload": { "timeout": 1000 } }
Variant 2:
cloud.onReceive(null)
Description: Clears Cloud message callback
Returns: undefined
Data synchronisation
Synchronisation functions
setHandler
Variant 1:
sync.setHandler(callback)
Description: Register synchronisation start handler. Registering new handler will overwrite previous.
If you enqueue your event messages here they will be delivered in this synchronisation cycle.
Arguments:
-
callback (function) -
Function signature:
() => ...
Variant 2:
sync.setHandler(null)
Description: Clears synchronisation start handler.
Returns: undefined
now
sync.now()
Description: Triggers synchronisation with cloud immediatly. If invoked during synchronisation it will do nothing. This function is asynchronous and will return immediatly.
Try to avoid using sync.now()
just after cloud.enqueue()
and calling them in short intervals. This will keep modem on and consume significat amount of power.
Returns: bool
setSyncPeriod
sync.setSyncPeriod(syncPeriod)
Description: Sets maximum synchronisation period in seconds. It reschedules pending synchronization automatically when called. Synchronisation may happen earlier due to calling sync.now()
or other internal events (like low battery or running out of storage memory).
Arguments:
- syncPeriod (interval, unit: s, min: 120, max: 7776000) - Synchronization period in seconds
Storage
Local persistent storage functions.
save
storage.save(id, data)
Description: Stores message in local storage under provided numeric key. Max serialized message size is about 12kB (this value may change in the future). Function returns size of saved data in bytes.
Arguments:
- id (number) - Record ID/key
- data (any) - Serializable user data object - any JSON compatible object is valid. Promises, functions, handles (eg. from timers) inside object will throw an exception.
Returns: number
Errors thrown:
- ESR0203 Not serializable
- ESR0204 Message too big
- ESR0201 Storage error
- ESR0202 No storage space
read
storage.read(id)
Description: Reads message from local storage from given numeric key. Returns undefined
when record does not exist.
Arguments:
- id (number) - Record ID/key
Returns: object
remove
storage.remove(id)
Description: Removes message from local storage from given numeric key. Returns true
if message was found and deleted.
Since: 0.0.5
Arguments:
- id (number) - Record ID/key
Returns: bool
readAll
storage.readAll(handle)
Description: Reads all messages from storage using provided function.
Arguments:
-
handle (function) -
Function signature:
(id, data) => ...
- id (number) - Record id/key
- data (object) - JSON like object with data
Returns: undefined
clear
storage.clear()
Description: Clears all records from local storage
Returns: undefined
getStats
storage.getStats()
Description: Get storage statistics.
Since: 0.1.0
Returns: object
Object fields:
- total (number, unit: byte) - Total number of storage
- used (number, unit: byte) - Used storage in bytes.
- free (number, unit: byte) - Free storage space
Example:
{
"total": 96000,
"used": 5345,
"free": 68000
}
Location
Location functions using global sattelite navigation systems (GNSS)
distance
location.distance(from, to)
Description: Calculates distance between two geographical locations
Arguments:
- from (object) - Source location
- to (object) - Destination location
Returns: number
startUpdates
location.startUpdates(callback = {0,0}, options = null)
Description: Invoke callback when GNNS position changes. You can register only one callback (calling it again will override callback).
Function will report position updates (if position can be obtained) for at least 15min unless different value is specified in timeout parameter in options (0 timeout means infinite). Updates will be returned after minimum minInterval
seconds and when device moved more than minDistance meters from last position. minDistance is 0 by default and this value means it is not used.
If location fails returned promise is rejected. Promise will be resolved with last known position (or undefined) either when location.stop()
wil be called or on timeout.
Arguments:
-
callback (function, optional) - Callback function that will be called when position has changed. This callback will be called only if position was succesfully obtained.
Function signature:
(position) => ...
- position (object) - Geographical position.
Object fields:
- lat (number, unit: deg) - Lattitude
- long (number, unit: deg) - Longitude
- speed (number, unit: km/h) - Estimated speed
- alt (number, unit: m) - Altitude
- head (number, unit: deg) - Heading
- prec (number) - Horizontal precision (HDOP)
- diff (number, unit: m) - Difference from last returned position
- ts (number, unit: ms) - UTC timestamp (sice 1 Jan 1970)
- sat (number) - Number of sattelites
Example:
{ "lat": 50.014, "long": 19.934, "speed": 36, "alt": 176, "head": 124, "prec": 2.4, "diff": 22.5, "ts": 1528289744000, "sat": 124 }
-
options (object, optional) - Location options like minimal reporting interval (in s), minimal distance (in m) or overall location timeout (in s). Returned promise will be rejected if
minInterval
is greater thantimeout
.Object fields:
- timeout (interval, unit: s, optional) - Maximum time GNSS is switched on. 0 for unlimited.
- minInterval (interval, unit: s, optional) - Minimal interval between GNSS position callback calls
- minDistance (number, unit: m, optional) - Minimal reporting distance
Example:
{ "timeout": 180, "minInterval": 0, "minDistance": 0.5 }
Invocation example:
location.startUpdates((position) => {
print(`lattitude=${position.lat} longitude=${position.long}`)
}, {minInterval: 10, minDistance: 10.2, timeout: 120})
Returns: promise
mock
Variant 1:
location.mock(position)
Description: Mocks current GNSS position. Use for testing only. You need to start location tracking as ususal using startUpdates
, but if you call this method mocked position will be returned in callback as if it got real fix. Mocked location objects have field called mock
set to 1
. Mocking does not affect Last Known Location. Mock works only after startUpdates
has been called.
Arguments:
- position (object) - Mocked device position.
Variant 2:
location.mock(null)
Description: Stops position mocking
Returns: undefined
stop
location.stop(resolvePromise = true)
Description: Stops location tracking
Arguments:
- resolvePromise (bool, optional) - If
true
then thestartUpdates
promise will be resolved
Invocation example:
location.stop(true)
Returns: undefined
UWB ranging
Distance ranging using Ultra Wide Band (AI Beacon only)
start
uwb.start(role, options = null, callback = {0,0})
Description: Provides distances from other UWB devices
Arguments:
- role (number) - Sets device role
- uwb.Role.RESPONDER = 0 → Responder
- uwb.Role.INITIATOR = 1 → Initiator
-
options (object, optional) - Ranging options
Object fields:
- timeout (interval, unit: s, optional) - Maximum time UWB is switched on. 0 for unlimited.
- mode (number, optional) - UWB mode: high performance or longer range
- panId (number, optional) - Network ID, must match between responders and initiators
- minDistance (number, unit: m, optional) - Minimal reporting distance
- maxDistance (number, unit: m, optional) - Maximum reporting distance
Example:
{ "timeout": 0, "mode": 1, "panId": 43981, "minDistance": 0.5, "maxDistance": 10 }
-
callback (function, optional) - Callback function that will be called when distance has been measured. This callback will be called only if position was succesfully obtained.
Function signature:
(distance) => ...
- distance (object) - Device distance
Object fields:
- id (string) - Other device id
- dist (number, unit: m) - Distance
- lqi (number) - Measurement quality
Example:
{ "id": "ab3456", "dist": 6.934, "lqi": 0.3 }
Invocation example:
uwb.start(io.Role.RESPONDER, {minDistance: 1.2, maxDistance: 10.2, timeout: 120, panId: 41}, (distance) => {
print(`id=${distance.id} distance=${distance.dist} lqi=${distance.lqi}`)
})
Returns: promise
Errors thrown:
- ESR1701 Bad args for role
- ESR1703 Invalid options
stop
uwb.stop(resolvePromise = true)
Description: Stops UWB ranging
Arguments:
- resolvePromise (bool, optional) - If
true
then thestart
promise will be resolved
Invocation example:
uwb.stop(true)
Returns: undefined
System
System information and global settings functions
getPublicId
sys.getPublicId()
Description: Gets device public identifier as hex string.
Note: Device ID is already included in event that is sent using cloud.enqueue(...)
Returns: string
getUptime
sys.getUptime()
Description: Gets system uptime in seconds since last reset.
Returns: number
isTimeSynced
sys.isTimeSynced()
Description: Check if time has been synchronized. If not then any date operation will print invalid timer error on console. Same can be achieved by new Date().getFullYear() > 2018
Returns: bool
getFirmware
sys.getFirmware()
Description: Gets firmware version as 3 element array [major, minor, patch]
Since: 0.0.4
Returns: object
Returned value example:
[0,0,5]
getHardware
sys.getHardware()
Description: Gets hardware revision as string
Since: 0.0.4
Returns: string
LTE
LTE Radio control and diagnostic
getOperators
modem.getOperators()
Description: Gets list of available operators. This may take we minutes and use significant amount of power.
Note: Calling this function again before promise is resolved will cause previous promise to be rejected.
Invocation example:
modem.getOperators()
.then((opers) => print("Operators:" + JSON.stringify(opers)))
.catch((e) => print("Error: " + e))
Returns: promise
Returned value example:
[{name: "T-Mobile", type: "gsm", status: "curr"},
{name: "Orange", type: "gsm", status: "avail"},
{name:"Verizon", type: "gsm", status: "avail"}]
getStatus
modem.getStatus()
Description: Gets current network status like signal strength, operator, cell ID.
Note: Calling this function again before promise is resolved will cause previous promise to be rejected.
Invocation example:
modem.getStatus()
.then((status) => print("Status:" + JSON.stringify(status)))
.catch((e) => print("Error: " + e))
Returns: promise
Object fields:
- name (string) - Operator name
- signal (number) - Signal strength
- rssi (number, optional) - RSSI
- rsrp (number, optional) - RSRP
- rsrq (number, optional) - RSRQ
- mcc (number) - Mobile Country Code (MCC)
- mnc (number) - Mobile Network Code (MNC)
- lac (number) - Location Area Code (LAC)
- cell (number) - Cell ID (CID)
- tech (string) - Technology used (GSM, LTE Cat. M1., NB IoT)
- band (string) - Used band symbol
Example:
{
"name": "T-Mobile",
"signal": 22,
"rssi": -92,
"rsrp": -17,
"rsrq": -17,
"mcc": 260,
"mnc": 2,
"lac": 1111,
"cell": 1111,
"tech": "Cat-M1",
"band": "LS"
}
getCells
modem.getCells()
Description: Gets information about cells in neigboughood. Similar to getOperators but focuses more on signal parameters.
Invocation example:
modem.getCells()
.then((cells) => print("Cells:" + JSON.stringify(cells)))
.catch((e) => print("Error: " + e))
Returns: promise
Object fields:
- name (string) - Operator name
- signal (number) - Signal strength
- rssi (number, optional) - RSSI
- rsrp (number, optional) - RSRP
- rsrq (number, optional) - RSRQ
- mcc (number) - Mobile Country Code (MCC)
- mnc (number) - Mobile Network Code (MNC)
- lac (number) - Location Area Code (LAC)
- cell (number) - Cell ID (CID)
- tech (string) - Technology used (GSM, LTE Cat. M1., NB IoT)
- band (string) - Used band symbol
Example:
{
"name": "T-Mobile",
"signal": 22,
"rssi": -92,
"rsrp": -17,
"rsrq": -17,
"mcc": 260,
"mnc": 2,
"lac": 1111,
"cell": 1111,
"tech": "Cat-M1",
"band": "LS"
}
getInfo
modem.getInfo()
Description: Gets device information like IMEI, IMSI, ICCID.
Note: Calling this function again before promise is resolved will cause previous promise to be rejected.
Invocation example:
modem.getInfo()
.then((info) => print("Info:" + JSON.stringify(info)))
.catch((e) => print("Error: " + e))
Returns: promise
Object fields:
- iccid (string) - Integrated Circuit Card Identifier (ICCID) - unchangeable SIM card number (usually printed on it)
- imei (string) - International Mobile Equipment Identity (IMEI)
- imsi (string) - International Mobile Subscriber Identity (IMSI)
Example:
{
"iccid": "00000000000000000000000",
"imei": "000000000000000000",
"imsi": "000000000000000000"
}
setAirplaneMode
modem.setAirplaneMode(state)
Description: Sets airplace mode on or off. This will make all LTE related functions to reject their promises.
Arguments:
- state (bool) - Turns the Airplane Mode on or off. When turned on, the LTE module is shut down, so the heartbeat reports will not be sent and any attempts to sync with Estimote Cloud will be queued until the Airplane Mode is turned back off.
Invocation example:
modem.setAirplaneMode(true)
Returns: undefined
Application
Application execution control and error handling functions
setErrorHandler
Variant 1:
app.setErrorHandler(errorHandler)
Description: Registers global error handler.
Arguments:
-
errorHandler (function) - Handles errors from callbacks and system
Function signature:
(type, error) => ...
- type (number) - Error type
- error (object) - Error object
Invocation example:
app.setErrorHandler((type, msg) => print(type + ": " + msg)))
Variant 2:
app.setErrorHandler(null)
Description: Unregisters global error handler.
remove
app.remove()
Description: Stops and deletes application. New application can be sent though Bluetooth or deployed by Cloud.
stop
app.stop()
Description: Stops application
restart
app.restart()
Description: Restarts application
getUptime
app.getUptime()
Description: Gets application uptime is ms (since installation, system reboot or comanded restart)
Since: 0.0.5
Returns: number
getMemStats
app.getMemStats()
Description: Get memory statistics.
Since: 0.1.0
Returns: object
Object fields:
- total (number, unit: byte) - Total number of heap memory
- used (number, unit: byte) - Used heap memory bytes.
- free (number, unit: byte) - Free heap memory bytes.
- peak (number, unit: byte) - Peak used heap memory bytes since app started.
Example:
{
"total": 78000,
"used": 5345,
"free": 68000,
"peak": 5345
}