Factory floor operations
Manufacturing connected devices that incorporate Azure Sphere hardware involves several factory-floor operations:
- Connecting each Azure Sphere chip to a factory floor PC
- Recording device IDs
- Updating the Azure Sphere OS if necessary
- Loading software
- Running functional tests
- Performing radio frequency (RF) testing and calibration, if necessary
- Verifying RF configuration
- Finalizing the device
You must connect the chip to the PC first and finalize the device last, but you can perform other operations in any order that suits your manufacturing environment.
The Manufacturing Samples package contains sample scripts for updating the OS on multiple devices in parallel, for claiming multiple devices at once, and for performing a device ready check. A separate RF Tools Package includes utilities and a C API library for use in testing and calibrating radio frequency (RF) operation. Please contact your Microsoft representative if you need either of these packages.
Connect each Azure Sphere chip to a factory floor PC
During manufacturing, you must connect each Azure Sphere chip to a factory floor PC. The PC must be running Windows 10 v1607 (Anniversary update) or a more recent release.
The Azure Sphere tools run on the PC and interact with the chip over a chip-to-PC interface. You choose how to implement this interface:
- Design an interface board that connects to your PC during manufacturing.
- Build an interface into each connected device. For example, the MT3620 reference board design (RDB) includes such an interface.
The MCU programming and debugging interface provides details on the design and requirements for the chip-to-PC interface.
You'll need to install the Azure Sphere SDK to connect devices to a PC and to perform other factory-floor tasks. See Install Azure Sphere for instructions.
You can simultaneously connect as many Azure Sphere devices to your PC as the PC's USB subsystem will support. The Azure Sphere tools do not limit the number of devices that can be connected at one time. We recommend that you request the Manufacturing Samples package, as described previously, to help you perform manufacturing tasks at scale.
Support for multiple attached devices is provided only by the azsphere CLI. The Visual Studio and Visual Studio Code extensions currently support development and debugging of only a single device (the first device), which must have IP address 192.168.35.2.
The azsphere command supports several features that enable you to gather information about all the devices that are attached to a PC and to perform operations when multiple devices are connected.
Get information about attached devices
You can gather information about all attached Azure Sphere devices by using the following command:
azsphere device list-attached
This command returns the IP address for each Azure Sphere device and a value that identifies the device's USB connection. If the device is responsive, the command also returns the device ID. For example, the following shows output for two devices:
2 devices attached: --> Device ID: <deviceID> --> Is responsive: yes --> IP address: 192.168.35.2 --> Connection path: 11433 --> Device ID: <deviceID> --> Is responsive: yes --> IP address: 192.168.35.3 --> Connection path: 123
The IP address is assigned when an FTDI-based device interface is attached to the PC; it does not indicate that a responsive device is present. The IP address persists while the FTDI-based device interface is attached to the PC, even if a different Azure Sphere device is plugged into the interface. After a PC reboot, however, the IP address may change. The first device to be attached is assigned the address 192.168.35.2.
The connection path is an FTDI location ID that identifies the USB connection. The location persists while the FTDI-based device interface is attached to the same USB port on the same USB hub, and in turn to the same port on the PC. Thus, it persists over reboot. However, any changes in wiring between the PC and the device may result in changes to the connection path. Like the IP address, it doesn't change even if a different Azure Sphere device is plugged into the FTDI interface.
Perform operations on attached devices
The azsphere device command supports two additional global parameters to identify a device by USB location or IP address:
|--deviceip, -ip IP-address||Identifies a device by its IP address, which is returned by azsphere device list-attached|
|--devicelocation, -l USB-location||Identifies a device by its connection path, which is returned by azsphere device list-attached|
Use either of these parameters to identify the device to which an azsphere device
Every device is assigned an IP address—even if it's unresponsive—so you can use the IP address to identify a device that requires recovery.
The following table lists the azsphere operations with which you can use these two parameters.
Update the Azure Sphere OS
Every Azure Sphere chip is loaded with the Azure Sphere OS when it is shipped from the silicon manufacturer. Depending on the version of the Azure Sphere OS on chips available from your supplier, and depending on the OS version requirements of your application, you might need to update the Azure Sphere OS during manufacture of the connected device.
You can obtain the most recently available Azure Sphere OS recovery files for MT3620-based hardware after you accept the license terms.
If the Azure Sphere chip is not online on the factory floor, you can update it by loading the recovery files onto the factory floor PC and then issuing the azsphere device recover command over the programming and debugging interface described earlier. Use the
--images parameter to install specific recovery images.
The Manufacturing Samples include an example script that performs parallel multi-device recovery. Please contact your Microsoft representative to get this package.
Record device IDs
As part of the factory-floor process, you should record the device IDs of all Azure Sphere chips that your company incorporates into manufactured devices. To get the device IDs of all attached devices, use azsphere device list-attached.
You will need the device IDs during cloud configuration to set up device groups and deployments.
All software that you load—regardless of whether it is a board configuration file, a testing application, or a production application intended for the end user—must be production-signed.
During manufacturing, Azure Sphere devices must not require any special device capabilities, such as the appdevelopment capability, which enables debugging. Acquiring capabilities for individual devices reduces device security and requires internet connectivity, which is typically undesirable on the factory floor.
Get production-signed images
The Azure Sphere Security Service production-signs each image when you upload it. To avoid the need for internet connectivity on the line, create the production-signed images once, download them from the Azure Sphere Security Service, and then save them on a factory-floor PC for sideloading during production.
To get a production-signed image, upload it to the Azure Sphere Security Service by using the azsphere image command:
azsphere image add --filepath <imagepackage-file>
Replace <imagepackage-file> with the name of the image package that contains your software. The Security Service production-signs the image and retains it.
Applications that are intended for use only during factory testing must be explicitly identified as temporary images. This ensures that these applications can be removed at the end of the testing process. To mark an image as temporary, use the --temporary parameter when you upload the file for production signing:
azsphere image add --filepath <imagepackage-file> --temporary
Save the component ID that the command displays; you'll need it later to remove the temporary image from the device.
To download the production-signed image, use the following command:
azsphere image download --imageid <image-id> --output <file-path>
Replace <image-id> with the ID of the image to download, and replace <file-path> with the filename and path in which to save the downloaded image. The image ID appears in the output of the azsphere image add command.
After you save the production-signed image, no further internet connectivity is necessary.
Deploy and delete images
To deploy a production-signed image onto a device in the factory, use the azsphere device sideload command:
azsphere device sideload deploy --imagepackage <file-path> [--deviceip <ip> | --devicelocation <USB location>]
Replace <file-path> with the name and path to the downloaded image file. If multiple devices are connected to the PC, include the --devicelocation or --deviceip parameter to identify the target device. See Perform operations on attached devices for details about these parameters.
If you load a temporary application for testing, use the following command to delete it after testing is complete:
azsphere device sideload delete --componentid <component id> [--deviceip <ip> | --devicelocation <USB location>]
Run functional tests
Functional tests verify that the product operates correctly. The specific tests that you should run depend on your individual hardware.
You can organize your tests as a single OEM application or as a series of applications. The application development documentation, the Azure Sphere samples, and the templates in the Azure Sphere SDK provide information about application design. Whatever design you choose, this application needs to be production-signed and then deployed using the steps in the previous section.
Some testing processes require communication with the chip that is being tested: to report errors, log data, or sequence tests. If your testing process requires communication, you can use the peripheral UARTs on the MT3620 (ISU0, ISU1, ISU2, or ISU3). Connect these UARTs to your factory PC or external test equipment using suitable circuitry of your design. If you created an interface board to support chip-to-PC communication, you might want to add this circuitry to that board.
Perform RF testing and calibration
Azure Sphere chips require wireless connectivity to receive software updates and communicate with the internet. Testing and calibrating RF operation is therefore a critical part of the manufacturing process. If you are using a module, certain aspects of RF testing might not be required; consult the module supplier for details.
The RF Tools package, available upon request, includes utilities and a C API library for use during testing. Using the library, you can program product-specific RF settings in e-fuses, such as the antenna configuration and frequency, as well as tune individual devices for optimal performance. If your test house needs to use the tool to certify your device, please contact your Microsoft representative before sharing the software with them.
Integration between the library and test equipment is your responsibility. Currently, Microsoft has partnered with LitePoint to provide a turnkey solution that integrates the Azure Sphere RF test library with the LitePoint equipment. Solutions from other test equipment vendors may become available in the future.
The RF testing tools topic describes how to use the RF tools.
At the same time as RF and Wi-Fi calibration, consider also connecting to a Wi-Fi access point to verify that your end-user application will be able to communicate over Wi-Fi. Ensure that the Wi-Fi connection does not have internet access, because over-the-air update may occur if the chip connects to an internet-enabled access point. After Wi-Fi testing, you should remove any Wi-Fi access points used for testing from the chip so that it is not visible to customers. For details about Wi-Fi configuration, see azsphere device wifi. Note that device recovery removes all Wi-Fi configuration data from the chip.
Verify RF configuration
Use the RfSettingsTool to verify that the radio configuration options such as target transmit power, region code, and MAC address have been correctly set. The RF settings tool documentation provides more information about using this tool.
Finalize the Azure Sphere device
Finalization ensures that the Azure Sphere device is in a secured state and is ready to be shipped to customers. You must finalize the device before you ship it. Finalization involves:
Running ready-to-ship checks to ensure that the correct system software and production application are installed and RF tools are disabled.
Setting the device manufacturing state to lock out RF configuration and calibration tools and prevent security breaches.
Run a ready-to-ship check
It is important to run a ready-to-ship check before you ship a product that includes an Azure Sphere device. A typical ready-to-ship check ensures the following:
- Azure Sphere OS is valid
- User-supplied images match the list of expected images
- Device manufacturing state is DeviceComplete
- No unexpected Wi-Fi networks are configured
- Device does not contain any special capability certificates
Some of the tests in the preceding list may differ if you are designing a module rather than a connected device. For example, as a module manufacturer you might choose to leave the chip in the "Blank" manufacturing state so that the customer of the module can perform additional radio testing and configuration.
The Factory Tools package includes a sample Python script called deviceready.py, which checks all the listed items. The deviceready.py script can be used as-is or modified to suit your needs. It also demonstrates how to run the Azure Sphere CLI tools to perform these device-ready checks programmatically as part of an automated test environment.
If your Azure Sphere SDK is installed in the default location, the deviceready.py script can be run from an Azure Sphere Developer Command Prompt without providing the path to the azsphere.exe executable. If you have installed the SDK in a different location, you will need to supply the path to the azsphere.exe executable with the --binpath command-line argument.
The deviceready.py script takes the following parameters:
- The --os parameter specifies the valid versions of the Azure Sphere OS for the check to succeed. If no OS versions are supplied, this check fails.
- The --images parameter specifies the image IDs that must be present for the check to succeed. If the list of installed image IDs differs from this list, the check fails. By checking image IDs (rather than component IDs) this check ensures that a specific version of a component is present on the device.
- The --os_components_json_file parameter specifies the path to the JSON file that lists the OS components that define each version of the OS. For MT3620-based devices, this file is named mt3620an.json and is available only by download. The mt3620an.json is not part of the Manufacturing Samples package.
- The --binpath parameter specifies the path to the azsphere.exe utility. Use this parameter only if the Azure Sphere SDK is not installed in the default location.
- The --help parameter shows command-line help.
- The --verbose parameter provides additional output detail.
A sample invocation of the deviceready.py script when running from the same folder as the deviceready.py file looks like the following:
> python .\deviceready.py --os 19.02 --images e6ca6889-96d3-4675-bbe5-251e11d02de0
Set the device manufacturing state
Sensitive manufacturing operations such as placing the radio in test mode and setting Wi-Fi configuration e-fuses should not be accessible to end users of devices that contain an Azure Sphere chip. The manufacturing state of the Azure Sphere device restricts access to these sensitive operations. Manufacturing states include:
Blank. The Blank state does not limit the manufacturing operations on a chip. Chips in the Blank state can enter RF test mode and their e-fuses can be programmed. When chips are shipped from the silicon factory, they are in the Blank manufacturing state.
Module1Complete. The Module1Complete manufacturing state is designed to limit the adjustments users can make to radio configuration settings such as maximum transmit power levels and allowed frequencies. RF commands can be used until Module1Complete is set. Restricting end-user access to these settings may be required to satisfy regulatory policies around radio hardware. This setting primarily affects manufacturers who need to test and calibrate radio operating parameters.
Microsoft recommends that you set this manufacturing state after radio testing and calibration have been completed; RF commands cannot be used after it is set. The Module1State protects the device against changes that may disrupt proper operation of the radio and other wireless devices in the vicinity.
DeviceComplete. The Device Complete manufacturing state allows manufacturers of finished products to secure devices that are deployed in the field against changes. Once a device is placed into the DeviceComplete state, a device-specific capability file is needed to perform any software loading and configuration tasks.
Do not set DeviceComplete for unfinished devices or modular devices (Wi-Fi modules, development boards, and so forth) that may be used as part of a larger system; this state limits manufacturing activities such as production-line testing, software installation, and configuration. Many CLI commands are unavailable after DeviceComplete is set, but can be re-enabled by using a device capability, such as the fieldservicing capability.
When manufacturing is complete, use the following command to set the DeviceComplete state:
azsphere device manufacturing-state update --state <desired state> [--deviceip <ip> | --devicelocation <USB location>]
Moving a chip to the DeviceComplete state is a permanent operation and cannot be undone. Once a chip is in the DeviceComplete state, it cannot enter RF test mode, its e-fuse settings cannot be adjusted, Wi-Fi settings, operating system updates, and installed applications cannot be changed without enabling a device capability. If you need to re-enable these capabilities on an individual chip, such as in a failure analysis scenario, please contact Microsoft.