8. References
- Amazon Sidewalk Manufacturing documentation:
docs.sidewalk.amazon/manufacturing/ - Amazon Sidewalk Protocol Specification, sections 4.1.2 (Certificate chain) and 4.3.2 (Sidewalk Manufacturing Serial Number (SMSN)) of that document
- Amazon Sidewalk Program Security Requirements:
docs.sidewalk.amazon/sidewalk-terms-and-agreements/security-program-requirements.html - AWS IoT Core Developer Guide, Bulk provisioning devices with AWS IoT Core for Amazon Sidewalk:
docs.aws.amazon.com/iot/latest/developerguide/sidewalk-bulk-provisioning.html - SDK interfaces:
sid_serial_registration.h,sid_serial_ifc.h,sid_on_dev_cert_cli.h - Amazon Sidewalk 360 portal:
360.sidewalk.amazon - Amazon Sidewalk SID API Developer Guide, Section 2.15 (Build configuration for factory-registered Endpoints and lite variants)
9. Appendix
9.1 Device states and registration lifecycle
device onboard performs four stages in one session on the host interface. The device is fully written before any call to the Amazon Sidewalk cloud.
- Manufacturing data. The device derives its SMSN and generates CSRs (ED25519 and P256R1). The CSRs are signed with the product DAK in the YubiHSM, and the resulting Sidewalk certificate chains are written back to the device.
- Control log. The SMSN, APID and Sidewalk certificate chains are submitted to the Amazon Sidewalk cloud.
- Provisioning. The wireless device record is created in AWS IoT Core for Amazon Sidewalk, identified by the SMSN.
- Registration. The encrypted registration handshake completes, and the device is factory-registered.
These stages map onto the Sidewalk device lifecycle described in the Amazon Sidewalk Manufacturing documentation: the control log stage reaches the device created state, the provisioning stage reaches the device associated with account state, and the registration stage reaches the device registered state. For a factory-registered device, the registered state is reached on the factory line rather than in the field.
In the field, the device performs field activation automatically on first contact with the network over BLE, FSK or LoRa, with no action from the end user. Field activation requires Amazon Sidewalk coverage at the deployment site. Never attempt mobile application or FFN registration on a factory-registered device.
9.2 Troubleshooting
The following table lists the most common failures that are not caused by the firmware. Firmware bring-up errors are described in Section 6.1.5.
| Symptom | Likely cause | Resolution |
|---|---|---|
LWA login denied: ... (lwa-invalid-parameter-bad-redirect-uri-vendor ...) | http://localhost:8000/ is not registered under Allowed Return URLs on the security profile | Add http://localhost:8000/ to Allowed Return URLs (Section 3.2) |
LWA login denied: ... invalid parameter : scope at the browser login, or LWA client_credentials returned 400: ... at the first control log upload | The security profile is not yet allow-listed for the named scope (Section 3.3) | Complete Section 3.3 with Amazon Sidewalk support, and wait for confirmation |
no LWA tokens cached on a device command | The browser login was skipped during configure, or the cached refresh token has expired | Run sid-mfg-tool configure again and complete the browser login (Chapter 4) |
/StartFactoryRegistration returned HTTP 403: '' (empty body), and the device was provisioned with a prototype device profile | ROW is not supported for prototype devices. A prototype device profile has no factory support or APID, so authorization always fails | Create a production device profile, complete factory support (Section 3.5), and provision devices against it |
/StartFactoryRegistration returned HTTP 403: '' (empty body) on the first attempt, with factory support already enabled | Your vendor or LWA application is not yet authorized for the APID of your product | Contact Amazon Sidewalk support to complete vendor onboarding (Section 3.3) before the factory run |
could not resolve AWS profile in configure | The named AWS CLI profile is missing or expired. The tool does not fall back to the default credential chain | Fix the profile in ~/.aws, then run aws sts get-caller-identity --profile <name> |
| HSM connector error or connection refused | yubihsm-connector is not running, or the connector URI in the configuration is wrong | Start the connector, run curl <connector>/connector/status, and check configure --show |
HSM authentication failed -- the PIN may be wrong. | Wrong DAK PIN | Run configure again and enter the DAK PIN from the HSM handoff |
failed to open HSM session: Can't find the Signer with <tag> | The configured product name does not match the product tag of the DAK in this HSM | Run configure again and enter the product tag from the HSM handoff |
SEGGER J-Link software not found | The tool drives the J-Link probe through the JLinkARM library of the SEGGER J-Link Software pack, which is not installed on the line PC | Install the J-Link Software and Documentation Pack in its standard location (Chapter 4) and run the command again |
J-Link with serial <N> is not connected (connected probes: ...) | --address does not match the serial number of an attached probe; the message lists the probes found | Use the serial number printed on the probe or development kit, and check its connection to the line PC |
cannot open J-Link <N>: ... | Another program owns the probe | Close J-Link RTT Viewer, J-Link Commander, RTT Logger and Simplicity Studio; a probe serves one host program at a time |
transport 'rtt' needs jlink_device | The tool is run with --transport rtt or with rtt as the default transport, but no J-Link device name is configured | Run configure again, choose transport rtt and enter the J-Link device name of the MCU |
RTT control block not found within 5.0s | The device is not powered or not running, the image is not an RTT image of the Factory Diagnostic Firmware, or jlink_device names a different MCU | Power-cycle the device, confirm the flashed image, and check jlink_device with configure --show |
10 Change History
| Version | Summary of Changes |
|---|---|
| Protocol Stack 1.0, Document Revision A | First release of the Registration over Wire Application Note. Supersedes the sid-mfg-tool ROW Customer Onboarding Guide. |
Glossary
| Term | Definition |
|---|---|
| Amazon FFS | Amazon Frustration-Free Setup: the Amazon program whose developer console hosts control log onboarding. Distinct from Sidewalk FFS, the registration path over FSK (Section 6.2) |
| APID | Advertised Product ID: 4-character alphanumeric product identifier, linked to the device profile by Amazon as part of factory support |
| BLE | Bluetooth Low Energy (Bluetooth LE); Sidewalk link type 1 |
| CM | Contract Manufacturer |
| Control log | Manufacturing record (SMSN, APID and Sidewalk certificate chains) ingested by the Amazon Sidewalk cloud |
| DAK | Device Attestation Key: certificate authority key for a device type, stored in the YubiHSM for production devices |
| DeviceTypeId | Device type identifier vended by Amazon together with the HSM; an input to the SMSN |
| DSN | Device Serial Number: unique per-device serial number assigned by the device maker |
| DUT | Device Under Test: the device connected to the line PC during manufacturing |
| Factory Diagnostic Firmware | Firmware flashed on the device during manufacturing that generates the device key pairs and CSRs and, for ROW, runs serial registration |
| Factory registration | Registration of a device on the factory line using ROW, before shipment |
| Factory support | Configuration of a device profile by Amazon for production (APID linkage and production DAK provisioning) |
| FFN | Frustration-Free Networking: touchless in-field registration |
| Field activation | Automatic activation of a factory-registered device on its first contact with the Amazon Sidewalk network, with no end user action |
| FSK | Sub-GHz frequency-shift keying (SubG-FSK), synchronous mode; Sidewalk link type 2 |
| HSM | Hardware Security Module (YubiHSM 2) holding the production DAK |
| J-Link | SEGGER debug probe through which the line PC reaches the MCU over the debug port; built into many development kits, or used as an external unit. ROW uses it for the RTT host interface |
| KV store | Device non-volatile storage for Sidewalk runtime state; at security-level-high, the only copy of the registration credentials |
| Line PC | Computer on the factory line that runs sid-mfg-tool and connects to the DUT |
| LoRa | Sub-GHz chirp spread spectrum (SubG-CSS), asynchronous mode; Sidewalk link type 3 |
| LWA | Login with Amazon: OAuth 2.0 authentication used by sid-mfg-tool |
| Manufacturing page | Non-volatile region holding the factory identity; at security-level-low, also a copy of the registration credentials |
| Product tag | Label identifying the DAK in the HSM (for example RNET_DAK_<PROJECT>), provided by Amazon with the DAK PIN |
| ROW | Registration over Wire |
| RTT | SEGGER Real-Time Transfer: byte channels between the MCU and a J-Link probe, read and written through the debug port. ROW uses channel 0 as the alternative to UART |
| SDK variant | Full (multi-link, sid_api.c) or lite (single link, sid_api_ble.c, sid_api_fsk.c or sid_api_lora.c) build of the Sidewalk SDK |
| Security level | security-level-high or security-level-low: determines where registration credentials are stored and how factory reset behaves; must match the SDK variant |
| SMSN | Sidewalk Manufacturing Serial Number: unique 32-byte device identifier |