How to ready your connected product for end-use
If you are new to the manufacture of imp-enabled devices, we recommend that you read ‘What is the Factory Process? A Short Guide for Product Managers’ before continuing to read this document. Developers taking a product into manufacture should also view ‘Moving From Development to Production’.
Terms presented in bold represent formal Electric Imp Platform terminology.
A production device is any imp-enabled unit that has been manufactured and prepared specifically for end-use rather than development. Blessing is the process by which a newly assembled device — a device under test (DUT) is registered with the Electric Imp impCloud™ as an end-user device, and this is what the Electric Imp Connected Factory Process is designed to achieve. In order to be blessed, a DUT must be connected to the Internet; it is configured to do so using a technique called BlinkUp™.
The factory process is the same whether you are an Public impCloud customer or you are taking advantage of Electric Imp’s Private impCloud service. In the discussion that follows, references to the impCloud apply equally to Public and Private impClouds. Where the process takes a different path for Private impClouds than it does with the Public impCloud, this will be indicated in the text.
In order to take advantage of the factory process, you must be an Electric Imp customer.
For a given connected product, the Electric Imp Connected Factory Process has two phases: pre-production and production. Each phase comprises a number of distinct stages, listed below. The pre-production phase involves tasks that set up your assembly line and the Electric Imp impCloud to manufacture and provision products that will be compatible with the Electric Imp Platform. The production phase centers on the production devices themselves.
After production comes a completion phase, but since this will be customer and product specific — for example, final device assembly, labelling and packaging for shipment; unit processing for logistics and inventory management — it is not covered here.
Finally, there are post-production tasks: actions which you may take once the production run is in progress or has been completed. Such tasks are primarily concerned with releasing application software updates to devices in the field, and obtaining information, such as device logs, for technical support and real-world testing purposes. Though not specifically a part of the factory process, the post-production phase follows logically from it, and so is detailed here.
Your application firmware comprises not only the device-side software that will run on your connected product (the device), but also the Electric Imp impCloud-hosted code (the agent) through which each device will communicate with other Internet-connected resources.
You develop your application firmware using Electric Imp’s impCentral™, or using your own tools and the impCentral API to upload your code to the impCloud and test it on your development hardware. Application firmware is developed in Development Device Groups and deployed to production devices via Production Device Groups. Each such group belongs to a given Product. Products are how impCentral embodies a connected product or family of products.
When your application firmware is ready for release, you use impCentral’s code editor to promote the required version (distinguished by its SHA) in order to make it accessible to the production facilities in impCentral’s Production Zone.
In the Production Zone, you create a Production Device Group and deploy the promoted application firmware SHA to it. You must have such a promoted SHA available in order to create a Production Device Group. This deployment means that any production devices subsequently added to the group or already a member of it will immediately receive that application firmware (provided it is online; offline devices receive the code when they next connect). Production devices are added to a Production Device Group when they are blessed. We’ll see shortly how the impCloud knows which group to assign them to.
When you create a Production Device Group, you specify its initial application firmware deployment
Note If you subsequently update your application firmware’s code, you will need to manually promote the new SHA. This is to ensure that only those versions expressly judged to be suitable for deployment are able to be deployed via impCentral.
Factory firmware comprises code which runs on devices under test (DUTs) in the factory before they receive the application firmware they will run in the field. Factory firmware sits at the heart of the Electric Imp Connected Factory Process: it manages all of the tasks detailed in the production phase. In short, it is responsible for testing and blessing all DUTs before they come off the assembly line and are distributed to end-users.
The factory firmware also runs on your factory BlinkUp fixture. You must therefore equip your factory firmware with code paths for each of the two types of device on which it will run — DUTs and factory BlinkUp fixtures — and carefully ensure that these code paths are not executed on the wrong type of device:
The same factory firmware (top) runs in both a factory BlinkUp fixture, such as the Electric Imp impFactory™ (left), to
transmit WiFi and Electric Imp impCloud access credentials, and on a production device (right) to test the hardware
Electric Imp provides a free-to-use code library, FactoryTools, to help you in this task.
Factory firmware is developed in impCentral using a Factory Test Device Group. You create device code and agent code; factory firmware agents can be used to enable communication between a DUT and the factory BlinkUp fixture: for example, to relay device-specific information that the BlinkUp fixture will output via a connected label printer or laser-etching fixture. Similarly, fixtures and DUTs can use their agents to post or retrieve data from Internet-connected resources.
The following factory API methods are optional:
For more detailed guidance on the role of these methods and on preparing your factory firmware, see ‘Writing, Testing and Using Factory Firmware’.
When the factory firmware is ready for release, you use the Factory Test Device Group’s code editor to promote the required version (distinguished by its SHA) in order to make it accessible to the production facilities in impCentral’s Production Zone.
In the Production Zone, you create a Factory Device Group and then deploy the promoted factory firmware SHA to it. This deployment means that any factory BlinkUp fixtures added to the group will receive that factory firmware &dmash; as will DUTs subsequently enrolled by those fixtures.
Creating a Factory Device Group requires you to have created at least one Production Device Group, which will become the Factory Device Group’s Target. When a DUT is blessed, the impCloud assigns it to the target group of the Factory Device Group to which the factory BlinkUp fixture that enrolled the DUT belongs.
When you create a Factory Device Group you must specify which Production Device Group is its target
Your factory BlinkUp fixture must be assigned to a Factory Device Group. This is done by entering the fixture’s Device ID into impCentral’s ‘Assign Devices’ panel, which you call up by clicking on the ‘Fixtures’ link under the ‘MANAGE’ column alongside the chosen Factory Device Group. You will need to have added a fixture to your account as a development device (using the Electric Imp mobile app) to do this, and to have created a Factory Device Group. You will need to make note of the fixture’s device ID (it will be listed in the ‘My Development Devices’ view, which is accessed from the devices menu () in impCentral’s top bar:
You will need to construct or purchase your factory BlinkUp hardware before production commences and ideally before you plan to begin testing your factory firmware. Electric Imp offers for purchase a pre-made factory BlinkUp fixture, the impFactory™, which is also available as a reference design if you wish to build your own. At minimum, a factory BlinkUp fixture requires just an LED to transmit the BlinkUp signal and a means to initiate the BlinkUp transmission: a button may be pressed manually by an assembly line operator, or a wire can send a signal from a sensor in the assembly line.
Only one factory BlinkUp fixture is required for each assembly line but you may designate, create and use as many as you like. Factory BlinkUp fixtures can be re-assigned to a different Product’s Factory Device Group in order to be used again for different production runs.
Whichever factory BlinkUp fixture you choose to use, it must be configured to access the Internet via the factory’s WiFi network. To do so:
Note If you need or want to re-configure a factory BlinkUp fixture and it is currently assigned to a Factory Device Group or Factory Test Device Group, you must unassign it or re-assign it to a Development Device Group first.
Electric Imp provides two event-triggered webhooks which you can use to connect the factory process to your own record-keeping systems. These webhooks are configured on a per-Device Group basis: for Factory Test Device Groups and/or Production Device Groups. The webhooks will not be triggered if they have not first been configured. Webhooks are configured in the chosen Device Group’s settings:
The two webhooks are:
To configure either webhook, you provide the URL of an endpoint on your server, a third-party logging service, or even a development device’s agent. The Electric Imp impCloud automatically posts an HTTP request with a data payload in JSON format to the endpoint when the named event takes place.
For more detailed information on configuring webhooks and the data they return, see ‘Production Webhooks’.
Each Factory Test Device Group allows you to thoroughly test the factory flow embodied in its development factory firmware. Not only can you run the factory firmware on test fixtures assigned to the Device Group, but those fixtures can be used to emulate the factory: they can enroll DUTs which will then receive the factory firmware. In other words, factory firmware calls to the factory API’s server.factoryblinkup() and server.bless() methods will be functional. Test blessed devices are listed in impCentral (click on the Factory Test Device Group’s device icon () in the sidebar) and their logs examined:
To test-bless devices, you will need to deploy promoted application firmware to them. You do this by clicking on the ‘Deploy’ button in the test blessed devices view, and then select a promoted application firmware deployment, which you can identify using the details provided, including the code’s SHA. You must also provide a brief description of the deployment:
Unsuccessfully blessed DUTs can be re-used in further testing. So can successfully test-blessed devices, but you will need to unbless them first. This can be achieved by selecting ‘My Development Devices’ from the devices menu () in impCentral’s top bar, and then locating your test-blessed device(s). For each one you want to unbless, click ‘Delete’ in the ‘Manage’ column. Deleting removes a device from your account; in the case of test-blessed devices, it also returns them to an unblessed state ready to be re-blessed with your test fixture. You will be asked in a pop-up to confirm your decision: click on the ‘Delete’ button to do so.
The production phase of the Electric Imp Connected Factory Process involves using the factory BlinkUp fixture on the assembly line to configure each newly assembled DUT in turn. This provides each DUT with the information it needs to connect to the factory WiFi network, to identify itself to the Electric Imp impCloud, and to receive the assigned factory firmware.
This part of the factory process takes place entirely within the factory. It does not make use of impCentral. The following diagram summarizes what takes place on the assembly line:
This flow comprises four key operations:
Though the DUT contains a wireless module, it is not yet able to connect because it has not been supplied with local network access credentials. Imp-enabled devices are provisioned with these credentials using BlinkUp, a technique which optically transmits the wireless network’s SSID and password to the device. It also transmits an enrollment token which the device uses to identify itself to the impCloud. BlinkUp takes approximately five seconds.
In the factory, the source of the BlinkUp signal is a factory BlinkUp fixture which you have already set up in the pre-production. Each DUT incorporates a photoreceptor to receive the signal. If the transmission LED is sufficiently bright, it need not be placed right up close to a production device’s photoreceptor.
A DUT’s progress while being configured and then connecting to the Electric Imp impCloud will be indicated on its LED with a number of these patterns.
Log messages posted by devices during the factory process will not appear in the Factory Test Device Group as is the case with development devices. Instead, you will use impCentral’s production logging facility in factory mode. Production logging can be used to help you monitor the factory process and to debug your factory firmware while it is running on a proper assembly line.
The DUT now runs the deployed factory firmware. The device must be blessed for end-use or it will be rejected by the Electric Imp impCloud when an end-user attempts to activate it. If the device is not blessed, it must be considered a development device: to be used by you and your developer colleagues, but not by an end-user.
The factory API’s bless command, server.bless(), takes a parameter value indicating whether the DUT passed (
true) or failed (
false) any hardware tests; on
false, the device’s LED goes red to alert the assembly line operator. Only if the value is
true will the blessing process be attempted; if it succeeds the LED goes green, otherwise the LED goes red.
Once blessed, the DUT is now a production device that is registered with the Electric Imp billing system. It has also been assigned to a Production Device Group. Whenever an update to the application firmware is deployed to the group, the device will receive the new code automatically and without end-user intervention. This bond is effectively permanent; unlike a development device, the end-user cannot change the blessed device’s application firmware.
The successful completion of this stage of the factory process will be signalled to your server if you have made use of the Blessing webhook.
The factory firmware should be coded to clear the blessed production device’s network settings and factory enrollment token after blessing. This ensures that the unit will be in a clean state when an end-user activates their newly purchased device. This is simply a matter of including the factory API call imp.clearconfiguration() at the end of the production device code flow in your factory firmware.
The production device will download its intended application firmware at this time, though you may elect to have the software download once an end-user has activated the device in the field. The former is recommended for applications which require a new device to begin operating as soon as it is powered on — for example, your product displays set-up instructions on a screen or performs some other pre-configuration task.
Downloading the application firmware immediately is the default, and will take place as soon as the callback function executed by the sever.bless() call completes. For this reason, it’s important to include the call to imp.clearconfiguration() within that callback.
Whichever of these alternatives you pick, you can be sure that once an end-user has activated a device, it will receive the latest version of the application firmware.
Given good prior testing in the lab and in the factory, the connected factory process should proceed smoothly, as has been demonstrated by many Electric Imp customers. If you do experience difficultly, there are a number of key factors you should consider initially.
When a DUT first connects to the impCloud, it checks whether it is running the most up-to-date version of impOS™ that it has been allowed to run. If an update is available, this will be downloaded and installed now: the status LED will go solid green for the duration of the upgrade process. This is not an indication that blessing was a success — the DUT has not yet downloaded and executed your factory firmware.
The update duration is relatively short but dependent on local Internet conditions — connectivity, the presence of a proxy, etc. — so you should not assume your factory firmware will run after a measured time. The duration of the ‘BlinkUp → possible update → restart → test-and-bless’ cycle will likely be different between your lab and your factory.
When updating is complete, the DUT will restart, re-connect, and download and run the factory firmware — subject to the potential issues described below.
If BlinkUp failed (indicated by a fast red flash), check the physical placement of the DUT relative to the fixture’s emitter. You may also wish to check the DUT’s BlinkUp circuit design.
If BlinkUp succeeded (three seconds of solid green followed by red and amber flashes) but the DUT doesn't connect, check the WiFi credentials embedded in or retrieved by the factory firmware and passed into the server.factoryblinkup() call.
Make sure the fixture is configured for network access using the Electric Imp mobile app.
Note If you are private impCloud customer, you will need to use your own BlinkUp web app in development mode.
If your factory firmware includes tests of the DUT hardware, you should feed the result of those tests as a single Boolean value into the server.bless() call. This ensures that the DUT’s LED will signal red if the hardware test failed, allowing a factory operator to identify the faulty unit and remove it. As that is the same effect as blessing itself failing, your factory firmware should include log messages to help you determine where the point of failure lies. If it is in the hardware test section of your factory firmware, check the code and/or the DUT hardware manually.
Blessed devices cannot be re-blessed, so if a DUT appears to be failing after it has already been successfully blessed, check that it is not still blessed.
If a DUT is connected but is not indicating bless success or failure, check that the promoted factory firmware’s blessing flow includes the key server.bless() call and that it has not been disabled for development testing.
Factory BlinkUp fixtures will not be able to perform factory BlinkUp if they are not assigned to a Factory Device Group. To assign a fixture to a different Product, you need to first remove it from the Factory Device Group that it is currently assigned to. Once that's done, you can’t use it to configure DUTs for that same Factory Device Group until it is re-assigned to it.
This issue is commonly seen with customers who are testing multiple factory flows simultaneously using the same fixture. Either label the fixture with the name of the Product which contains the Factory Test Device Group or Factory Device Group to which it is currently assigned, or obtain sufficient fixtures so that each Product has its own unit.
DUTs which leave the factory in an unblessed state and end up in the hands of end-users are called ‘factory escapes’. These devices will not work for end-users.
To avoid factory escapes, take care to ensure that all DUTs are tracked and that only blessed devices are placed in product packaging and dispatched from the factory. We strongly recommend that you print a self-adhesive label which can be attached to devices and/or their packaging — or they can be laser-etched — when they are successfully blessed. You can use your factory firmware’s agent code to relay device information to the printing/etching station to ensure each label or mark is tied to a specific device.
Devices coming off the production line without a mark or label should be considered faulty and sent back for re-work. They should not remain in the production flow. This can help to significantly minimize factory escapes.
The Electric Imp Platform makes it very easy to promote and deploy updates and improvements to application firmware. This may be done at any time, and does not require action on the part of your end-users.
Deploying an update is a two-stage process, both steps being conducted in impCentral:
These two operations are performed separately in order to provide you with an opportunity to identify and correct issues in the chosen version before deployment takes place. Deployment is irrevocable, but issues can be quickly rectified by promoting and then deploying a subsequent version of the code.
You may choose to develop updates in the original Development Device Group or in a new Development Device Group created for the purpose — the choice is yours. Similarly, if you want to deploy the update to a subset of your production devices, you simply create a new Production Device Group to which the updated code’s promoted SHA will be deployed, and then migrate a proportion of the first group’s production devices to the new own. On assignment, they will receive the new group’s deployed code. When the update meets will QA approval, you can move the remainder of your production devices to the new group. The original group can later be re-used to sample the next update.
Deployment is the final step in the update process. Once a new SHA is deployed to the chosen Production Device Group, every production device assigned to that group will receive the new software. Devices which are powered down or sleeping at this point will update when they next come online.
It is possible to unbless production devices, a process which makes the target device able to be used for development. To perform this task, locate the relevant Production Device Group and click ‘Devices’ under the ‘MANAGE’ column. Locate the device in the list and then click ‘Delete’ under the ‘MANAGE’ column. The device will now be unblessed.
If you know the ID, MAC address or agent URL of the target device, you can use the device lookup option in the devices menu to call up the device’s details. Now look for the ‘Actions’ menu at the top right of the view and select ‘Delete’ from it to unbless the device (if it is a production device).