Skip to main content

Send telemetry to Azure IoT Hub

In this example we create an application where we send telemetry data from our camera up to Azure IoT Hub. Telemetry data from the camera could be motion detection events or custom events from ACAP applications installed on the camera.

architecture

The application consists of the following Azure resources.

An Axis camera has an internal MQTT client that will connect to the IoT Hub in Azure. The camera authenticates to the IoT Hub using a X.509 certificate.

Prerequisites​

  • A network camera from Axis Communications (example has been verified to work on a camera with firmware >=10.4)

No command-line interface is needed even though command listings are present in the example. See command-line interface reference for syntax used in command listings.

Instructions​

The instructions are divided into two parts. The first part covers deploying the Azure resources and the second part covers configuring the camera.

Deploy Azure resources​

info

The generated X.509 certificates are valid for 365 days, which means that a solution deployed with these certificates will be operational for about a year. To remain operational longer that that, update the script to generate certificates with a longer validity, or re-provision the solution after a year when the certificates have expired.

The generated X.509 certificates are self-signed. To root the certificates in a trusted root Certificate Authority (CA), please contact a trusted commercial certificate authority like Baltimore, Verisign, or DigiCert.

Let's deploy the Azure resources required to receive telemetry from a camera. Navigate to the Microsoft Azure portal by right-clicking the button below and open the link in a new tab.

Deploy to Azure

The template will require the following custom parameters.

  • Object ID - The object ID of your Azure Active Directory user. The object ID can be found either by navigating to your user in Azure Active Directory, or by running the following command in the Azure Cloud Shell: az ad signed-in-user show --query id --output tsv.
  • Organization name - The name of your organization, used when generating the X.509 certificates.
  • IoT Hub name prefix - The prefix of the IoT Hub name. A generated hash will be appended to the name, guaranteeing its uniqueness on Azure. Default value is axis-telemetry.
  • Device identity - The name of the IoT device, used for authentication and access control. Default value is device01.
  • Location - The location to deploy all resources in. Default value tells Azure to deploy resources to the location of the resource group.

Once the deployment is complete, navigate to the Outputs tab and take note of the values with name host, username and clientId. We will use these values in the next chapter when we configure the camera.

Outputs

Configure the camera​

Now that the resources in Azure are ready to accept telemetry, let's continue with configuring the camera to send events.

We will begin by downloading the device certificate from Azure Key Vault.

  1. In Microsoft Azure portal, navigate to your newly created resource group
  2. Select your Key Vault instance
  3. Select Certificates under Objects in the left pane of your Key Vault instance
  4. Click the device certificate
  5. Click on the current version of the certificate
  6. Download the certificate by clicking the Download in PFX/PEM format toolbar button

With the device certificate downloaded to your computer, we're ready to configure the Axis camera. Start by navigating to the camera using your preferred web browser. To add a device certificate, follow the steps below.

  1. In the user interface of the camera, select System -> Security
  2. Above the list of Certificates, click on Add certificate to add a new certificate
  3. Select Upload a client-server certificate using a private key (PKCS#12) and click on Next
  4. Upload your downloaded device certificate and click on Next
  5. Click on Install
  6. Click on Close

The next step is to configure the MQTT client on the camera.

  1. In the user interface of the camera, select System -> MQTT
  2. In the MQTT client section use the following settings
    • Host: <iot hub name>.azure-devices.net, i.e. the host output value from the Azure deployment
    • Protocol: MQTT over WebSocket Secure
    • Port: 443
    • Basepath: $iothub/websocket
    • Username: <iot hub name>.azure-devices.net/<device identity>/?api-version=2018-06-30, i.e. the username output value from the Azure deployment
    • Client certificate: <device certificate>, i.e. the device certificate we just uploaded to the camera
    • CA certificate: DigiCert Global Root G2
    • Validate server certificate: checked
      • Host: <aws iot core host>, i.e. the host echoed in the final step of the previous chapter: <device identity>, i.e. the clientId output value from the Azure deployment
  3. Click Save

Once the settings are saved, click on Connect on the top of the MQTT settings page.

Let's continue with configuring the event type we wish to send to the Azure IoT Hub. For the sake of simplicity we create a new schedule that triggers an event every 5 seconds, because the event is predictable and doesn't require any physical access to the camera. You can change this event to any type sent by the camera or an installed ACAP application.

  1. In the user interface of the camera, select System -> Events -> Schedules
  2. Add a new schedule with the following settings
    • Name: Every 5 seconds
    • Type: Pulse
    • Repeat every: 5 Seconds
  3. Click Save

Finally select pulses to be the event type the camera sends to the Azure IoT Hub.

  1. Return to System -> MQTT
  2. Scroll down to the MQTT publication section and enter following settings
    • Use default topic prefix: unchecked
    • Topic prefix: devices/<device identity>/messages/events/, e.g. devices/device01/messages/events/
    • Include condition: unchecked
    • Include serial number: checked
  3. Click on Save
  4. Click Add condition and enter the following settings
    • Condition: Pulse
  5. Click on Add

At this point the camera is sending a new event every 5 seconds to the Azure IoT Hub. You can monitor events by using the Azure CLI:

Monitor events sent to Azure IoT Hub
az iot hub monitor-events --hub-name <iot hub name>

Add additional IoT devices​

To add additional IoT devices to your deployed application, please open Microsoft Azure portal in a web browser and navigate to the deployed IoT Hub. In the IoT Hub, select Devices under Device management in the left pane, and then click the Add Device toolbar button.

Assuming that the new device will be named device02, enter the following information and then click the Save button.

  • Device ID: device02
  • Authentication type: X.509 CA Signed

With the new Azure IoT device created, navigate to your Key Vault instance and select Certificates under Objects in the left pane. Click the ca certificate and download it in the same way as you previously downloaded the device certificate.

With the CA certificate downloaded, and assumed to have the name keyvault.pfx, please open a command-line interface and run the following commands to create a new device certificate. At this point you will need to have OpenSSL installed on your computer.

Create a new device certificate
# Define a variable with the name of the new device
device_identity=device02

# Define a variable pointing at the downloaded CA certificate
ca_path=keyvault.pfx

# Generate a new private key
openssl genrsa -out "$device_identity.key" 2048

# Generate a new certificate signing request (CSR)
openssl req -new -key "$device_identity.key" -subj "/CN=$device_identity" \
    -out "$device_identity.csr"

# Convert the downloaded CA certificate from PFX format to PEM format (press
# enter when asked for password)
openssl pkcs12 -in "$ca_path" -nodes -out ca.pem

# Create the new device certificate
openssl x509 -req -in "$device_identity.csr" -CA ca.pem -CAcreateserial \
    -days 365 -sha256 -out "$device_identity.pem"

# Convert the device certificate from PEM format to PFX format
openssl pkcs12 -inkey "$device_identity.key" -in "$device_identity.pem" -export \
    -passout pass: -out "$device_identity.pfx"

With the new device certificate device02.pfx created, please proceed to upload the certificate to the camera, and then configure the camera using the same steps as the first camera in the application.

Cleanup​

To delete all deployed resources in Azure, run the following CLI command:

Cleanup deployed resources
az group delete --name <resource group name>

Troubleshooting​

This section will highlight some of the common problems one might encounter when running this example application.

MQTT client cannot connect to the Azure IoT Hub​

If the MQTT client is unable to successfully connect to the Azure IoT Hub, please make sure that the following statements are true.

  • The camera is not behind a proxy. This example does not support a network topology where requests needs to traverse a proxy to reach the internet.
  • The camera date and time is correctly configured. The date and time of the camera needs to be correctly configured.

Disclaimer​

Microsoft and Azure are trademarks of Microsoft Corporation. All other trademarks are the property of their respective owners, and we are not affiliated with, endorsed or sponsored by them or their affiliates.

As described in this document, you may be able to connect to, access and use third party products, web sites, example code, software or services (“Third Party Services”). You acknowledge that any such connection and access to such Third Party Services are made available to you for convenience only. Axis does not endorse any Third Party Services, nor does Axis make any representations or provide any warranties whatsoever with respect to any Third Party Services, and Axis specifically disclaims any liability or obligations with regard to Third Party Services. The Third Party Services are provided to you in accordance with their respective terms and conditions, and you alone are responsible for ensuring that you (a) procure appropriate rights to access and use any such Third Party Services and (b) comply with the terms and conditions applicable to its use.

Last updated on