Azure IoT Hub¶
The Azure IoT Hub library provides an API to connect to an Azure IoT Hub instance and interact with it. It connects to Azure IoT Hub using MQTT over TLS.
Optionally, the library supports Azure IoT Hub Device Provisioning Service (DPS). DPS can be enabled at compile time to make use of the device provisioning services for onboarding of devices to Azure IoT Hub. When the device provisioning is complete, the library automatically connects to the assigned Azure IoT Hub.
The library also has integrated support for Azure FOTA. For more information on Azure FOTA, see the documentation on Azure FOTA library and nRF9160: Azure FOTA sample.
Prerequisites for connecting to Azure IoT Hub¶
In order to connect to Azure IoT Hub, an Azure account and an Azure IoT Hub instance must first be created and configured. See Creating an Azure IoT Hub instance using the Azure portal for more information.
Note
While Registering the device with Azure IoT Hub, make sure that you select X.509 CA Signed
as the Authentication type.
The connection to Azure IoT Hub with MQTT is secured using TLS. For testing purposes, see Creating Azure IoT Hub certificates for the steps to create certificates and a private key for the leaf device, and to register the generated test root certificate to be used with an IoT hub.
The Azure IoT Hub library requires the provisioning of the following certificates and a private key for a successful TLS connection:
Baltimore CyberTrust Root certificate - Server certificate, used to verify the server’s certificate while connecting.
Device certificate - generated by the procedures described in Creating Azure IoT Hub certificates , used by Azure IoT Hub to authenticate the device.
Private key of the device.
Provisioning of the certificates¶
To provision the certificates and the private key to the nRF9160 modem, complete the following steps:
Update the modem firmware on the onboard modem of the nRF9160-based device to the latest version by following the steps in Updating the nRF9160 DK cellular modem.
Build and program the nRF9160: AT Client sample to the nRF9160-based device as explained in Building and programming a sample application.
Launch the LTE Link Monitor application, which is part of nRF Connect for Desktop.
Click Certificate manager located at the top right corner.
Copy the Baltimore CyberTrust Root certificate into the
CA certificate
entry.Copy and paste the device certificate and the key created using the scripts located in Creating Azure IoT Hub certificates, into the respective entries (
Client certificate
,Private key
).Select a desired security tag (any positive integer, for example,
42
) and click Update certificates.
Note
The chosen security tag while provisioning the certificates must be same as the security tag configured by the CONFIG_AZURE_IOT_HUB_SEC_TAG
option.
Configuring the library¶
You can configure the library to connect to Azure IoT Hub with or without using DPS.
Configuration without using DPS¶
To connect to Azure IoT Hub without using DPS, complete the following minimum required configuration:
In the Azure Portal, navigate to IoT Hub and select the desired IoT hub.
In the overview page, locate and copy the
Hostname
and configureCONFIG_AZURE_IOT_HUB_HOSTNAME
to this address.Set the option
CONFIG_AZURE_IOT_HUB_DEVICE_ID
to the device ID. The device ID must match the device ID used while creating the certificates.Set
CONFIG_AZURE_IOT_HUB_SEC_TAG
to the security tag used in Provisioning of the certificates.
Configuration using DPS¶
To connect to Azure IoT Hub using DPS, complete the following steps:
Set up an Azure IoT Hub Device Provisioning Service (DPS) instance and obtain the ID scope.
Create an enrollment group as described in Device enrollments with Azure Portal and link it to your IoT hub. Select the certificate added in the previous step as the Primary certificate.
Enable
CONFIG_AZURE_IOT_HUB_DPS
.In the Azure Portal, click Device Provisioning Services and select the DPS instance to use.
In the overview page, locate and copy the
ID Scope
and configureCONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
to this string.Set the
CONFIG_AZURE_IOT_HUB_DEVICE_ID
option to device ID, unlessCONFIG_AZURE_IOT_HUB_DEVICE_ID_APP
is enabled. The device ID must match the device ID used while creating the certificates.Set
CONFIG_AZURE_IOT_HUB_SEC_TAG
to the security tag used while Provisioning of the certificates.
Initializing the library¶
The library is initialized by calling the azure_iot_hub_init()
function.
If the initialization fails, the application cannot use any APIs of the library.
Optionally, you can enable CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP
and include a pointer to the azure_iot_hub_config
structure containing the device ID in the azure_iot_hub_init()
function call.
Below is an example for setting the device ID at run time instead of compile time by configuring the CONFIG_AZURE_IOT_HUB_DEVICE_ID
option:
struct azure_iot_hub_config cfg = { .device_id = "my-device", .device_id_len = sizeof("my-device") - 1, }; int err = azure_iot_hub_init(&cfg, event_handler); if (err) { printk("azure_iot_hub_init failed: %d\n", err); return err; }
Connecting to Azure IoT Hub¶
After the initialization, a azure_iot_hub_connect()
function call connects the device to the configured IoT hub or DPS instance, depending on the configuration.
The initial TLS handshake takes some time to complete, typically in the range of few seconds, depending on the network conditions and the TLS cipher suite used.
During the TLS handshake, azure_iot_hub_connect()
blocks, so care must be taken when deciding the context from which the API is called.
After a successful connection, the library automatically subscribes to the following standard Azure IoT Hub MQTT topics (See Azure IoT Hub MQTT protocol support for details):
devices/<device ID>/messages/devicebound/#
(cloud-to-device messages)$iothub/twin/PATCH/properties/desired/#
(desired properties update notifications)$iothub/twin/res/#
(operation responses)$iothub/methods/POST/#
(direct method requests)
Currently, the library does not support persistent MQTT sessions. Hence subscriptions are requested for each connection to the IoT hub.
Configuration¶
Configure the following parameters when using this library:
CONFIG_AZURE_IOT_HUB_HOSTNAME
- Sets the Azure IoT Hub host name. It must be configured, since DPS is not enabled by default.CONFIG_AZURE_IOT_HUB_DEVICE_ID
- Specifies the device ID, which is used when connecting to Azure IoT Hub or when DPS is enabled.CONFIG_AZURE_IOT_HUB_DEVICE_ID_APP
- Used to provide the device ID at run time.CONFIG_AZURE_IOT_HUB_DPS
- Enables Azure IoT Hub DPS.CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
- Sets the Azure IoT Hub DPS ID scope that is used while provisioning the device.
API documentation¶
include/net/azure_iot_hub.h
subsys/net/lib/azur_iot_hub/src/
-
group
azure_iot_hub
Library to connect a device to Azure IoT Hub.
Typedefs
-
typedef void (*
azure_iot_hub_evt_handler_t
)(struct azure_iot_hub_evt *evt)¶ Azure IoT Hub library event handler.
- Parameters
evt – Pointer to event structure.
Enums
-
enum
azure_iot_hub_evt_type
¶ Azure IoT Hub notification events used to notify the user.
Values:
-
enumerator
AZURE_IOT_HUB_EVT_CONNECTING
¶ Connecting to Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_CONNECTED
¶ Connected to Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_CONNECTION_FAILED
¶ Connection attempt failed. The reported error code from the IoT Hub is available in the data.err member in the event structure. The error codes correspond to return codes in MQTT CONNACK messages.
-
enumerator
AZURE_IOT_HUB_EVT_READY
¶ Azure IoT Hub connection established and ready.
-
enumerator
AZURE_IOT_HUB_EVT_DISCONNECTED
¶ Disconnected from Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_DATA_RECEIVED
¶ Device-bound data received from Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_PUBACK
¶ Acknowledgment for data sent to Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_TWIN_RECEIVED
¶ Device twin has been received.
-
enumerator
AZURE_IOT_HUB_EVT_TWIN_DESIRED_RECEIVED
¶ Device twin has received a desired property update.
-
enumerator
AZURE_IOT_HUB_EVT_TWIN_RESULT_SUCCESS
¶ Device twin update successful. The request ID and status are contained in the data.result member of the event structure.
-
enumerator
AZURE_IOT_HUB_EVT_TWIN_RESULT_FAIL
¶ Device twin update failed. The request ID and status are contained in the data.result member of the event structure.
-
enumerator
AZURE_IOT_HUB_EVT_DPS_CONNECTING
¶ Connecting to Device Provisioning Service.
-
enumerator
AZURE_IOT_HUB_EVT_DPS_REGISTERING
¶ Device Provisioning Service registration has started.
-
enumerator
AZURE_IOT_HUB_EVT_DPS_DONE
¶ Device Provisioning Service is done, and Azure IoT Hub information obtained.
-
enumerator
AZURE_IOT_HUB_EVT_DPS_FAILED
¶ Device Provisioning Service failed to retrieve information to connect to Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_EVT_DIRECT_METHOD
¶ Direct method invoked from the cloud side.
Note
After a direct method has been executed, azure_iot_hub_method_respond must be called to report back the result of the method invocation.
-
enumerator
AZURE_IOT_HUB_EVT_FOTA_START
¶ FOTA download starting.
-
enumerator
AZURE_IOT_HUB_EVT_FOTA_DONE
¶ FOTA update done, reboot required to apply update.
-
enumerator
AZURE_IOT_HUB_EVT_FOTA_ERASE_PENDING
¶ FOTA erase pending. On nRF9160-based devices this is typically caused by an active LTE connection preventing erase operation.
-
enumerator
AZURE_IOT_HUB_EVT_FOTA_ERASE_DONE
¶ FOTA erase done.
-
enumerator
AZURE_IOT_HUB_EVT_FOTA_ERROR
¶ FOTA failed
-
enumerator
AZURE_IOT_HUB_EVT_ERROR
¶ Internal library error
-
enumerator
-
enum
azure_iot_hub_topic_type
¶ Azure IoT Hub topic type, used to route messages to the correct destination.
Values:
-
enumerator
AZURE_IOT_HUB_TOPIC_DEVICEBOUND
¶ Data received on the devicebound topic.
-
enumerator
AZURE_IOT_HUB_TOPIC_EVENT
¶ Event topic used to send event data to Azure IoT Hub.
-
enumerator
AZURE_IOT_HUB_TOPIC_TWIN_DESIRED
¶ Received “desired” properties from the device twin.
-
enumerator
AZURE_IOT_HUB_TOPIC_TWIN_REPORTED
¶ Send updates to the “reported” properties in the device twin.
-
enumerator
AZURE_IOT_HUB_TOPIC_TWIN_REQUEST
¶ Topic to request to receive the device twin.
-
enumerator
Functions
-
int
azure_iot_hub_init
(const struct azure_iot_hub_config *config, azure_iot_hub_evt_handler_t event_handler)¶ Initialize the module.
Warning
This API must be called exactly once, and it must return successfully for subsequent calls to this library to succeed.
- Parameters
config – [in] Pointer to struct containing connection parameters. Can be NULL if
CONFIG_AZURE_IOT_HUB_DEVICE_ID
is set.event_handler – [in] Pointer to event handler function.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_connect
(void)¶ Establish connection to Azure IoT Hub. The function blocks until a connection to the hub is established on the transport level. Subsequent calls to other library function should await AZURE_IOT_HUB_EVT_CONNECTED and AZURE_IOT_HUB_EVT_READY events.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_disconnect
(void)¶ Disconnect from Azure IoT Hub. Calling this function initiates the disconnection procedure, and the event AZURE_IOT_HUB_EVT_DISCONNECTED is received when it is completed.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_send
(const struct azure_iot_hub_data *const tx_data)¶ Send data to Azure IoT Hub.
- Parameters
tx_data – [in] Pointer to struct containing data to be transmitted to Azure IoT Hub.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_input
(void)¶ Receive incoming data from Azure IoT Hub.
Implicitly this function calls a non-blocking recv() on the socket with IoT hub connection. It can be polled periodically, but by default this functionality is handled internally in the library.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_ping
(void)¶ Ping Azure IoT Hub. Must be called periodically to keep connection alive. By default ping is handled internally in the library.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_method_respond
(struct azure_iot_hub_result *result)¶ Send response to a direct method invoked from the cloud.
- Parameters
result – [in] Structure containing result data from the direct method execution.
- Returns 0
If successful. Otherwise, a (negative) error code is returned.
-
int
azure_iot_hub_keepalive_time_left
(void)¶ Helper function to determine when next ping should be sent in order to keep the connection alive. By default, ping is sent in time automatically by the library.
- Returns
Time in milliseconds until next keepalive ping will be sent.
- Returns
-1 if keepalive messages are not enabled.
-
struct
azure_iot_hub_prop_bag
¶ - #include <azure_iot_hub.h>
Property bag structure for key/value string pairs. Per Azure IoT Hub documentation, the key must be defined, while the value can be a string, an empty string or NULL.
Note
If value is provided as a string, it’s the equivalent to “key=value”. If the value is an empty string (only null-terminator), it’s the equivalent of “key=”. If value is NULL, it’s the equivalent of “key”.
-
struct
azure_iot_hub_topic_data
¶ - #include <azure_iot_hub.h>
Azure IoT Hub topic data.
Public Members
-
enum azure_iot_hub_topic_type
type
¶ Topic type.
-
char *
str
¶ Pointer to topic name.
-
size_t
len
¶ Length of topic name.
-
enum azure_iot_hub_topic_type
-
struct
azure_iot_hub_data
¶ - #include <azure_iot_hub.h>
Azure IoT Hub transmission data.
Public Members
-
struct azure_iot_hub_topic_data
topic
¶ Topic data is sent/received on.
-
char *
ptr
¶ Pointer to data sent/received from Azure IoT Hub.
-
size_t
len
¶ Length of data.
-
uint16_t
message_id
¶ Message id used for the message, used to match acknowledgments.
-
uint8_t
dup_flag
¶ Duplicate flag. 1 indicates the message is a retransmission, Usually triggered by missing publication acknowledgment.
-
uint8_t
retain_flag
¶ Retain flag. 1 indicates to the IoT hub that the message should be stored persistently.
-
struct azure_iot_hub_topic_data
-
struct
azure_iot_hub_method
¶ - #include <azure_iot_hub.h>
Azure IoT Hub direct method data.
-
struct
azure_iot_hub_result
¶ - #include <azure_iot_hub.h>
Azure IoT Hub result structure.
Used to signal result of direct method execution from device to cloud, and to receive result of device twin updates (twin updates sent from the device will receive a result message back from the cloud with success or failure).
-
struct
azure_iot_hub_evt
¶ - #include <azure_iot_hub.h>
Struct with data received from Azure IoT Hub.
Public Members
-
enum azure_iot_hub_evt_type
type
¶ Type of event.
-
enum azure_iot_hub_evt_type
-
struct
azure_iot_hub_config
¶ - #include <azure_iot_hub.h>
Structure for Azure IoT Hub connection parameters.
-
typedef void (*