Monitor Your Development Devices’ Status

Access The impCentral API From Your Agents

The following code demonstrates how you can make use of the impCentral™ API within your agent code to interact with the Electric Imp impCloud™ code and device management infrastructure. Here, the impCentral API is accessed to retrieve details of all the development devices assigned to the account used to log into the API.

Accessing The API

Version 1.1.1 logs in to the impCentral API using an API login key, which you need to add to the code in the area marked. You can retrieve a login key using the following command-line statements. First, get an access token using your account credentials (replace YOUR_USERNAME and YOUR_PASSWORD with the appropriate strings):

curl -v -X POST 'https://api.electricimp.com/v5/auth' \
    -H 'Content-Type: application/json' \
    -d '{"id": "YOUR_USERNAME", "password": "YOUR_PASSWORD"}'

If you get an error, check the credentials you entered, otherwise you should receive a string like this:

{ "access_token":"AN_ACCESS_TOKEN",
  "expires_in":3600,
  "expires_at":"2018-02-14T13:58:24.299Z",
  "refresh_token":"A_REFRESH_TOKEN"}

Carefully copy the access token value string (shown above with the placeholder AN_ACCESS_TOKEN) and add it to the following command, making sure not to include the double-quote marks, and add your password:

curl -v -X POST 'https://api.electricimp.com/v5/accounts/me/login_keys' \
    -H 'Authorization: Bearer AN_ACCESS_TOKEN' -H 'X-Electricimp-Password: YOUR_PASSWORD' \
    -H 'Content-Type: application/vnd.api+json' -d '{"data": { "type": "login_key", "attributes" : {} }}'

If you get an error, check the password and access token you entered, otherwise you should receive a string like this:

{ "data": { "type": "login_key",
            "id": "YOUR_LOGIN_KEY",
            "attributes": { ... }}}

Copy the value of the provided ID (shown above with the placeholder YOUR_LOGIN_KEY) and enter it into the Agent code in line 17:

const LOGIN_KEY = "YOUR_LOGIN_KEY";

Using The API

The code uses the login key to retrieve an API access token, which is then used to authorize data retrievals (through login() and getNewAccessToken()). The access token in short-lived; the login token is subsequently used to retrieve fresh access tokens as required. When it updates its device records, the code first checks that the access token is valid (via isAccessTokenValid()); if it is not, a new one is requested automatically, using getNewAccessToken(). The request is made asynchronously; gotAccessToken() is called to process the response from the API.

Bulk data issued by the impCentral API is provided in pages, along with data to help your code retrieve the next page in sequence. Again, the code below performs this task for you. This takes place within getDeviceData() by calling getNextURL() which examines the set of link data returned by the API for the URL of the next page of data. isFirstPage() checks whether the page that has been retrieved is the first in the sequence (it may also be the last, of course). When there is no supplied URL for the next page, we know that we have retrieved the last page of data.

Serving Web Pages

The code also shows how the agent can be used to serve a simple web page. In this case, the page provides no user interactivity, but it is possible to provide that too, as this example demonstrates. However, the example code below does include the delivery of graphics (and, by extension, any other type of non-HTML file) embedded in the agent code as strings of hexadecimal characters.

The device data is processed to extract each device’s online status, and to assemble the HTML page that will be returned when a web browser connects to the agent’s URL: standard header and footer blocks in between which the code assembles a table with rows for each device.

Interactions with the browser are managed by an instance of Electric Imp’s Rocky library, which maintains an agent-served API. Rocky operates by assigning callback functions that are triggered where API endpoints that you define are accessed. Here, an HTTP GET request made to the agent URL’s root endpoint causes the HTML page to be sent, while calls to /images return the requested PNG images indicating device status (online or offline, and whether status has changed). The latter demonstrates Rocky’s use of regular expressions to ensure the callback is triggered by any call for a file in /images and how the registered callback is used to process the request to ensure the correct data is returned.

The web page returned includes a trigger to auto-reload the page at regular intervals; a timestamp shows when this last took place.

The Device’s Role