Device connectivity in Azure IoT Central

This article introduces key concepts relating to device connectivity in Microsoft Azure IoT Central.

Azure IoT Central uses Azure IoT Hub Device Provisioning service (DPS), enabling IoT Central to support onboarding & connecting of devices at scale.

  • Customers can now generate device credentials and configure the devices offline without having to first register the devices in IoT Central
  • IoT Central supports device connection with industry recommended X509 cert- based connectivity, while continuing to support and improve Shared Access Signatures (SAS) connectivity
  • IoT Central customers can now bring their own Device Ids to register devices in IoT Central, enabling simple integration with existing back-office systems
  • There is one consistent way to connect devices to IoT Central

Note

IoT Central uses Azure IoT Device Provisioning service (DPS) underneath for all device registration and connection, learn more about DPS.

Based on your use case follow the instructions to connect devices to IoT Central

  1. Connect a single device quickly (using Shared Access Signatures)
  2. Connect devices at scale using Shared Access Signatures (SAS)
  3. Connect devices at scale using X509 certificates recommended for production workloads
  4. Connect without first registering devices

Note

Here is the global end point for devices to connect and provision global.azure-devices-provisioning.net.

Connect a single device

Connecting a single device to IoT Central using SAS is easy and takes only a few steps

  1. Add a real device from Device Explorer, click on +New > Real to add a real device.
    • Enter the Device Id (should be lower case) or use the suggested Device Id.
    • Enter the Device Name or use the suggested name
      Add Device
  2. Get connection details such as Scope ID, Device ID, and Primary key for the added device by clicking Connect on the device page.
    • Scope ID is per IoT Central App and is generated by DPS, used to ensure unique device ID within an App.
    • Device Id is the unique device ID per App, the device needs to send Device Id as part of the registration call.
    • Primary Key is a SAS token, generated by IoT Central for this specific device. Connection details
  3. Use these connection details Device Identity, Device Name, and the Device Primary Key in your device code to provision and connect your device and start seeing the data flow through instantaneously. If you are using the MxChip device follow, the step-by-step instructions here, start from the section Prepare the DevKit device.

    Below are the references for other languages you might want to use.

    • C language: If you are using C, follow this C sample device client to connect a sample device. Use the following settings in the sample.

      hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
      
      static const char* const SYMMETRIC_KEY_VALUE = "Enter Primary Symmetric key here";
      
      static const char* const REGISTRATION_NAME = "Enter Device Id here";
      
    • Node.js: If you want to use Node.js use the step-by-step instructions here, start from the section Prepare the client code.

Connect devices at scale using Shared Access Signatures

To connect devices at scale with IoT Central using SAS, there are two steps involved

  1. Register devices by importing them into IoT Central via a CSV file and export devices with device connection details to use to connect your devices
  2. Device setup The device is programmed with the connection details ( Scope ID, Device ID, and Primary key), enabling it to call the provisioning service to get its connection info/IoT Central app assignment when it is switched on.

Note

An advanced option is also available where you can connect devices without having to first register devices in IoT Central, learn more here.

Register devices

To connect large number of devices to your application, Azure IoT Central offers bulk importing devices via a CSV file.

CSV file requirements: The CSV file should have the following columns (and headers)

  1. IOTC_DeviceID (should be lower case)
  2. IOTC_DeviceName (Optional)

Import devices to register them in your application

  1. Choose Explorer on the left navigation menu.
  2. On the left panel, choose the device template for which you want to bulk create the devices.
  3. Click Import, select the CSV file that has the list of Device IDs to be imported. The CSV file should have the following columns (and headers)
    • IOTC_DeviceID (should be lower case)
    • IOTC_DeviceName (Optional)
  4. Once the import completes, a success message is shown on the device grid.

Export devices to get the connection details, Export creates a CSV file with Device Id, Device Name, and the Device Key. Use these details to connect the device to IoT Central. To bulk export devices from your application:

  1. Choose Explorer on the left navigation menu.
  2. Select the devices that you want to export and then click the Export action.
  3. Once the export completes, a success message is shown along with a link to download the generated file.
  4. Click on the success message to download the file to a local folder on the disk.
  5. The exported CSV file will have the following columns information: Device Id, Device Name, Device Primary/Secondary Keys, and Primary/Secondary certificate thumbprints
    • IOTC_DEVICEID
    • IOTC_DEVICENAME
    • IOTC_SASKEY_PRIMARY
    • IOTC_SASKEY_SECONDARY
    • IOTC_X509THUMBPRINT_PRIMARY
    • IOTC_X509THUMBPRINT_SECONDARY

Device setup

Use these connection details, Device Identity (IOTC_DEVICEID), Device Primary Key( IOTC_SASKEY_PRIMARY), and Scope ID in your device code to provision and connect your device. If you have not already, get the Scope Id from your IoT Central App Administration > Device Connection > Scope ID. If you are using the MxChip device to connect follow the step-by-step instructions here, start from the section Prepare the DevKit device.

Below are the references for other languages you might want to use.

  • C language: If you are using C follow this C sample device client to connect a sample device. Use the following settings in the sample.

    hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;
    
    static const char* const SYMMETRIC_KEY_VALUE = "Enter Primary Symmetric key here";
    static const char* const REGISTRATION_NAME = "Enter Device Id here";
    

Connect devices using X509 certificates

Using X.509 certificates as an attestation mechanism is an excellent way to scale production and simplify device provisioning. X.509 certificates are typically arranged in a certificate chain of trust in which each certificate in the chain is signed by the private key of the next higher certificate, and so on, terminating in a self-signed root certificate. This establishes a delegated chain of trust from the root certificate generated by a trusted root certificate authority (CA) down through each intermediate CA to the end-entity "leaf" certificate installed on a device. To learn more, see Device Authentication using X.509 CA Certificates.

To connect devices to IoT Central using X509 certificates, there are three key steps involved

  1. Configure the connection settings in IoT Central app by adding/verifying the X509 root/intermediate certificate used to generate the device certificates. There are two steps to configure connection settings for X509 Certificates.

    • Add X509 root or intermediate certificate you are using to generate the leaf device certificates. Go to Administration > Device Connection > Certificates.

      Connection settings

    • Certificate verification: Verifying certificate ownership ensures that the uploader of the certificate is in possession of the certificate's private key. To verify the certificate

      • Generate Verification code, click the button next to the Verification code field to generate the verification code.
      • Create an X.509 verification certificate with the verification code, save the certificate as a .cer file.
      • Upload the signed verification certificate and click verify.

      Connection settings

    • Secondary Certificate: During the lifecycle of your IoT solution, you'll need to roll certificates. Two of the main reasons for rolling certificates would be a security breach, and certificate expirations. Secondary certificates are used to reduce downtime for devices attempting to provision while you are updating the Primary certificate.

      FOR TESTING PURPOSES ONLY

      Below are some utility commandline tools you can use to generate CA certs and device certs.

    • If you are using MxChip here is a commandline tool to generate CA certs add it to your IoT Central app and verify the certificates.

    • Use this commandline tool to

      • Create the certificate chain (follow Step 2 in the GitHub docs). Save the certs as .cer files and upload to IoT Central (Primary).
      • Get the Verification Code from the IoT Central App, generate the certificate (follow Step 3 in the GitHub docs), and upload to verify.
      • Create leaf certs with your device Id as a parameter to the tool(follow Step 4). Save the cert and use it on your device.
  2. Register devices by importing them into IoT Central via a CSV file.

  3. Device setup : Generate the leaf certificates using the uploaded root certificate. Make sure you use the Device ID as the CNAME in the leaf certificates and is in lower case. Here is a commandline tool to generate leaf/device certs for TESTING PURPOSES ONLY.

    Program the device with provisioning service information enabling it to get its connection details and IoT Central app assignment when switched on.

    Further referene

Note

Use the Device ID as a cname when generating the leaf certificates for devices.

Note

The Device ID should be lower case

Connect without first registering devices

One of the key scenarios IoT Central enables is for OEMs to mass manufacture devices, generate credentials and configure them in the factory without having to first register them in IoT Central. Once the devices are turned on and connect to IoT Central the operator approves the device to connect to the IoT Central app.

Below is the flow to connect devices with this feature

Connection settings

Follow the steps based on your choice of device authentication scheme (X509/SAS)

  1. Connection settings

    • X509 Certificates: Add and verify the root/intermediate certificate and use it to generate the device certificates in the next step.
    • SAS: Copy the Primary key( this key is the group SAS key for this IoT Central application) and use it to generate the device SAS keys in the next step. Connection settings SAS
  2. Generate device credentials

    • Certificates X509: Generate the leaf-certificates for your devices using the root/intermediate certificate you have added to this app. Make sure you use the Device ID as a cname in the leaf certificates and (should be lower case). Here is a commandline tool to generate leaf/device certs for testing.
    • SAS Device SAS keys can be generated using this command line tool. Use the Primary SAS key (group SAS key) from the previous step. Make sure the Device ID is in lower case.

      Use the below instructions to generate device SAS key

      npm i -g dps-keygen
      

      Usage

      dps-keygen <Primary_Key(GroupSAS)> <device_id>
      
  3. Device setup

    Flash the device with Scope ID, Device ID, Device cert/SAS key and then turn on the device to connect to IoT Central app.

  4. Connect device to IoT Central: Once switched on the devices connect to DPS/IoT Central for registration.

  5. Associate Device to a template: The connected device will show up under UnAssociated Devices in Device Explorer. The device provisioning status is Registered. Associate the device to the appropriate device template and approve the device to connect to the IoT Central app. The device gets the conection details for the IoT Central app, it connects and starts sending data. Device provioning is now complete and the Provisioning status turns to Provisioned.

Device Provisioning status

There are a series of steps involved when a real device is connected to Azure IoT Central

  1. Registered: The device is first Registered, meaning the device is created in IoT Central, and has the Device ID for the device. Device is Registeretd when

    • A new real device is added on Explorer
    • A set of device is added using Import on Explorer
    • A device that has not been registered but connects with valid credentials and is visible under Un-Associated devices.

      In all of the above cases the Provisioning status is Registered

  2. Provisioned: The next step is when the device connects with valid credentials IoT Central completes the provisioning step (by creating the device in IoT Hub). It then returns the connection string to the device to connect and start sending data. The device Provisioning status now turns from Registered to Provisioned.

  3. Blocked: The operator can block a device, once a device is blocked it cannot send data to IoT Central and will have to be reset. Devices that are blocked have the Provisioning status of Blocked. The operator can also unblock the device. Once unblocked the device Provisioning status return to its previous Provisioning status (Registered or Provisioned).

Getting device connection string

You can get Iot hub device connection string to Azure IoT Hub using the following steps

  1. Get connection details such as Scope ID, Device ID, Device Primary key from the device page (got to the device page > click Connect )

    Connection details

  2. Get the device connection string using the commnd line tool below. Use the below instructions to get the device connection string

    npm i -g dps-keygen
    

    Usage

    In order to create a connection string, find the binary under bin/ folder

    dps_cstr <scope_id> <device_id> <Primary Key(for device)>
    

    Learn more about the dps-keygen tool here.

SDK support

The Azure Device SDKs offer the easiest way for you implement the code on your devices that connects to your Azure IoT Central application. The following device SDKs are available:

Each device connects using a unique connection string that identifies the device. A device can only connect to the IoT hub where it is registered. When you create a real device in your Azure IoT Central application, the application generates a connection string for you to use.

SDK features and IoT Hub connectivity

All device communication with IoT Hub uses the following IoT Hub connectivity options:

The following table summarizes how Azure IoT Central device features map on to IoT Hub features:

Azure IoT Central Azure IoT Hub
Measurement: Telemetry Device-to-cloud messaging
Device properties Device twin reported properties
Settings Device twin desired and reported properties

To learn more about using the Device SDKs, see one of the following articles for example code:

Protocols

The Device SDKs support the following network protocols for connecting to an IoT hub:

  • MQTT
  • AMQP
  • HTTPS

For information about these difference protocols and guidance on choosing one, see Choose a communication protocol.

If your device can't use any of the supported protocols, you can use Azure IoT Edge to do protocol conversion. IoT Edge supports other intelligence-on-the-edge scenarios to offload processing to the edge from the Azure IoT Central application.

Security

All data exchanged between devices and your Azure IoT Central is encrypted. IoT Hub authenticates every request from a device that connects to any of the device-facing IoT Hub endpoints. To avoid exchanging credentials over the wire, a device uses signed tokens to authenticate. For more information, see, Control access to IoT Hub.

Note

Currently, devices that connect to Azure IoT Central must use SAS tokens. X.509 certificates are not supported for devices that connect to Azure IoT Central.

Next steps

Now that you have learned about device connectivity in Azure IoT Central, here are the suggested next steps: