LTE Beacon: Micro-app API reference [0.0.15]

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 and const
  • 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.0.15. See API reference for other firmware versions.

Global functions

print

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

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.

setInterval

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.

clearTimeout

clearTimeout(handler)

Description: Stops timer. Alias for timerHandler.stop()

Arguments:

  • handler (pure_object) - Timer handler object returned by setTimeout

clearInterval

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, ms)- New interval in milliseconds. If ommited (or 0) previous interval will be used.

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, ms)- New interval in milliseconds. If ommited (or 0) previous interval will be used.

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.

Bluetooth Low Energy functions

Bluetooth Low Energy scanning and advertising functions

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, ms)- Interval in milliseconds

  • handler.power(interval) - Sets new advertising power (in dBm).

    • interval (number, dBm)- 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).

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 (like print) 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 by print.

    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:

    {
   "addr": "feab1214112c",
   "name": "MyDevice",
   "scanResponse": false,
   "flags": 2,
   "txPower": 4,
   "serviceData": {
        "fe9a": "fe124566783234534"
   },
   "manufData": "fe34567689",
   "rssi": -67,
   "serviceUUIDs": [
        "fe9a"
   ],
   "channel": 37,
   "connectable": true
}

  • 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

BLE device-to-device connectivity

Input/Output

led

Variant 1:

 io.led(id, state)

Description: Sets LED on or off

Arguments:

  • id (number) - RGB segment number
    • io.Led.LTE = 0 - LTE side LED
    • io.Led.GPS = 1 - GPS side LED
    • io.Led.BLE = 2 - 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

Warning: This is temporary API and it is subject to change.

Variant 1:

 io.setLedColor(id, color)

Description: Sets LED RGB color

Arguments:

  • id (number) - RGB segment number (from 0 to 2)
    • io.Led.LTE = 0 - LTE side LED
    • io.Led.GPS = 1 - GPS side LED
    • io.Led.BLE = 2 - 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 = 0 - LTE side LED
    • io.Led.GPS = 1 - GPS side LED
    • io.Led.BLE = 2 - 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 = 0 - LTE side LED
    • io.Led.GPS = 1 - GPS side LED
    • io.Led.BLE = 2 - 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(() => print("short press"), io.PressType.SHORT)
io.press(() => print("long press"), io.PressType.LONG)

Accelerometer

Accelerometer control functions.

get

 sensors.accel.get()

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:

{
     "y": 0.00134,
     "x": 0.514,
     "z": 0.9878
}

setSens

 sensors.accel.setSens(level)

Description: Sets sensitivity

Arguments:

  • level (number) - Sets accelerometer sensitivity level

Invocation example:

sensors.accel.setSens(io.accel.Level.MEDIUM)

Returns: undefined

setResp

 sensors.accel.setResp(level)

Description: Sets sensitivity

Arguments:

  • level (number) - Sets accelerometer responsivness level

Invocation example:

sensors.accel.setResp(io.accel.Level.MEDIUM)

Returns: undefined

onMotion

Variant 1:

 sensors.accel.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.accel.onMotion((motion) => {
print(`Is moving: ${motion}`)
})

Variant 2:

 sensors.accel.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

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 4kB (this value may change in the future).
Device ID and timestamp are automatically included in the event so there is not need to include them inside event message.

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.

Invocation example:

cloud.enqueue("status", {battery: 0.98, temp: 23.5}, {volatile: true})

Returns: undefined

Errors thrown:

  • Not serializable value
  • Message is too big
  • Storage system error
  • Not enough storage space

onReceive

Variant 1:

 cloud.onReceive(msgHandler)

Description: Receives message from cloud. It overwrites previous callback. Setting null will disable callback.

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 storage functions

save

 storage.save(id, data)

Description: Stores message in local storage under provided numeric key. Max serialized message size is about 4kB (this value may change in the future).

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: undefined

Errors thrown:

  • Not serializable value
  • Message is too big
  • Storage system error
  • Not enough 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

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 = location_default_options())

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:

    {
   "head": 124,
   "ts": 1528289744000,
   "prec": 2.4,
   "long": 19.934,
   "lat": 50.014,
   "diff": 22.5,
   "alt": 176,
   "speed": 36,
   "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 than timeout.

Invocation example:

location.startUpdates((position) => { print(`lattitude=${position.lat} longitude=${position.long}`)
}
}, {minInterval: 10, minDistance: 10.2, timeout: 120 })

Returns: promise

stop

 location.stop(resolvePromise = true)

Description: Stops location tracking

Arguments:

  • resolvePromise (bool, optional) - If true then the startUpdates promise will be resolved

Invocation example:

location.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

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

 lte.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:

lte.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

 lte.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:

lte.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
  • rsrp (number, optional) - RSRP
  • 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:

{
     "rsrp": -17,
     "name": "T-Mobile",
     "signal": 22,
     "mcc": 260,
     "lac": 1111,
     "cell": 1111,
     "band": "LS",
     "tech": "Cat-M1",
     "rssi": -92,
     "mnc": 2
}

getInfo

 lte.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:

lte.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:

{
     "imei": "000000000000000000",
     "iccid": "00000000000000000000000",
     "imsi": "000000000000000000"
}

setAirplaneMode

 lte.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:

lte.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, msg) => ...

    • type (number) - Error type
    • msg (string) - Error message

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

NFC

Near Field Communication control functions

onFieldChanged

Variant 1:

 nfc.onFieldChanged(callback)

Description: Invokes callback function when other device is in communication field

Arguments:

  • callback (function) - Callback function that will be called when other device is in communication field

    Function signature: (field) => ...

    • field (bool) - Is true if device is communication field

Invocation example:

nfc.onFieldChanged((field) => {
print(`Is field on: ${field}`)
})

Variant 2:

 nfc.onFieldChanged(null)

Description: Unregisters field callback

Returns: undefined

onWrite

Variant 1:

 nfc.onWrite(callback)

Description: Invokes callback function when NFC tag has been written. Tag becomes writable only when this callback is registered.

Arguments:

  • callback (function) - Callback function that will be called when other device writes NFC tag

    Function signature: (data) => ...

    • data (arraybuffer) - Raw NDEF data received from external device.

Invocation example:

nfc.onWrite((data) => {
print(`Received raw NDEF data`)
})

Variant 2:

 nfc.onWrite(null)

Description: Unregisters write callback. This makes tag read-only.

Returns: undefined

setMsg

Variant 1:

 nfc.setMsg(message)

Description: Sets NDEF message so it can be read from device as a tag.

Arguments:

  • message (object) - NDEF message as an array of separate NDEF records. Each record must have recordType field that defines what other fields must be set.

Invocation example:

nfc.setMsg([{recordType: nfc.RecordType.TEXT,text: "Estimtote Welcomes"},{recordType: nfc.RecordType.URI, uri: 'https://estimote.com'},{recordType: nfc.RecordType.EXTERNAL, type: "custom:type", data: "ab32fef4e5e6e712"}])

Variant 2:

 nfc.setMsg(null)

Description: Clears user defined NDEF message and sets back initial one

Invocation example:

nfc.setMsg(null)

Returns: undefined

Errors thrown:

  • Invalid format
  • Too big
  • Invalid record type
  • Missing field