Skip to main content

impCentral API Primer

This document provides a top-level introduction to impCentral’s concepts and resources. It is intended to help you understand impCentral’s information architecture as you use the impCentral API and its accompanying documentation, including the impCentral API Reference.

Products

Products encompass all of the different types of firmware — application code and factory software — that are required to develop an Electric Imp-enabled product, to put it into production and to make it successfully perform its role in the field.

A Product, of necessity, requires multiple programs: development code to run on development devices; ‘pre-factory’ code to test your factory flow in the lab before you go into production; factory firmware to run on your BlinkUp™ Fixtures and Devices Under Test (DUTs) on the assembly line; and application firmware to run on Production Devices in the field. All of these product-specific programs are organized under the Product, which will also encompass multiple versions of each of these programs — for example, as you maintain the current application firmware but also work on future releases in parallel.

Product Endpoints

  • Products are accessed via the impCentral API endpoint /products.
  • Specific Products are accessed via their unique ID: /products/{product_ID}.
  • Products are created, modified or deleted by selecting the appropriate HTTP verb when contacting these endpoints.

The Product Data Structure

The API represents a Product as an object which contains the following keys:

  • id — The Product’s unique system ID, set by the system.
  • type — The object’s type: "product".
  • attributes
    • name — The Product’s name, set by the user (1-80 characters).
    • description — The Product’s optional description, set by the user (0-255 characters).
    • created_at — When the Product was created, set by the system.
  • relationships
    • creator — The Account that created the Product, set by the system.
    • owner — The Account that currently manages the Product, initially set by the system.

For a full list of Product-related endpoints and actions, please see the impCentral API Reference.

Device Groups

Device Groups are arbitrary collections of devices. Devices are assigned to Device Groups, not to a Product. All of the devices within a given Device Group run the same code, which is deployed to the Device Group not to the devices per se.

A Product may be associated with any number of Device Groups according to the specific needs of the Product, and of your development and production workflows. Device Groups can be added to or removed from a Product as required over time — they need not be defined only at the outset. Device Groups cannot be removed if they contain devices, ie. they must be ‘empty’ before they can be deleted.

There are five types of Device Group:

  • Development — Used to develop and test application firmware.
  • Test Factory — Used to develop and test factory firmware.
  • Test Production — Gathers devices that have been tested and blessed during factory testing.
  • Factory — Organizes BlinkUp fixtures in your Connected Factory.
  • Production — Gathers Production Devices that have been tested and blessed in your Connected Factory.

Devices must be specifically assigned to a Device Group in order to be used. Assignment can be performed either manually or, in the case of DUTs, automatically. A device can be assigned to only one Device Group at a time. Devices can subsequently be moved from one Device Group to another, with one restriction: assigned devices can generally only be moved to Device Groups of the same Device Group type.

The only way a device can be re-assigned to a Device Group of a different type is if it itself changes its nature. For instance, if a Production Device (ie. a blessed DUT) is unblessed via the impCentral API’s factory controls, it becomes an unassigned device (its relationships.devicegroup property is null) and can therefore be subsequently assigned to, say, a Development Device Group. Devices in Factory and Test factory Device Groups can be unassigned and then assigned to Development Device Groups.

Device Group Endpoints

  • Device Groups are accessed via the API endpoint /devicegroups.
  • Specific Device Groups are accessed via their unique ID: /devicegroups/{device_group_ID}.
  • Device Groups are created, deleted or modified by selecting the appropriate HTTP verb when contacting these endpoints.
  • Examine a Device Group object’s relationships.product value to determine which Product it belongs:
{ "relationships: {
    "product": {
        "type": "product",
        "id": "01560db4-1ca2-5af3-de74-fb5cc7c2bf9e" }
    }
}

The Device Group Data Structure

The API represents a Device Group as an object which contains the following keys:

  • id — The Device Group’s unique ID, set by the system.
  • type — The object’s type: "production_devicegroup", "development_devicegroup", "factory_devicegroup", "pre_factoryfixture_devicegroup" or "pre_production_devicegroup".
  • attributes
    • name — The Device Group’s name, set by the user (1-80 characters).
    • description — The Device Group’s optional description, set by the user (0-255 characters).
    • created_at — When the Device Group was created, set by the system.
    • load_code_after_blessing — Do the Device Group’s devices receive their application firmware after blessing (true) or first end-user BlinkUp (false), set by the user. Only valid for Production Device Groups.
  • relationships
    • product — The Product object to which the Device Group belongs, set by the user.
    • production_target — The Device Group object representing the Production Device Group that newly blessed devices will be automatically added to, set by the user. Only valid for Factory Device Groups, for which it is mandatory.
    • current_deployment — The Deployment object containing the code currently assigned to the Device Group.
    • creator — The Account object that created the Device Group, set by the system.
    • owner — The Account object that currently manages the Device Group, initially set by the system.

For a full list of Device Group-related endpoints and actions, please see the impCentral API Reference.

Test Production And Test Factory Device Groups

These two group types are intended to be use for testing your factory process before you go into production. They are currently functionally identical to Production and Factory Device Groups, respectively. The impCentral web app uses these Device Groups under the hood to provide test blessing functionality.

Assigning Devices To A Device Group

When development devices and BlinkUp fixtures are added to an Electric Imp account using the Electric Imp mobile app they are initially unassigned. To assign a device to a suitable Device Group, send a POST request to the impCentral API endpoint /devicegroups/{devicegroup_id}/relationships/devices and pass in a Device identifier object (or an array of Device identifiers). This is a simple JSON entity which combines the device’s known ID and its object type (which is always "device"):

{ "type": "device",
  "id": "<device_id>" }

Note that the device ID is the internal device ID, retrieved from an entry in the array returned by the /devices endpoint (see below).

To re-assign a device to another Device Group, it is first necessary to unassign the device first. You can achieve this by sending a DELETE request to the /devicegroups/{devicegroup_id}/relationships/devices endpoint and passing in the Device identifier (or an array of Device identifiers), as above. When the API has confirmed the removal of the device(s) from the Device Group, you can assign the devices to the other Device Group.

Assigning Production Devices

Production Devices on the assembly line are automatically assigned to a pre-selected Production Device Group, called the Target Production Device Group, when they are blessed. This Target Production Device Group is specified in the relationships object of the Factory Device Group, to which the BlinkUp fixture which configured the Production Devices belongs. The production_target key is a required property of Test Factory and Factory Device Groups.

Unassigning Devices

A device can be removed from its Device Group by sending a DELETE request to the /devicegroups/{devicegroup_id}/relationships/devices endpoint and passing in the Device identifier (or an array of Device identifiers), as above. Devices removed this way are unassigned.

Devices

Devices are organized into five basic types:

  • Development
    • Configured using the Electric Imp mobile App
    • Can be assigned to any Development Device Group
    • Runs development application firmware
  • BlinkUp Fixture
    • Configured using the Electric Imp mobile App
    • Can be assigned to any Test Factory or Factory Device Group
    • Runs development or production factory firmware
  • Device Under Test (DUT)
    • Configured with a BlinkUp Fixture
    • Not assigned to a Device Group until they are blessed
  • Test Blessed Device
    • Configured using a customer’s BlinkUp SDK-based mobile or web app
    • Auto-assigned to a Test Factory Device Group’s target Test Production Device Group
    • Runs production application firmware
  • Production Device
    • Configured using a customer’s BlinkUp SDK-based mobile or web app
    • Auto-assigned to a Factory Device Group’s target Production Device Group
    • Runs production firmware

You should note that Development Devices and BlinkUp fixtures are added to your account using the Electric Imp mobile app (Public impCloud only) and therefore appear as unassigned devices until they are manually assigned to a Device Group.

Production Devices are never initially assigned to a Device Group manually. They are always assigned to their first group automatically, as a consequence of being blessed. However, they can be manually moved to another Production Device Group at a later time. When they receive their initial application firmware will depend on their Production Device Group’s attributes.load_code_after_blessing value: either right after blessing (true, the default) or after they have first been configured by an end-user (false).

Device Endpoints

  • Devices are accessed via the API endpoint /devices.
  • Specific devices are accessed via their unique ID: /devices/{device_ID}.
  • Examine a device object’s product and device_group relationships to determine which Device Group it has been assigned to, and to which Product that Device Group belongs.
  • To assign a device to a Device Group, set its relationships.device_group value. This automatically sets the relationships.product value to match that of the target Device Group.

Device Data Structure

The API represents a device as an object which contains the following keys:

  • id — The device’s unique ID, set by the system.
  • type — The object’s type: "device".
  • attributes
    • name — The device’s name, set by the user (1-80 characters).
    • mac_address — The device’s MAC address as last recorded by the system.
    • ip_address — the device’s IP address as recorded by the system.
    • rssi — The device’s last reported WiFi signal strength.*
    • free_memory — The device’s last reported free RAM.*
    • imp_type — The type of the device’s imp, eg. "imp005".
    • swversion — The device’s reported software version (as imp.getsoftwareversion())
    • device_online — Whether the device currently online (true) or not (false), set by the system.
    • device_state_changed_at — The date and time when the device last connected or disconnected, set by the system.
    • agent_id — The ID of the device’s current agent instance. This can be used to generate the agent URL.
    • agent_running — Whether the agent is currently operational (true) or not (false), set by the system.
    • agent_state_changed_at — The date and time when the agent last started up or shut down, set by the system.
    • last_enrolled_at — The date and time at which the device was last configured by BlinkUp.
  • relationships
    • devicegroup — The Device Group object to which the device has been assigned, set by the user or the system (in the case of a blessed production device assigned to its target Production Device Group). null if the device is unassigned.
    • product — The Product object to which the Device Group belongs, set by the system.
    • owner — The Account object that currently manages the Device Group, initially set by the system.

* These attributes are not currently returned as device records within lists, only as records returned for specific devices.

For a full list of Device-related endpoints and actions, please see the impCentral API Reference.

Restarting Devices

Individual devices can be restarted by making a POST request to the /devices/{device_ID}/restart endpoint.
All of the devices in a given Device Group can be restarted by making a POST request to the /devicegroups/{devicegroup_id}/restart endpoint.

Filtering Devices

Returning a list of all the devices associated with an account will return all your devices: not only development devices and factory BlinkUp fixtures, but also production devices. The API therefore makes uses of a pagination system to make the delivery of device lists — and for the delivery of Product, Device Group and Deployment lists — more manageable.

In addition, filters can be applied to the request to control how much information is returned — to limit a list of devices to solely development devices, for example.

Filtering and pagination are out of the scope of this document, but are detailed in ‘How to Use the impCentral API’.

Deployments

The impCentral API continues to keep device and agent code together but embodies them in a resource called a Deployment. A new Deployment can be pictured as a single commit. If the code is deployed using the impCentral API, the Device Group’s devices will receive the code when they next restart, though the API includes separate endpoints to allow them to be restarted immediately (see above).

Device Groups reference only a single Deployment at a time (or no Deployment if they are new groups). Each Deployment records the agent and device code. It also includes a timestamp indicating when the deployment took place; a 256-bit SHA of the agent and device code, and the parent account ID; an identifier indicating which user deployed the code; and a unique ID.

Assigning new, updated or unchanged code to a Device Group replaces the group’s previous code with the new code by changing the Deployment that the Device Group references.

If, when a new Deployment is created, any of the application code has been changed, the new Deployment will include a new SHA, otherwise the SHA will be the same. The Deployment ID and timestamp will be different. The user ID may be different.

impCentral neither imposes nor assumes any relationship between one Deployment and another — they can be different versions of the same application, identical instances of the same application, or completely different applications altogether. It is left entirely to the host application, such as an impCentral API-based third-party tool, to deal with version control. However, a deployment’s attribute.origin value can be used to track relationships between deployments: it can used to store the source deployment’s SHA or ID, for example. What information, if any, is stored in the origin attribute is up to you — this value is not populated by the system.

Deployment Endpoints

  • Deployments are accessed via the API endpoint /deployments.
  • Specific Deployments are accessed via their unique ID: /deployments/{deployment_ID}.
  • Deployments are created, deleted, modified (only their description, attributes.tags and/or attributes.flagged value) by selecting the appropriate HTTP verb when contacting these endpoints.
  • Examine a Deployment object’s relationships.product and relationships.device_group values to determine which Device Group it has been assigned to and to which Product that Device Group belongs.
  • Creating a Deployment necessarily involves specifying the Device Group to which it will be assigned.
  • Deployments can take up to 4MB of agent code and up to 4MB of device code.

Deployment Data Structure

The API represents a Deployments as an object which contains the following keys:

  • id — The Deployment’s unique ID, set by the system.
  • type — The object’s type: "deployment".
  • attributes
    • sha — A 256-bit SHA of the agent code, device code and owner account ID, set by the system.
    • description — The Deployment’s description, set by the user (0-255 characters).
    • agent_code — The Deployment’s agent code, set by the user (up to 4MB in size).
    • device_code — The Deployment’s device code, set by the user (up to 4MB in size).
    • origin — Free-form string field, set by the user.
    • flagged — Whether the Deployment can be deleted, set by the user or by the system depending on how the Deployment is assigned (see below); default is false.
    • tags — An array of strings that can be used to add metadata to the Deployment, set by the user.
    • created_at — When the Deployment was created, set by the system.
  • relationships
    • product — The Product object to which the Device Group belongs, set by the user (see below)
    • devicegroup — The Device Group object the Deployment has been assigned to, set by the user (see below).
    • creator — The Account object that created the Deployment, set by the system.
    • owner — The Account object that currently manages the Deployment, set by the user.
    • flagger — The Account object that changed the flagged attribute.

For a full list of Device-related endpoints and actions, please see the impCentral API Reference.

Deploying Code

To test code on development devices via the API, you need to create a new Deployment targeting a specific Product and one of its Development Device Groups.

To make the same code available for deployment to production devices, you need to duplicate the Deployment but set its relationships.devicegroup value to a Production Device Group.

When a new Deployment is created, its code is automatically staged for the target Device Group’s devices. Use the /devicegroup/{devicegroup_id}/restart endpoint to restart them, a process which causes them to receive the Deployment’s code. This applies to all devices other than not-yet-blessed production devices on the assembly line: they will receive the code either immediately after blessing (true, the default) or right after their first end-user BlinkUp (false), as selected by setting the Production Device Group’s attributes.load_code_after_blessing value.

Deploying Factory Firmware To BlinkUp Fixtures

Factory BlinkUp Fixtures run factory firmware in order to configure production devices on the assembly line for factory network access. Under impCentral, it’s sufficient to add a fixture to your account, assign it to a Test Factory or Factory Device Group under the chosen Product, create a Deployment with the factory firmware code and set it to reference the intended device group. It is not necessary to register the fixture’s MAC address with the Product, but the fixture being assigned can be identified to the API by its MAC address.

impCentral ensures that any DUTs configured by a given fixture will receive the correct factory firmware. Because the Test Factory or Factory Device Group record includes the attributes.production_target key, these DUTs will be assigned to a specific Test Production or Production Device Group, respectively, upon blessing and so receive the group’s deployed application firmware.

impCentral Product Example: ‘Connected Meter 400’

The Product ‘Connected Meter 400’ comprises 10 Device Groups:

  • Three for application firmware development/testing:
    • Connected Meter 400 1.0 Development
    • Connected Meter 400 2.0 Development
  • Four for factory firmware development and testing:
    • Factory Firmware 1.0-US Test Factory
    • Factory Firmware 1.0-US Blessings Test Production
    • Factory Firmware 1.0-RoW Test Factory
    • Factory Firmware 1.0-RoW Blessings Test Production
  • One for production factory firmware:
    • Line Fixtures Factory
  • Three for production application firmware:
    • 400 US SKU Production
    • 400 RoW SKU Production
    • 400 2.0 Field Test Production

The first two Development Device Groups are used to develop and test the versions they are named for. Version 1.0 of the Connected Meter 400 application firmware has been released to production, but its code is retained in case it requires future updates. Version 2.0 is in development and adds many new software features. Version 2.0 will eventually replace 1.0.

For factory firmware there is one two major versions, 1.0, but it exists in two forms: one containing test code for US-oriented devices, the containing code to test devices that will ship to the Rest of the World. Alongside the Test Factory Device Groups in which these versions of the factory firmware have been developed, there are two Test Production Device Groups to which promoted deployments of the 1.0 application firmware have been made. When a new iteration of the factory firmware is tested on DUTs, it yields blessed devices which are auto-assigned to the appropriate Test Production Device Group.

When an updated factory firmware deployment has passed the testing process, it is promoted and deployed to the Line Fixtures group, which contains all of the fixtures in the manufacturer’s Connected Factory. When the DUTs the configure are blessed, they are auto-assigned to the appropriate Production Device Group, to which the latest promoted deployment of Connected Meter 400 1.0 has already been deployed.

US and RoW Production Devices differ only in certain hardware-specific ways, so they both run the same application code but need to be tested and blessed with SKU-specific factory firmware. Deploying either Factory Firmware 1.0-US or Factory Firmware 1.0-RoW to Line Fixtures allows production to output US or RoW devices from the same, generic DUTs.

In preparation for the field testing of the Connected Meter 400 2.0 application firmware, a new Production Device Group has been set up and deployed with code from the Connected Meter 400 2.0 group. When the time comes for testing to begin, a number of Production Devices will be moved from 400 US SKU to 400 2.0 Field Test, at which point they will receive and run the version 2.0 application firmware (if they are online; if not, they will receive the new code when they next connect to the impCloud).