LTE Beacon: Cloud code & APIs

LTE Beacon sends its events to Estimote Cloud, where you can:

  • process it immediately, by writing some cloud code that runs directly in Estimote Cloud
  • retrieve it later via Estimote Cloud API

What’s ahead (aka Table of Contents)

Cloud code

Each IoT App is not just the code that runs on the LTE Beacon, but also code that runs in Estimote Cloud, where you can handle the events coming from the LTE Beacon. We call the latter cloud code, and you’ll commonly use it to call other APIs in response to the LTE Beacon events.

Here’s an example:

const request = require('request-promise');
module.exports = async function (event) {
    if (event.type === 'assets-update') {
        const assets = event.payload.assets;
        await request.post(
            'http://my.own.api/assets-update', {json: true, body: {assets}});
    }
}

Anatomy of the cloud code

Your cloud code should export a function with one argument—the event to handle. It looks like this:

{type: "assets-update",
 payload: {assets: ["..."]},
 enqueuedAt: "2018-10-30T13:27:23.170Z",
 identifier: "5e7e309e594c26a4d0694a90698c7534"}

… which corresponds to the following event queued on the LTE Beacon:

cloud.enqueue('assets-update', {assets: ['...']);

Your function is expected to either:

  • be an async function, for example:

      module.exports = async function (event) {
      await twilio.messages.create({ /* ... */});
  }

  • return a Promise, for example:

      module.exports = function (event) {
      return twilio.messages.create({ /* ... */});
  }

Execution limits

Your functions must finish within 30 seconds, and has very limited amount of memory and processing power.

Node.js environment & available modules

Your function will run in a sandboxed Node.js 10.x environment, with access to the following modules only:

(You still need to require them before use.)

Note: The versions of these packages are guaranteed to be at least as stated above, but we might update them as per the ^ npm specifier—that is, patch and minor version updates, but not the major version.

LTE Device Events API

You can access the history of events from your LTE Beacons via Estimote Cloud API.

The appropriate endpoint is documented here:
http://cloud.estimote.com/docs/#api-LTE-getDeviceEvents

Experimental: events batch processing

LTE Beacons send data to Cloud in batches to minimize time and power consumed by modem. However events are
processed one-by-one by Cloud Code. This is not very efficient since each invocation may require one HTTP request to send data further.
To mitigate this problem a batch mode was introduced where events are delivered in groups.
Batch processing can be enabled by adding this comment to Cloud Code (so existing apps would not be affacted):

//# batch: true

Consider an example Cloud Code:

//# batch: true
module.exports = async (data) => {
  console.log("Got data: " + JSON.stringify(data));
}

When batching is off exported function is invoked for each event:

Got data: {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:27:19.145Z","payload":{"app":"C","cnt":7}}
Got data: {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:27:19.146Z","payload":{"app":"C","cnt":8}}
Got data: {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:27:19.143Z","payload":{"app":"C","cnt":5}}
Got data: {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:27:19.144Z","payload":{"app":"C","cnt":6}}
Got data: {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:27:19.148Z","payload":{"app":"C","cnt":9}}

When batching is on, events are delivered in a single call in a form of an array:

Got data: [
    {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:28:44.391Z","payload":{"app":"C","cnt":10}},
    {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:28:44.392Z","payload":{"app":"C","cnt":11}},
    {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:28:44.393Z","payload":{"app":"C","cnt":12}},
    {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:28:44.395Z","payload":{"app":"C","cnt":13}},
    {"identifier":"--hidden--","type":"appC","enqueuedAt":"2020-12-10T09:28:44.396Z","payload":{"app":"C","cnt":14}}
 ]

There is no guarantee how many events will be in one batch or that all events from device will be delivered in one invocation.

Note: This is an experimental feature so it is still under testing and development, so some of the details might change in the future. Use with care.