Microsoft Azure provides a rich set of integrated public cloud services for all your IoT solution needs. The IoT Hub Device Provisioning Service is a helper service for IoT Hub that enables zero-touch, just-in-time provisioning to the right IoT hub without requiring human intervention, enabling customers to provision millions of devices in a secure and scalable manner.
This project shows how to configure DevKit in order to make it automatically register to IoT Hub using the Device Provisioning Service. In this tutorial, you will learn how to:
- Set up the Device Provisioning Service configuration on the device
- Save Unique Device Secret on STSAFE security chip
- Generate X.509 certificate
- Create a device enrollment entry in the Device Provisioning Service
Before you begin
To complete the steps in this tutorial, you need the following:
- Prepare your DevKit with Getting Started Guide.
- Upgrade to latest firmware (>= 1.3.0) with Firmware Upgrading tutorial.
- Create and link IoT Hub with Device Provisioning Service instance with Set up auto provisioning.
Set up the Device Provisioning Service configuration on the device
To enable the DevKit to connect to the Device Provisiong Service instance you just created:
In the Azure portal, select the Overview blade for your Device Provisioning Service and note down the Global device endpoint and ID Scope value.
gitis installed on your machine and is added to the environment variables accessible to the command window. See Software Freedom Conservancy’s Git client tools to have the latest version installed.
- Open a command prompt. Clone the GitHub repo for DPS sample code:
git clone https://github.com/DevKitExamples/DevKitDPS.git
Launch VS Code and connect DevKit to computer, open the folder that contains the code you cloned.
Open DevKitDPS.ino, Find and replace
[Global Device Endpoint]and
[ID Scope]with the values you just note down. You can leave the registrationId as blank, the application will generate one for you based on the MAC address and firmware version. If you want to customized it, the Registration ID has to use alphanumeric, lowercase, and hyphen combinations only with maximum 128 characters long. See Manage device enrollments with Azure portal for more details.
Use Quick Open in VS Code (Windows:
Cmd+P) and type task device-upload to build and upload the code to the DevKit.
- Observe the success of the task in the output window.
Save Unique Device Secret on STSAFE security chip
Device Provisioning Service can be configured on device based on its Hardware Security Module (HSM). DevKit uses Device Identity Composition Engine (DICE) from the Trusted Computing Group (TCG). A Unique Device Secret (UDS) saved in STSAFE security chip on the DevKit is used to generate the device unique X.509 certificate. The certificate can be later used for the enrollment process in the Device Provisioning Service.
A typical Unique Device Secret (UDS) is a 64 characters long string. A sample UDS is as below:
Each of two characters are used as Hex value in the security calculation. So the above sample UDS is resolved to: “
To save Unique Device Secret on the DevKit:
Take the sample UDS string above and change one or many characters to other values between
f. This is used as your own UDS.
Open serial monitor by using tool like Putty, see Use Configuration Mode for details.
With the DevKit connected to computer, hold down button A, then push and release the reset button to enter configuration mode. The screen should show the DevKit id and ‘Configuration’.
Copy the sample UDS above. In serial monitor window, type set_dps_uds [your_own_uds_value] and press the Enter key to save it.
Without closing the serial monitor window, press reset button on the DevKit.
Note down DevKit MAC Address and DevKit Firmware Version value.
Generate X.509 certificate
- Open file explorer and go to the folder contain the DSP sample code you cloned, there is a .build folder, find and copy DPS.ino.bin and DPS.ino.map in it.
Note: If you have changed the
built.path configuration for Arduino to other folder. You need to find those files in the folder you configured.
Paste these two files into tools folder on the same level with .build folder.
Run dps_cert_gen.exe, follow the prompts to enter your UDS, MAC address for the DevKit and the firmware version to generate the X.509 certificate.
Observe the success of generation, a .pem certificate is saved in the same folder.
To be done.
Create a device enrollment entry in the Device Provisioning Service
In the Azure portal, navigate to your provisioning service. Click Manage enrollments, and select the Individual Enrollments tab.
In Mechanism, choose X.509.
In Certificate .pem or .cer file, upload the .pem certificate you just have.
Leave the rest as default and click Save.
Start the DevKit
Launch VS Code and open serial monitor.
Press the Reset button on your DevKit.
You should see the DevKit start the registration with your Device Provisioning Service.
Verify the DevKit is registered on IoT Hub
Once your device boots, the following actions should take place:
- The device sends a registration request to your Device Provisioning Service.
- The Device Provisioning Service sends back a registration challenge to which your device responds.
- On successful registration, the Device Provisioning Service sends the IoT hub URI, device ID and the encrypted key back to the device.
- The IoT Hub client application on the device then connects to your hub.
- On successful connection to the hub, you should see the device appear in the IoT hub’s Device Explorer.
Problems and feedback
If you encounter problems, you can find FAQs if you encounter problems or reach out to us from the channels below.
Was this documentation helpful?
Now that you have learned prepare the DevKit to enroll a device securely to DPS using DICE, so that it will automatically register to IoT Hub with zero-touch.
Advance to the other tutorials to learn: