Factory-floor tasks
Important
This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.
Manufacturing connected devices that incorporate Azure Sphere hardware involves the following factory-floor tasks to prepare devices for shipping:
- Connecting each Azure Sphere chip to a factory-floor PC
- Getting device details and recording them for later use
- Updating the Azure Sphere OS, if necessary
- Update the trusted keystore, if necessary
- Loading software onto the device
- Running functional tests to verify the product's correct operation
- Performing radio frequency (RF) testing and calibration
- Verifying Wi-Fi communication
- Configuring the device for Ethernet
- Finalizing the Azure Sphere device for shipping
You must connect the chip to the PC first, get device details second, and finalize the device last, but you can perform the other tasks in any order that suits your manufacturing environment.
Important
You should do some preparation to help ensure that your factory-floor tasks can be completed without delays. Preparation includes setting up the factory-floor PC and any other necessary equipment and installing the necessary PC software tools. All of the tasks you should do to prepare for a smooth manufacturing process are described in Manufacturing process preparation.
Connect each Azure Sphere chip to a factory-floor PC
During manufacturing, you must connect each Azure Sphere chip to a factory-floor PC. If you want to simultaneously connect multiple Azure Sphere devices to a single PC, see Equipment for factory-floor tasks in the manufacturing preparation tasks.
Most factory-floor tasks involve the azsphere device command. When you have multiple devices attached to the PC, you must specify the device on which to apply the azsphere device command by including the --device parameter set to either the device's IP address or the device's connection path. The command will fail if the --device parameter is omitted and multiple devices are attached. To get the IP address or connection path, see Get device details.
Important
The Azure Sphere 23.05 SDK release and later releases support communication with multiple attached devices on Windows and Linux.
Get device details
You must record the device ID of each Azure Sphere chip that your company incorporates into manufactured products. You will need the device ID for cloud-configuration tasks.
If you have multiple devices attached to the factory-floor PC, you must also record the IP address or connection path of attached devices for later use in factory-floor tasks. As explained in Connect each Azure Sphere chip, IP address or connection path is required to specify the target device when there are multiple attached devices.
To get the device ID, IP address, and connection path of the attached devices, use the azsphere device list-attached command. The following descriptions provide essential details about the device ID, IP address, and connection path.
Device ID — The silicon manufacturer creates the device ID, stores it on the chip, and registers it with Microsoft. This device registration ensures that Microsoft is aware of all Azure Sphere chips and that only legitimate chips can be used in connected devices.
IP address — 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 FTDI-based device interface to be attached is assigned the address 192.168.35.2. 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.
Connection path — The connection path is an FTDI location ID that identifies the USB connection. The location ID 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.
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 update the OS by installing specific recovery images, which should already be present on your PC. See Prepare for an update of the OS in the manufacturing preparation tasks. The Manufacturing Samples include an example script that performs parallel multi-device recovery.
You can update the OS on the Azure Sphere device by issuing the azsphere device recover command. Use the --images parameter to install specific recovery images:
azsphere device recover --images <path-to-images> [--device <IP-address or connection-path>]
Note
If multiple devices are connected to the PC, include the --device parameter to identify the target device by IP address or connection path. See Connect each Azure Sphere chip to a factory-floor PC for details.
Update the trusted keystore
As a prerequisite to loading software onto your device, you may need to update the trusted keystore on the device. This is required only if the OS on the device is older than your software, and only if the Azure Sphere image signing key used by AS3 was updated between the OS being published and your software being production-signed. To avoid this step and reduce manufacturing time, consider updating the OS version you are using during manufacture.
You can easily determine if updating the trusted keystore is required by attempting to load your software according to the instructions in the next section. If loading succeeds you do not need to update the trusted keystore. If loading fails with the message starting with Internal device error: Image not trusted by device then an out-of-date trusted keystore is the cause.
To update the trusted keystore, you need to have acquired the up-to-date trusted keystore file. Then, as part of your manufacturing scripts, use the azsphere device sideload deploy command to load the updated trusted keystore prior to loading application software, replacing <path-to-trusted-keystore.bin> with the path to of the trusted keystore file:
azsphere device sideload deploy --image-package <path-to-trusted-keystore.bin> [--device <IP-address or connection-path>]
Load device software
All software that you load—regardless of whether it is a board configuration image, a testing application, or a production application—must be production-signed. If you load a temporary application for testing, you must delete it after testing is complete.
All production-signed images that you need during the factory-floor process should be saved on your factory-floor PC prior to beginning the process, as described in Get production-signed images in the manufacturing preparation tasks.
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.
To load software onto a device in the factory or to delete temporary software from a device after testing is complete, use the azsphere device sideload command as follows:
Use azsphere device sideload deploy to load an image, replacing
<file-path>with the name and path to your production-signed image file:azsphere device sideload deploy --image-package <file-path> [--device <IP-address or connection-path>]
Use azsphere device sideload delete to delete a temporary image, replacing
<component-id>with the component ID of the image to be deleted:azsphere device sideload delete --component-id <component-id> [--device <IP-address or connection-path>]
Note
If multiple devices are connected to the PC, include the --device parameter to identify the target device by IP address or connection path. See Connect each Azure Sphere chip to a factory-floor PC for details.
Run functional tests
Functional tests are necessary to verify that the product operates correctly. Run the applications that you developed for functional testing as part of of the manufacturing preparation tasks. See Develop applications for functional testing.
If your functional tests require communication with the chip that is being tested, connect the MT3620 peripheral UARTs (ISU0, ISU1, ISU2, or ISU3) to either your factory-floor PC or external test equipment via suitable circuitry of your own design.
Perform radio frequency (RF) testing and calibration
Azure Sphere chips may use Wi-Fi to receive software updates and communicate with the internet. If your product uses Wi-Fi and it incorporates either a chip-down design or a module that is not RF-certified, you must perform RF testing and calibration for each device. The equipment and tools needed for this task are described in Equipment and software for RF testing and calibration in the manufacturing preparation tasks.
The RF Tools package includes utilities and a C API library for use during testing. You can use the C API library to program product-specific RF settings in e-fuses. For example, e-fuses are programmed to configure the antenna and frequency, to tune devices for optimal performance, and to enable Wi-Fi channels. The RF testing tools topic describes how to use the RF tools.
Program e-fuses to enable Wi-Fi channels
The Azure Sphere OS selects Wi-Fi channels based on the region code that is programmed into the MT3620 e-fuses at offset addresses 0x36 and 0x37. For details about e-fuses on the MT3620, see the MT3620 E-fuse Content Guidelines Mediatek document.
The region code is a two-letter ASCII code. The Azure Sphere OS uses the region code setting in the e-fuses to look up the region in the Linux wireless regulatory database and then selects the channels allowed for that region. If no region code is programmed into the e-fuses, in which case the e-fuses remain set to 0x00 0x00, or if the characters "00" are programmed, the OS defaults to a conservative set of channels that are generally allowed in all regions. The channels allowed for region "00" are specified in the Linux wireless regulatory database.
The region code setting in the e-fuses does not need to match the country where the device will be used. Manufacturers can choose any region code that maps to an allowed set of channels for the region of operation. Different regions and countries often adopt similar or identical regulations, which can allow region codes to be used interchangeably.
Example: To instruct the Azure Sphere OS to select Wi-Fi channels for region "DE" (Germany), program 0x44=D and 0x45=E into the e-fuses at addresses 0x36 and 0x37. The allowed channels for Germany, excerpted from the Linux wireless regulatory database, are shown below. Most countries in the European Union (EU) allow the same set of channels.
country DE: DFS-ETSI
(2400 - 2483.5 @ 40), (100 mW)
(5150 - 5250 @ 80), (200 mW), NO-OUTDOOR, AUTO-BW, wmmrule=ETSI
(5250 - 5350 @ 80), (100 mW), NO-OUTDOOR, DFS, AUTO-BW, wmmrule=ETSI
(5470 - 5725 @ 160), (500 mW), DFS, wmmrule=ETSI
# short range devices (ETSI EN 300 440-1)
(5725 - 5875 @ 80), (25 mW)
# 60 GHz band channels 1-4 (ETSI EN 302 567)
(57000 - 66000 @ 2160), (40)
Verify RF configuration
Use the RfSettingsTool to verify that the radio configuration options such as target transmit power, region code, and Wi-Fi Media Access Control (MAC) address have been correctly set. The RF settings tool documentation provides more information about using this tool.
Verify Wi-Fi communication
Consider connecting to a Wi-Fi access point to verify that your product application is able to communicate over Wi-Fi. Ensure that the Wi-Fi connection does not have internet access, because an over-the-air update may occur if the chip connects to an internet-enabled access point.
To connect a device to a Wi-Fi access point, follow the instructions in the Quickstart (CLI tab). If multiple devices are connected to the PC, you must include the --device parameter in the azsphere device wifi show-status command and the azsphere device wifi add command. For details about using the azsphere device command with multiple attached devices, see Connect each Azure Sphere chip to a factory-floor PC.
After Wi-Fi testing, you should remove any Wi-Fi access points used for testing from the chip so that these are not visible to customers. Device recovery removes all Wi-Fi configuration data from the chip.
Configure the device for Ethernet
An Azure Sphere device can communicate over Ethernet. The device requires an external Ethernet adapter and a board-configuration image for communication through Ethernet.
To configure an Azure Sphere device for Ethernet, connect an Ethernet adapter to the Azure Sphere device, as described in Connecting Ethernet adapters.
Two Ethernet devices are supported by the Azure Sphere Operating System.
- Microchip ENC28J60. This is a 10Base-T (10mbps) adapter. It can be wired with an LED indicator at half-duplex speed, or without an LED indicator at full-duplex speed. Seeed devkits are wired for half-duplex operation.
- Wiznet W5500. This is a 100Base-TX (100mpbs) adaptor. It supports an integrated TCP/IP stack and NIC pass-through modes, but Azure Sphere only supports NIC pass-through when using the W5500 for internet connectivity. Due to bus bandwidth limitations, full 100mbps speed may not be achievable by the MT3620 device.
The Ethernet interface will be enabled automatically once the board configuration is loaded, as described in Load device software, and the device is rebooted. All interfaces use dynamic IP addresses by default.
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 ready-to-ship checks
It is important to run ready-to-ship checks before you ship a product that includes an Azure Sphere device. Different checks must be performed for different manufacturing states. Ready-to-ship checks ensure the following:
- The device manufacturing state is set correctly for that stage of manufacturing.
- The Azure Sphere OS on the device is valid and the expected version. This can only be checked for devices that are not yet in the DeviceComplete state.
- User-supplied images on the device match the list of expected images. This can only be checked for devices that are not yet in the DeviceComplete state.
- No unexpected Wi-Fi networks are configured on the device. This can only be checked for devices that are not yet in the DeviceComplete state.
- The device does not contain any special capability certificates. For MT3620-based devices, this can only be checked on devices not in the Blank state.
Different checks are necessary at different stages of manufacturing because the manufacturing state of the device determines the capabilities of the device.
Which checks you run will also depend on whether you are designing a module or 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.
Use device_ready.py to perform checks
The Manufacturing Samples package includes a tool called device_ready.py, which performs the above checks, as appropriate for each manufacturing state. It should be run for each of the manufacturing states relevant to your device.
The following table lists the parameters that the device_ready.py script takes:
| Parameter | Description |
|---|---|
--expected_mfg_state |
Determines which manufacturing state to check for and controls which tests are run. If this parameter is not specified, it defaults to "DeviceComplete". If the manufacturing state of the device differs from this value, the check fails. |
--images |
Specifies the list of image IDs (GUIDs) that must be present on the device for the check to succeed. The list consists of the image GUIDs separated by spaces. This parameter defaults to the empty list if not specified. If the list of installed image IDs on the device 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. |
--os |
Specifies a list of versions of the Azure Sphere OS. This parameter defaults to the empty list if not supplied. If the OS version present on the device is not in this list, this check fails. |
--os_components_json_file |
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. Use the download_os_list.py tool to download the latest version. |
--azsphere_path |
Specifies the path to the azsphere.exe utility. If not specified, this parameter defaults to the default install location for the Azure Sphere SDK on Windows. Use this parameter only if the Azure Sphere SDK is not installed in the default location. |
--help |
Shows command-line help. |
--verbose |
Provides additional output detail. |
Following example is a sample run of the device_ready.py tool with the following arguments:
--os 22.07--os_components_json_file mt3620an.json--expected_mfg_state Module1Complete
device_ready.py --os 22.07 --os_components_json_file mt3620an.json --expected_mfg_state Module1Complete
Checking device is in manufacturing state Module1Complete...
PASS: Device manufacturing state is Module1Complete
Checking capabilities...
PASS: No capabilities on device
Checking OS version...
PASS: OS '22.07' is an expected version
Checking installed images...
PASS: Installed images matches expected images
Checking wifi networks...
PASS: Device has no wifi networks configured
------------------
PASS
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.
The three manufacturing states are as follows:
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 Module1Complete state protects the device against changes that may disrupt proper operation of the radio and other wireless devices in the vicinity.
DeviceComplete. The DeviceComplete 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 must be used whenever performing any software loading and configuration tasks. The fieldservicing capability allows you to sideload production-signed images, but not delete them. The appdevelopment capability allows both sideloading and deleting images.
Do not set DeviceComplete for unfinished devices or modules (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 and so certain ready-to-ship checks must be run before this state is set. Restricted commands can be re-enabled using a device capability such as the fieldservicing capability, but only for devices you have claimed, and therefore this is not appropriate for use in a factory-floor environment as it requires cloud connectivity.
The following table summarizes the device capabilities that are present for each manufacturing state.
| Manufacturing state | Device capabilities |
|---|---|
| Blank | enableRfTestMode, fieldServicing, and those that are either sideloaded or passed with an operation, as described in Device capabilities. |
| Module1Complete | fieldServicing and those that are either sideloaded or passed with an operation, as described in Device capabilities. |
| DeviceComplete | Only those that are either sideloaded or passed with an operation, as described in Device capabilities. |
When manufacturing is complete, use the azsphere device manufacturing-state update command to set the DeviceComplete state:
azsphere device manufacturing-state update --state <desired-state> [--device <IP-address or connection-path>]
Note
If multiple devices are connected to the PC, include the --device parameter to identify the target device by IP address or connection path. See Connect each Azure Sphere chip to a factory-floor PC for details.
Important
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; and Wi-Fi settings, operating system updates, and installed applications cannot be changed without claiming the device and using a device capability. If you need to re-enable functions on an individual chip that device capabilities do not re-enable, such as in a failure analysis scenario, contact Microsoft.