LTE Beacon: Micro-app API reference

Micro-apps are written in JavaScript, although only a subset of the full specification is supported. If you’re not sure if a certain language feature is supported or not, you can:

  1. Just try it! If it compiles succesfully in the Estimote Web IDE, you’re good.

  2. Check out this test suite of the JavaScript engine we use:

    https://github.com/jerryscript-project/jerryscript/tree/master/tests/jerry

    If the language feature you’re looking for is there, and wasn’t added only very recently, the LTE Beacon probably supports it.

Some commonly used, modern JavaScript features that we’ll point out right away:

  • supported: arrow functions
  • not supported: const and let, destructuring, Object.assign

Other than that, here’s a list of LTE-Beacon–specific functions and APIs:

Global functions

print

print(text)

Description: Prints message on debug console.

Arguments:

  • text (string) - Text that will be displayed on console.

toHex

toHex(array)

Description: Converts arraybuffer/array to hex string

Arguments:

  • array (object) - Text that will be displayed on console.

Returns: object

Timer functions

Timer functions that allow to schedule tasks asynchronously

single

 timers.single(interval, callback)

Description: Start single shot timer

Arguments:

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

repeat

 timers.repeat(interval, callback)

Description: Start repeated timer.

Arguments:

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

at

 timers.at(timestamp, callback)

Description: Invoke timer at specified UTC time.

Arguments:

  • timestamp (object) - 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

 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.
    Function signature: () => ...
 ble.advertise(data)

Description: This variant will advertise statically defined packet.

Arguments:

  • data (object) - Packet that will be advertised

Returns: handle object

Handler object methods:

  • handler.stop() - Stops advertiser

  • handler.interval(interval) - Sets new advertising interval

    • interval (number, ms)- Interval in milliseconds
  • handler.power(interval) - Sets new advertising power (in dBm)

    • interval (number, dBm)- Power in dBm

startScan

 ble.startScan(callback, duration = 0, stopCallback = null)

Description: Start scanning for BLE packets

Arguments:

  • callback (function) - Callback function that will be called when new packet is detected
    Function signature: (scanRecord) => ...
    • scanRecord (object) - Raw BLE advertising packet.
  • duration (number, unit: ms) - Scan duration. 0 if there is no time limit.
  • stopCallback (function) - Callback function that will be called when scan stops
    Function signature: () => ...

Invocation example:

ble.startScan((scanRecord) => {
var packet = ble.parse(scanRecord)
if(packet) {
print(JSON.stringify(packet))
}
}, 10000, () => print("Scan is done"))

parse

 ble.parse(scanRecord)

Description: Parses scanned BLE advertisment and extracts data. It can recognize most common packets like iBeacon or Eddystone

Arguments:

  • scanRecord (object) - Raw BLE packet scanned provided by startScan callback

Returns: object

stopScan

 ble.stopScan(invokeStopCallback = true)

Description: Stop BLE scanning

Arguments:

  • invokeStopCallback (bool) - If true then stop callback will be called

Invocation example:

ble.stopScan(true)

Creating BLE packets

Builders that will construct most popular packets like iBeacon or Eddystone

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) - Measured power in dBm (measured at 0m)

Returns: object

Invocation example:

ble.build.eddystoneUrl("https://estimote.com", -20)

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) - Measured power in dBm (measured at 0m)

Returns: object

Invocation example:

ble.build.eddystoneUid("123456789ABCDEF01234", "349012AEB2E3", -20)

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) - Measured power in dBm (measured at 1m)

Returns: object

Invocation example:

ble.build.iBeacon("123e4567-e89b-12d3-a456-426655440000", 1024, 512, -50)

estimoteLocation

 ble.build.estimoteLocation(measuredPower = -50)

Description: Builds Estimote Location packet

Arguments:

  • measuredPower (number, unit: dBm, min: -127, max: 127) - Measured power in dBm (measured at 1m)

Returns: object

Invocation example:

ble.build.estimoteLocation(-50)

Input/Output

set

 io.set(pin, value)

Description: Sets GPIO pin output

Arguments:

  • pin (number) - GPIO pin number
  • value (bool) - True if pin is set to high, false if to low

Invocation example:

io.set(1, true)

get

 io.get(pin)

Description: Get GPIO pin input

Arguments:

  • pin (number) - GPIO pin number

Returns: bool

Invocation example:

io.get(1)

led

 io.led(state)

Description: Sets LED on or off

Arguments:

  • state (bool) - Set true to turn on LED

Invocation example:

io.led(true)

setLedColor

 io.setLedColor(color)

Description: Sets LED RGB color

Arguments:

  • color (array) - Array containing three numbers for red, green and blue colors from 0.0 to 1.0 (max ilumination)

Invocation example:

io.setLedColor([0.5, 0.0, 1.0])

listen

 io.listen(pin, callback)

Description: Listen for GPIO state change

Arguments:

  • pin (number) -
  • callback (function) -
    Function signature: (state) => ...
    • state (bool) -

Invocation example:

io.listen(0, (value) => if(value) { myFunction() })

press

 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) - Button press type

    • io.PressType.SHORT = 0 - Short press, lest than 1 second
    • io.PressType.VERY_LONG = 2 - Very long press, more than 3s
    • io.PressType.LONG = 1 - Long press, more than 1 second

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 in G

Returns: object

onMotion

 sensors.accel.onMotion(callback, threshold = 2)

Description: Invokes callback function when acceleration in any axis is above given threshold

Arguments:

  • callback (function) - Callback function that will be called when motion is detected
    Function signature: (motion_vector) => ...
    • motion_vector (object) - Acceletation vector
  • threshold (number) - Acceleration threshold in G

Returns: undefined

Invocation example:

sensors.accel.onMotion((vector) => {
print(`Moved: ${vector.x}, ${vector.y}, ${vector.z}`)
}, 2)

Battery

Battery diagnostic functions.

getVoltage

 sensors.battery.getVoltage()

Description: Returns battery volatage in V

Returns: number

isExtPower

 sensors.battery.isExtPower()

Description: True if external power is available.

Returns: bool

isCharging

 sensors.battery.isCharging()

Description: True if battery is charging

Returns: bool

getPerc

 sensors.battery.getPerc()

Description: Energy left in battery in %

Returns: number

Temperature

Temperature reading functions.

get

 sensors.temp.get()

Description: Temperature in C

Returns: number

Cloud communication

Cloud communications functions.

enqueue

 cloud.enqueue(type, message)

Description: Enqueues event message to be sendt to cloud during synchronisation window.

Arguments:

  • type (string) - Event type name
  • message (pure_object) - Arbitrary user data object

Returns: undefined

Errors thrown:

  • JS serialization error
  • Storage system error
  • Message is too big
  • Not enough storage space

Invocation example:

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

onReceive

 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) - JSON message received from Cloud
 cloud.onReceive(null)

Description: Clears Cloud message callback

Returns: undefined

Data synchronisation

Synchronisation functions

setHandler

 sync.setHandler(callback)

Description: Register synchronisation handler. Registering new handler will overwrite previous.

Arguments:

  • callback (function) -
    Function signature: () => ...
 sync.setHandler(null)

Description: Register synchronisation handler. Registering new handler will overwrite previous.

Returns: undefined

now

 sync.now()

Description: Forces synchronisation

Returns: bool

setSyncPeriod

 sync.setSyncPeriod(syncPeriod)

Description: Sets synchronisation period in seconds

Arguments:

  • syncPeriod (number, unit: s, min: 120, max: 7776000) -

Storage

Local storage functions

save

 storage.save(id, data)

Description: Stores message in local storage under provided numeric key

Arguments:

  • id (number) - Record ID/key
  • data (object) - JSON object with user data

Returns: undefined

Errors thrown:

  • JS serialization error
  • Storage system error
  • Message is too big
  • Not enough storage space

    read

     storage.read(id)
    

Description: Reads message from local storage from given numeric key

Arguments:

  • id (number) - Record ID/key

Returns: object

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 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) - From location
  • to (object) - Destination location

Returns: number

startUpdates

 location.startUpdates(callback, options = location_default_options(), stopCallback = null)

Description: Invoke callback when GNNS position changes. You can register one callback. Calling it again will override callback. Function will report position updates for at least 15min unless different value is specified in timeout parameter in options (0 timeout means infinite).

Arguments:

  • callback (function) - Callback function that will be called when position has changed
    Function signature: (position) => ...
    • position (object) - Geographical position.
      Example:
      {ts: 1537333256000, long: 20.23444343, alt: 265, lat: 30.452345, head: 0, prec: 1.20, speed: 0 }
      
  • options (object) - Location options like minimal reporting interval (in s), minimal distance (in m) or overall location timeout (in s)
  • stopCallback (function) - Callback function that will be called when location tracking stops
    Function signature: () => ...

Invocation example:

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

stop

 location.stop(invokeStopCallback = true)

Description: Stops location tracking

Arguments:

  • invokeStopCallback (bool) - If true then stop callback will be called

Returns: undefined

Invocation example:

location.stop(true)

System

System information and global settings functions

getPublicId

 sys.getPublicId()

Description: Gets device public identifier as hex string

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.

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 network status like signal strength, operator, cell ID.

Returns: promise

Returned value example:

{name:"T-Mobile" signal:22,mcc:260,mnc:2,lac:1111,cell:11111,iccid:"00000000000000000000000",tech:"Cat-M1"}

setAirplaneMode

 lte.setAirplaneMode(state)

Description: Sets airplace mode on or off

Arguments:

  • state (bool) - Set true to turn on airplane mode

Returns: void

Invocation example:

lte.setAirplaneMode(true)

Application

Application execution control and error handling sfunctions

setErrorHandler

 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
 app.setErrorHandler(null)

Description: Unregisters global error handler.

stop

 app.stop()

Description: Stops and deletes application

restart

 app.restart()

Description: Restarts application