Everything You Need To Know About Factory Control Code
Factory firmware is Squirrel code you develop to run on devices in an Electric Imp Connected Factory. This includes Devices Under Test (DUTs) on the assembly line, and the imp-based BlinkUp™ fixtures you will use to prepare these DUTs for access to the Electric Imp impCloud™ and for factory network access, as required.
Each of these types of device run their own, device-specific factory firmware: one for fixtures, another for DUTs. You develop this code within impCentral™’s Test Zone in the code editor of a Test DUT Device Group (DUT firmware) and a Test Fixture Device Group (fixture firmware). Eventually, when you put your connected product into production, you will deploy the code to a DUT Device Group and a Fixture Device Group as part of the Connected Factory Process
The fixture firmware’s task is to perform BlinkUp in the factory. Like the BlinkUp of a development device, factory BlinkUp is an optical process that transmits device-enrollment tokens and, if required, network access credentials. This transmission is made by a BlinkUp fixture equipped with an LED and running the fixture firmware.
Fixture firmware is deployed to a Test Fixture Device Group (for development and testing) or a production-ready Fixture Device Group. When a BlinkUp fixture is assigned to either of these types of Device Group, it receives the deployed fixture firmware.
Factory BlinkUp is initiated by calling the factory-only imp API method server.factoryblinkup() in your fixture firmware. The method will have no effect it if is called in DUT firmware. It has four parameters, all of which are required:
"dummy", if WiFi is not required)."", if there is no password or WiFi is not required).Calling server.factoryblinkup() causes the BlinkUp fixture to retrieve a factory enrollment token from the impCloud server and then transmit it to the DUT. It also sends the supplied network credentials. The method returns immediately; the request for the factory enrollment token is performed asynchronously. BlinkUp only begins when the token has been received, and Squirrel is suspended until BlinkUp is complete. After BlinkUp, Squirrel resumes, and the fixture is ready to configure another DUT on the assembly line.
Typically, BlinkUp is triggered by an assembly line operator pressing a button, or in response to a signal from a sensor integrated into the line to track assembly progress. In the case of the impFactory, the button is on pin C. You will need to ensure your fixture firmware can detect the button press or sensor signal; it should then call server.factoryblinkup().
Like all other devices, DUTs indicate a successful BlinkUp by lighting their BlinkUp LED green for three seconds.
Full fixture firmware sample code is linked at the end of this guide.
When a DUT has been configured by a BlinkUp fixture, it is able to connect to the impCloud and submit the factory enrollment token that it received. This token is used to authenticate the DUT as a valid factory device. Once the DUT has been authenticated by the impCloud, it is assigned to a Test DUT Device Group (for development and testing) or a production-ready DUT Device Group and therefore receives the DUT firmware deployed to the group.
To minimize factory escapes — working and saleable production devices that are outside of your supply chain — it’s very important to ensure that your DUT firmware is not a version of your application firmware. A DUT that is removed from the factory should not be able to operate as a production device.
DUT firmware can be used to provision the ‘raw’ DUT with content it will need in the field. For example, your product might require image and audio data, or sensor calibration values, to be stored in Flash; the latest version of these assets can be retrieved and stored by the DUT firmware right on the assembly line. Other device initialization operations can be performed too.
DUT firmware should also be used to run tests that verify that the provisioned DUT works correctly and can therefore be sold to an end-user. This testing is an opportunity to weed out units containing failed components, for example.
In some cases, test results can be assessed in code. Others may require an assembly line operator to verify a successful result and confirm that by pressing a button built into the device or by bridging two terminals on the unit’s PCB.
Such tests help minimize the number of ‘bad’ units leaving the factory. This in turn minimizes product returns and end-user support requests.
Once the DUT has passed all of your tests, it is ready to become a Production Device, ie. a unit that is suitable for sale to an end-user. This process is called blessing. To bless a DUT for end-use, the DUT firmware calls the factory-only imp API method server.bless(). This method is mandatory: your DUT firmware must include it.
server.bless() has two parameters, testSuccess and callback, which respectively take a boolean value and a function.
The boolean value should be generated by the code within your DUT firmware that tests the unit’s hardware. The outcome of these tests should be true for a pass, or false for a fail. Only if true is passed into server.bless()’s first parameter will the impCloud be contacted to bless the DUT. If the first server.bless() parameter is passed false, the DUT’s BlinkUp LED will go red to alert the assembly line operator to remove the rejected device. The LED will also go red if blessing fails. Only if testSuccess is passed true and blessing is successful will the LED go green:
| testSuccess Value | Was blessing successful? | BlinkUp LED Color |
|---|---|---|
true |
Yes | Green |
true |
No | Red |
false |
Blessing not attempted | Red |
If the LED appears red, the DUT is not blessed.
If true is passed into server.bless()’s testSuccess parameter, the blessing request is sent to the impCloud server, and server.bless() returns. When the server responds, whether blessing succeeded or failed, the function passed into the callback parameter is executed. At this point, the DUT’s LED goes green to indicate blessing success, or red for blessing failure.
Unlike the three-second period during which the LED goes green to show BlinkUp success (in the factory or outside of it), the green blessing success indication is maintained until the Production Device (ie. the blessed DUT) is powered down.
It is also possible that the DUT’s initial connection to the impCloud will also result in it downloading an impOS™ update. After this update is installed — the time this takes is primarily dependent on the factory’s Internet connection — the DUT will reboot and then run its assigned factory firmware.
It is important to note, therefore, that DUT LEDs may go green for a period of time, but that this is not necessarily an indication that blessing was performed and succeeded. Only the blessing success indicator keeps the LED green, so you should not rely solely on visual inspection for determining which stage in the BlinkUp-Update-Blessing sequence the DUT has reached at any given time. We strongly recommend that you make use of your firmware’s agent code to provide machine- and/or human-readable indications of which stage a DUT has reached.
If your assembly has multiple stages, you can make use of more than one DUT firmware. Each stage will require its own BlinkUp fixture running stage-specific fixture firmware. It will also require stage-specific DUT firmware. You can run factory BlinkUp on a DUT any number of times, but only until it is blessed. Blessing is mandatory, but only in the final piece of DUT firmware that the DUT will run.
| DUT | BlinkUp Fixture 1 | BlinkUp Fixture 2 | ... | BlinkUp Fixture n |
|---|---|---|---|---|
| Runs... | DUT firmware #1 | DUT firmware #1 | ... | DUT firmware #n |
| Conducts tests... | Suite #1 | Suite #2 | ... | Suite #n |
| Is blessed? | No | No | No | Yes |
| Assigned to a Production Device Group | No | No | No | Yes |
Fixture Device Groups require a Production Device Group set as a target. You can set the same Production Device Group as the target for all of your multi-stage Fixture Device Groups. This is because only the last DUT firmware in sequence will actually bless the DUT, ie. only this firmware will cause the DUT to be assigned to a Production Device Group. Once a DUT is blessed, it cannot undergo factory BlinkUp, but unblessed DUTs can undergo factory BlinkUp as many times as necessary.
The callback function registered with server.bless() should call imp.clearconfiguration() to erase your factory’s network credentials and the factory enrollment token from the DUT. This ensures that the end-user sees the device as a ‘clean slate’: when the device is next powered up, the device will correctly signal on its BlinkUp status LED that it is ready to be activated.
You should include as little code in your post-bless callback as possible. Only include code which needs to take place after blessing; all other code, eg. tests, device provisioning, should be executed before server.bless() is called.
If the device’s target (Test) Production Device Group is set to download its application firmware upon blessing (this is the default), then approximately two seconds after the post-bless callback is triggered, the server sends the DUT a restart signal. As soon as the device goes idle, if it is not already in this state, impOS will restart the device’s Squirrel Virtual Machine (VM). This in turn caused the device to fetch its application firmware.
The restart signal is sent by the impCloud. Because of the nature of Internet communications, you should not assume the time taken to receive and install the application firmware will be of a fixed duration. The recommended procedure therefore is to prevent your DUT firmware from going idle in the post-bless callback until all of its essential tasks have been completed. As soon as Squirrel yields, impOS will be free to restart the Squirrel VM, which will cause the application firmware to be fetched.
If you are installing your application upon device activation (either the first end-user BlinkUp or you are activating Production Devices in the factory), you can simply power down the device once the code in the post-bless callback has been run.
Note The Production Device (ie. the blessed DUT) does not have an agent at this point. Its agent will not be instantiated until it is activated by an end-user through a BlinkUp operation.
Full DUT firmware sample code is linked at the end of this guide.
You develop factory firmware for a specific Product within impCentral’s Test Zone. You will need to perform the following actions:
Your DUT firmware and fixture firmware will make use of the Electric Imp Factory API. We have already mentioned some of the methods in this API (server.factoryblinkup(), server.bless() and imp.clearconfiguration()) but there are others. The full Factory API is described here.
Note Factory firmware is currently not able to make use of the imp API’s nv table to persist data across warm reboots.
Factory firmware of either type can incorporate agent code as well as device code; factory agents are instantiated when the device receives its factory firmware. Agents can be used to connect DUTs to the fixture that performed BlinkUp on them (for example, you provide information that will be printed on a fixture-connected print station) and for DUTs to signal their state to your own record-keeping systems.
Factory agents will continue to run for as long as they are in active communication with their device, or for a set period of time should communication be lost. In the case of BlinkUp fixtures, that extension period is 30 days. For DUTs, however, the agent will continue to run only for a further 24 hours.
impCentral makes testing factory firmware not only easy but also does so by replicating how it will be run in the factory. You assign BlinkUp fixtures to your Test Fixture Device Group, and these then receive your in-development fixture firmware. You can view their logs in impCentral. They can be then used to configure DUTs, which will receive and run the DUT firmware by being assigned, post-BlinkUp, to a Test DUT Device Group. Which group they are assigned to at this point is indicated by a Test Fixture Device Group setting.
In the test environment (impCentral’s Test Zone), all calls to server.factoryblinkup() and server.bless() work exactly as they do in production. Upon blessing, DUTs become Test Production Devices — they are assigned to a Test Production Device Group, also specified as a Test Fixture Device Group setting.
Note BlinkUp fixtures will log to the Test Fixture Device Group’s code editor; DUTs will log to the Test DUT Device Group’s code editor; Test Production Devices will log to the Test Production Device Group’s code editor.
To use your fixture firmware in production, you will need to promote it to impCentral’s Production Zone. Do this by clicking on the Promote button in the impCentral Test Fixture Device Group code editor, or by viewing an existing deployment’s settings (navigate to your Product’s Test Fixture Device Groups list and click Deployments under MANAGE, then click Settings under MANAGE) and checking the Promoted box.
The same process is used to promote your DUT firmware to production, only this time you will work within a Test DUT Device Group.
You should have already promoted a similar deployment of your application firmware.
Now follow these steps:
Should you update your DUT firmware, perhaps to add further hardware tests, you will need to promote it again from its Test DUT Device Group, as described in the previous section. Once promoted, the new code can be deployed to a DUT Device Group in the Production Zone as detailed above. When the updated DUT firmware is deployed, it will be received by all DUTs that are factory-enrolled after this point.
Updating your fixture firmware requires the same actions, except that they will involve your Test Fixture Device Group (for code promotion) and a Fixture Device Group (for deployment to production). Add fixtures in that group will receive the new firmware immediately.
You may include server.log() and server.error() calls in your factory firmware. When run in Test Factory Device Groups, these calls will log messages in the usual way: from fixtures, within the Test Factory Device Group code editor’s log pane; from DUTs, within the Test DUT Device Group code editor’s log pane.
You will find a complete factory firmware example, based on the code segments listed earlier, in our Sample Code section.