How to

Concept

A device that comes through the IoTConnect Device Provisioning Service, we call that an associated device. IoTConnect creates that device programmatically. These devices need further configuration to become operational.

Workflow Diagram

Before you start using it or bring it online, you must assign a template to these devices. Once the device gets the template, it is ready to send/receive messages to/from IoTConnect.

Pre-requisite

• Your device authentication type should be X.509 certificate or TPM.
• Your device shall auto provision/enroll using the Azure Device Provisioning service.
• You can get details like DPS Connection string, ScopeId, IoTHub hostname to provision/enroll device in DPS from the Key Vault page of your IoTConnect account.

• DPS Global device endpoint:
  • global.azure-devices-provisioning.net
• Enable Unassociated Device support.
  • Create a support ticket from your IoTConnect account to enable Azure Sphere & Unassociated device support.

For Sphere Device

• An Azure subscription
• Allowed connections: You can find this hostname in a key vault in the DSP Info tab, beside DPS Scope ID for sphere device.

How to create Unassociated Device

Before you start, you need to upload the root/intermediate X.509 Certificate in IoTConnect and verify. After that, onboard the device, connect and do all device communications.

How to upload and verify certificate in IoTConnect Portal?

• Login to your IoTConnect portal. Go to the Certificate section in device overview page

Setup CA certificate for sphere device

• Use the Azure Sphere developer command prompt to download your Azure Sphere Tenant CA certificate.
  • azsphere ca download -o -c <path\filename.cer>

• Upload your CA root/intermediate certificate for sphere by clicking on the CA CERTIFICATE button.

• To upload the sphere certificate, you need to check Azure Sphere Tenant CA Certificate checkbox

• On clicking the save button, your sphere certificate will be uploaded and added as the entry into the CA Certificate list. It will show origin as a DPS (Sphere CA) and now your certificate is ready to use for creating sphere devices with DPS

Note: Please set a calendar reminder ~6 Days before the certificate expiry date so that you can upload the new certificate.

• Sample: https://github.com/Avnet/azure-sphere-samples/tree/master/Samples/AvnetIoTConnectTemplate

Assign a template to the Unassociated device

• Once you have the device certificate ready, you can register the device in DPS in your firmware using that device certificate and DPS details.
• Before registering the device, Go to Devices > Unassociated Device section from menu or overview page

• Now, you can turn on your device which shall be registered with DPS. Once the device got registered successfully, you will receive one message on this screen to refresh the page

Note: After successfully finishing above stems still you don’t see your device in this list means you are not belongs to root entity. Its permission issue, in this case you have to connect your company admin to help you finish this process by assign template with valid CA certficate and give access of this device to you by changing the entity. Mean while your device will receive rc=”3″ response saying device not found

• Once you get a device in the list, you need to associate the template by clicking on the icon under the Action column. Select the appropriate template. Insert yes in the textbox for confirmation about your CA certificate and click the Associate button.

• After successful template association, device is ready to use. It will move from the Unassociated devices section to respective device section.

Get device identity.

Once Sphere Device get provisioned or connected to IoTHub; Device needs to send below is the JSON to get all required metadata information.

{
    "mt": 200,		// Message type
    "sid": "",		// Company SDK Identity
    "v": 2.0
}

On failure, you will receive the following JSON.

{
    "d": {
        "ec": 3, // Error code.

Refer table #1

        "ct": 200 // Command type
    }
}

On success, you will receive below JSON.

{
    "d": {
        "ec": 0,		//Error code. Ref
        "ct": 200,		//Command type same as message type
        "sid": "",		// Company SDK Identity
        "cpid": "",		//Device cpid
        "meta": {
            "g": "",		//Device guid
            "dtg": "",		//Device template guid
            "edge": 0,	        //1 – If device is Edge Device
            "gtw": "",	        //Represents tag, if its gateway device 
            "at": 1,		//Device authentication type. Ref
            "eg": "",		//Entityguid of device
            "df": 60,		//Device data frequency / message frequency.
            "hwv": "",	        // Device hardware version
            "swv": "",	        // Device software version
            "pf": 1		// Add cpid as prefix when required 
        },
        "has": {
            "d": 0,		//If 1 – Device needs to ask for child device by sending 204 message type
            "attr": 1,		//If 1 – Device needs to ask for attributes by sending 201 message type
            "set": 0,		//If 1 – Device needs to ask for settings/twins by sending 202 message type
            "r": 0,		//If 1 – Device needs to ask for rules by sending 203 message type
            "ota": 0		//If 1 – Device needs to ask for pending OTA by sending 205 message type
        }
    }
}

Sending Telemetry

Once the device got all required details, it can start sending telemetry to IoTConnect. It may vary based on the device type structure of telemetry. IoTConnect accepts various types of telemetry data from the device based on the device type defined in IoTConnect Portal.
Normal Device

{

    "sid": "",                         //sid from hello response
    "dtg": "",                         //dtg from hello response
    "mt": 0,		               //0 - Reporting telemetry
    "dt": "",                          //Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ
    "d": [{                            //Can have multiple value 
            "dt":””,                   //Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ
            "d": {

                "attrName1": "attVal", 	//String attribute
                "attrName2": 1, 	//NUMBER attribute
                "attrName3": {		//Object attribute
                    "attrName4": -240	//Number attribute
                }

            }

        }

    ]

}

Gateway Device

{
    "sid": "",                           //sid from hello response
    "dtg": "",                           //dtg from hello response
    "mt": 0,		                 //0 - Reporting telemetry
    "dt": "",                           //Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ
    "d": [{                             //Can have multiple value 
            "id”:””,                    //Parent/Child device unique id
            "tg”:””,                    //Tag of respective parent/child device
            "dt":””,                    //Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ
            "d": {

                "attrName1": "attVal", 	//String attribute
                "attrName2": 1, 	//NUMBER attribute
                "attrName3": {		//Object attribute
                    "attrName4": -240	//Number attribute
                }

            }

        }

    ]

}

Reference Tables