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.
For the code to perform this role, you will need to enter your Electric Imp account credentials in lines 12 and 13. These are used to retrieve an API access token, which is then used to authorize data retrievals (through login() and getNewAccessToken()). The access token in short-lived; it is initially accompanied by a refresh token which 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 refreshAccessToken(). The request is made asynchronously; refreshedAccessToken() 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.
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.
Finally, a small stub is used to drive the device. Though all the work required by this application is performed by the agent, we need a device to ensure the agent stays operational. The impCloud eventually shuts down agents paired with devices that have not connected for a period of 31 days. Here the device does little but sleep, but its occasional wakings ensure that the agent is maintained.