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 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.
/products./products/{product_ID}.The API represents a Product as an object which contains the following keys:
"product".For a full list of Product-related endpoints and actions, please see the impCentral API Reference.
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:
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.
/devicegroups./devicegroups/{device_group_ID}.{ "relationships: {
"product": {
"type": "product",
"id": "01560db4-1ca2-5af3-de74-fb5cc7c2bf9e" }
}
}
The API represents a Device Group as an object which contains the following keys:
"production_devicegroup", "development_devicegroup", "factory_devicegroup", "pre_factoryfixture_devicegroup" or "pre_production_devicegroup".true) or first end-user BlinkUp (false), set by the user. Only valid for Production Device Groups.For a full list of Device Group-related endpoints and actions, please see the impCentral API Reference.
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.
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.
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.
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 are organized into five basic types:
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).
/devices./devices/{device_ID}.The API represents a device as an object which contains the following keys:
"device"."imp005".true) or not (false), set by the system.true) or not (false), set by the system.null if the device is unassigned.* 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.
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.
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’.
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.
/deployments./deployments/{deployment_ID}.The API represents a Deployments as an object which contains the following keys:
"deployment".false.For a full list of Device-related endpoints and actions, please see the impCentral API Reference.
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.
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.
The Product ‘Connected Meter 400’ comprises 10 Device Groups:
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).