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 a proprietary FOTA solution. For more information on Azure FOTA, see the documentation on Azure FOTA library and nRF9160: Azure FOTA sample.
The library uses Azure SDK for Embedded C for message processing and other operations. For more information on how Azure SDK for Embedded C is integrated in this library, see Azure SDK for Embedded C IoT client libraries.
Important
If the server sends a device-bound message when the device is unavailable for a period of time, for instance while in LTE Power Saving Mode, the server will most likely terminate the TCP connection. This will result in additional data traffic as the device has to reconnect to the server, which in turn requires a new TLS handshake and MQTT connection establishment.
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
If you do not use DPS to provision devices to your IoT Hub, make sure that you select X.509 CA Signed
as the Authentication type while Registering the device with Azure IoT Hub.
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 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.
Public 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.
Important
Azure has started the process of migrating their IoT Hub and DPS server certificates from Baltimore CyberTrust Root Certificate to DigiCert Global Root G2.
Azure advises to have both Baltimore CyberTrust Root and DigiCert Global Root G2 certificates for all devices to avoid disruption of service during the transition.
Refer to Azure IoT TLS: Critical changes for updated information and timeline.
Due to this, it is recommended to provision the DigiCert Root G2 certificate to a secondary security tag set by the CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG
option.
This ensures that the device can connect after the transition.
Note
The location and name of the generated public device certificate and private key files vary depending on the method you use for the credential generation.
For PowerShell scripts, the device certificate is called mydevice-public.pem
and the private key is mydevice-private.pem
.
These files are located in the working directory with the other generated files.
For bash scripts, the public device certificate is called new-device.cert.pem
and is located in a directory called certs
within the script
directory.
The private key is called new-device.key.pem
and located in a directory called private
within the script
directory.
The file and directory names may change if Azure changes their scripts.
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 modem firmware.
Build and program the nRF9160: AT Client sample to the nRF9160-based device as explained in Building and programming an application.
Launch the LTE Link Monitor application, which is part of nRF Connect for Desktop.
Click CERTIFICATE MANAGER located at the upper right corner.
Copy the server root certificate into the
CA certificate
entry.Copy and paste the device certificate and the private key into the respective entries (
Client certificate
,Private key
).Select a desired security tag (any positive integer in the range of 0 to 2147483647) and click Update certificates.
Important
The default security tag set by the CERTIFICATE MANAGER 16842753 is reserved for communications with nRF Cloud. Overwriting this security tag entry will require you to flash new certificates if you want to establish a connection to the nRF Cloud.
Note
The chosen security tag while provisioning the certificates must be same as the security tag configured by the CONFIG_MQTT_HELPER_SEC_TAG
option.
Note
If more than one root server certificate is used, the second one can be provisioned to a different security tag and configured in the application using the CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG
Kconfig option.
The modem will check both security tags if necessary when verifying the server’s certificate.
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.The hostname can also be set at run time.
Set the option
CONFIG_AZURE_IOT_HUB_DEVICE_ID
to the device ID.The device ID must match with the one used while creating the certificates. You can also set the device ID at run time by populating the
device_id
member of theazure_iot_hub_config
structure passed to theazure_iot_hub_connect()
function when connecting. If thedevice_id.size
buffer size is zero, the compile-time optionCONFIG_AZURE_IOT_HUB_DEVICE_ID`
is used.Make sure that the device is already registered with your Azure IoT Hub, or follow the instructions in Registering the device with Azure IoT Hub.
Set the
CONFIG_MQTT_HELPER_SEC_TAG
option to the security tag used in Provisioning of the certificates.Optionally, set the
CONFIG_MQTT_HELPER_SEC_TAG
option if multiple server certificates are provisioned.
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 set theCONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
option to this string.Alternatively, you can set the registration ID at run time.
Set the
CONFIG_AZURE_IOT_HUB_DPS_REG_ID
option to the registration ID.You can also set the registration ID at run time.
Set
CONFIG_MQTT_HELPER_SEC_TAG
to the security tag used while Provisioning of the certificates. Optionally, set theCONFIG_MQTT_HELPER_SEC_TAG
option if multiple server certificates are provisioned.
Application integration
Initializing the library
The library is initialized by calling the azure_iot_hub_init()
function.
The initialization must be successful to make the other APIs in the library available for the application.
An event handler is passed as the only argument to the azure_iot_hub_init()
function.
The library calls this function with data associated to the application, such as incoming data and other events.
For an exhaustive list of event types and associated data, see azure_iot_hub_evt_type
.
Using the Device Provisioning Service
You can use the Azure IoT Hub Device Provisioning Service to provision the device to an IoT Hub. When the registration process has completed successfully, the device receives its assigned hostname and device ID to use when connecting to Azure IoT Hub. The assigned hostname and device ID are stored to the non-volatile memory on the device and are available also after a reset and power outage.
This code example shows how to configure and use DPS:
static void dps_handler(enum azure_iot_hub_dps_reg_status state)
{
switch (state) {
case AZURE_IOT_HUB_DPS_REG_STATUS_NOT_STARTED:
LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_NOT_STARTED");
break;
case AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNING:
LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNING");
break;
case AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNED:
LOG_INF("AZURE_IOT_HUB_DPS_REG_STATUS_ASSIGNED");
/* Act on assignment */
k_sem_give(&dps_assigned_sem);
break;
case AZURE_IOT_HUB_DPS_REG_STATUS_FAILED:
LOG_INF("ZURE_IOT_HUB_DPS_REG_STATUS_FAILED");
/* Act on registration failure */
k_sem_give(&dps_registration_failed_sem);
break;
default:
LOG_WRN("Unhandled DPS registration status: %d", state);
break;
}
}
...
int err;
struct azure_iot_hub_buf assigned_hostname;
struct azure_iot_hub_buf assigned_device_id;
struct azure_iot_hub_dps_config dps_cfg = {
.handler = dps_handler,
/* Can be left out to use CONFIG_AZURE_IOT_HUB_DPS_REG_ID instead. */
.reg_id = {
.ptr = device_id_buf,
.size = device_id_len,
},
/* Can be left out to use CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE instead. */
.id_scope = {
.ptr = id_scope_buf,
.size = id_scope_len,
},
};
err = azure_iot_hub_dps_init(&dps_cfg);
/* Error handling */
err = azure_iot_hub_dps_start();
if (err == 0) {
LOG_INF("The DPS process has started");
/* Wait for the registration process to complete. */
err = k_sem_take(&dps_done_sem, K_SECONDS(SOME_TIMEOUT));
/* Error handling */
} else if (err == -EALREADY) {
LOG_INF("Already assigned to an IoT hub, skipping DPS");
} else {
/* Error handling */
}
err = azure_iot_hub_dps_hostname_get(assigned_hostname);
/* Error handling */
err = azure_iot_hub_dps_device_id_get(assigned_device_id);
/* Error handling */
/* Use the hostname and device ID to connect to IoT Hub. */
After successfully registering the device, the application can proceed to connect to the assigned IoT Hub using the obtained device ID.
When a device has been assigned to an IoT Hub and the information is stored to the non-volatile memory, the DPS APIs always return the stored information and do not trigger a new registration.
To delete the stored assignment information, call the azure_iot_hub_dps_reset()
function.
Alternatively, you can call the functions azure_iot_hub_dps_hostname_delete()
or azure_iot_hub_dps_device_id_delete()
to delete specific information.
After calling the azure_iot_hub_dps_reset()
function, the library must be initialized again.
After the initialization, a new registration with the DPS can be started by calling the azure_iot_hub_dps_start()
function.
The DPS APIs are documented in the Azure IoT Hub DPS API section.
Connecting to Azure IoT Hub
After the initialization, calling the azure_iot_hub_connect()
function connects the device to the configured IoT hub or DPS instance, depending on the configuration.
The initial TLS handshake takes a few seconds to complete, depending on the network conditions and the TLS cipher suite used.
During the TLS handshake, the azure_iot_hub_connect()
function blocks.
Consider this when deciding the context from which the API is called.
Optionally, DPS registration can be run automatically as part of the call to the azure_iot_hub_connect()
function.
Note that the azure_iot_hub_connect()
function blocks when DPS registration is pending.
Running DPS as part of the azure_iot_hub_connect()
function also limits the DPS configuration options as follows:
The device ID is used as registration ID when registering with the DPS server.
The ID scope is set in the
CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
option.
Use the DPS APIs directly if you need more control over the DPS registration process.
When using the azure_iot_hub_connect()
function, you can choose to provide the hostname to the IoT Hub and device ID at run time, or let the library use Kconfig options.
Here is an example for setting the hostname and device ID at run time:
struct azure_iot_hub_config cfg = {
.hostname = {
.ptr = hostname_buffer,
.size = hostname_length,
},
.device_id = {
.ptr = device_id_buffer,
.size = device_id_length,
},
.use_dps = false,
};
err = azure_iot_hub_connect(&cfg);
/* Error handling */
You can pass NULL
or a zeroed out configuration to the azure_iot_hub_connect()
function.
The library uses the values for hostname and device ID from the Kconfig options CONFIG_AZURE_IOT_HUB_HOSTNAME
and CONFIG_AZURE_IOT_HUB_DEVICE_ID
, respectively.
This code example uses a Kconfig value for the device ID (and by extension DPS registration ID) and runs DPS to acquire the assigned IoT Hub hostname and assigned device ID.
struct azure_iot_hub_config cfg = {
.use_dps = true,
};
err = azure_iot_hub_connect(&cfg);
/* Error handling */
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.
For more information about the available APIs, see the Azure IoT Hub API section.
Configuration
To use the Azure IoT Hub library, you must enable the CONFIG_AZURE_IOT_HUB
Kconfig option.
You can configure the following options when using this library:
CONFIG_AZURE_IOT_HUB_HOSTNAME
- Sets the Azure IoT Hub host name. Note that the hostname can also be provided at run time.CONFIG_AZURE_IOT_HUB_DEVICE_ID
- Configures the device ID. The device ID can also be set at run time.CONFIG_AZURE_IOT_HUB_USER_NAME_BUF_SIZE
- Sets the user name buffer size. You can adjust the buffer size to reduce stack usage, if you know the approximate size of your device ID.CONFIG_AZURE_IOT_HUB_AUTO_DEVICE_TWIN_REQUEST
- Automatically requests the device twin upon connection to an IoT Hub.CONFIG_AZURE_IOT_HUB_TOPIC_MAX_LEN
- Sets the maximum topic length. The topic buffers are allocated on the stack. You may have to adjust this option to match with your device ID length.CONFIG_AZURE_IOT_HUB_MSG_PROPERTY_RECV_MAX_COUNT
- Sets the maximum number of message properties that can be parsed from an incoming message’s topic.CONFIG_AZURE_IOT_HUB_MSG_PROPERTY_BUFFER_SIZE
- Sets the size of the internal message property buffer used when sending messages with message properties, allocated on the stack. You can adjust this to fit your needs.
MQTT helper library specific options:
CONFIG_MQTT_HELPER_SEND_TIMEOUT
- Enables timeout when sending data to an IoT Hub.CONFIG_MQTT_HELPER_SEND_TIMEOUT_SEC
- Sets the send timeout value (in seconds) to use when sending data.CONFIG_MQTT_HELPER_SEC_TAG
- Sets the security tag where the Azure IoT Hub certificates are stored.CONFIG_MQTT_HELPER_SECONDARY_SEC_TAG
- Sets the secondary security tag that can be used for a second CA root certificate.CONFIG_MQTT_HELPER_PORT
- Sets the TCP port number to connect to.CONFIG_MQTT_HELPER_RX_TX_BUFFER_SIZE
- Sets the size of the MQTT RX and TX buffer that limits the message size, excluding the payload size.CONFIG_MQTT_HELPER_PAYLOAD_BUFFER_LEN
- Sets the MQTT payload buffer size.CONFIG_MQTT_HELPER_STACK_SIZE
- Sets the stack size for the internal thread in the library.CONFIG_MQTT_HELPER_NATIVE_TLS
- Configures the socket to be native for TLS instead of offloading TLS operations to the modem.
DPS-specific configuration:
CONFIG_AZURE_IOT_HUB_DPS
- Enables Azure IoT Hub DPS.CONFIG_AZURE_IOT_HUB_DPS_HOSTNAME
- Hostname of the DPS server.CONFIG_AZURE_IOT_HUB_DPS_REG_ID
- Registration ID to use in the registration request to DPS.CONFIG_AZURE_IOT_HUB_DPS_HOSTNAME_MAX_LEN
- Maximum length of the assigned hostname received from DPS.CONFIG_AZURE_IOT_HUB_DPS_DEVICE_ID_MAX_LEN
- Maximum length of the assigned device ID received from DPS.CONFIG_AZURE_IOT_HUB_DPS_TOPIC_BUFFER_SIZE
- Size of the internal topic buffers in the DPS library.CONFIG_AZURE_IOT_HUB_DPS_USER_NAME_BUFFER_SIZE
- User name buffer size.CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
- Sets the Azure IoT Hub DPS ID scope that is used while provisioning the device.CONFIG_AZURE_IOT_HUB_DPS_OPERATION_ID_BUFFER_SIZE
- Size of the operation ID buffer. The operation ID is received from the IoT Hub during registration.
API documentation
Azure IoT Hub API
include/net/azure_iot_hub.h
subsys/net/lib/azure_iot_hub/src/azure_iot_hub.c
Azure IoT Hub DPS API
include/net/azure_iot_hub_dps.h
subsys/net/lib/azure_iot_hub/src/azure_iot_hub_dps.c
- 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.
- Param 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. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_CONNECTED
Connected to Azure IoT Hub. The event has no associated data.
-
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 to receive data. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_DISCONNECTED
Disconnected from Azure IoT Hub. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_DATA_RECEIVED
Device-bound data received from Azure IoT Hub. The event contains the received data in the
data.msg
member, and the topic it was received on in thetopic
member, including message properties intopic.properties
.
-
enumerator AZURE_IOT_HUB_EVT_PUBACK
Acknowledgment for data sent to Azure IoT Hub. The acknowledged message ID is in
data.message_id
.
-
enumerator AZURE_IOT_HUB_EVT_PINGRESP
Acknowledgment for ping request message sent to Azure IoT Hub. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_TWIN_RECEIVED
Device twin has been received. The event contains the received data in the
data.msg
member, and the topic it was received on in thetopic
member, including message properties intopic.properties
.
-
enumerator AZURE_IOT_HUB_EVT_TWIN_DESIRED_RECEIVED
Device twin has received a desired property update. The event contains the received data in the
data.msg
member, and the topic it was received on in thetopic
member, including message properties intopic.properties
.
-
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. The received payload is in the
data.msg
member, and the topic it was received on is in thetopic
member.
-
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_DIRECT_METHOD
Direct method invoked from the cloud side.
The event contains the method data in the ``data.method`` member, and the topic it was received on in the ``topic`` member. @note After a direct method has been executed, @a 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. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_FOTA_DONE
FOTA update done, reboot required to apply update. The event has no associated data.
-
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. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_FOTA_ERASE_DONE
FOTA erase done. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_FOTA_ERROR
FOTA failed. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_ERROR_MSG_SIZE
A received message is too large for the payload buffer and can not be processed. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_ERROR
Internal library error. The event has no associated data.
-
enumerator AZURE_IOT_HUB_EVT_CONNECTING
-
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_DIRECT_METHOD
Data received on the direct method topic.
-
enumerator AZURE_IOT_HUB_TOPIC_TWIN_DESIRED
Received “desired” properties from the device twin.
-
enumerator AZURE_IOT_HUB_TOPIC_TWIN_REQUEST_RESULT
Topic to receive twin request result messages. Both success and error messages are received on the same topic.
-
enumerator AZURE_IOT_HUB_TOPIC_DPS
Topic to receive Device Provisioning Service (DPS) messages.
-
enumerator AZURE_IOT_HUB_TOPIC_EVENT
Event topic used to send event data to Azure IoT Hub.
-
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 AZURE_IOT_HUB_TOPIC_UNKNOWN
Indicates that the message was received on an unknown topic.
-
enumerator AZURE_IOT_HUB_TOPIC_DEVICEBOUND
Functions
-
int azure_iot_hub_init(azure_iot_hub_evt_handler_t event_handler)
Initialize the module.
Note
This API must be called exactly once, and it must return successfully for subsequent calls to this library to succeed.
- Parameters
event_handler – [in] Pointer to event handler function.
- Return values
0 – If successful.
-EALREADY – if the library has already been initialized and is in a state where it can not be re-initialized.
-EINVAL – in invalid argument was provided.
-
int azure_iot_hub_connect(const struct azure_iot_hub_config *config)
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.
- Parameters
config – [in] Pointer to struct containing connection parameters. If NULL, values from Kconfig will be used instead.
- Return values
0 – If successful.
-EALREADY – if the device is already connected to an IoT Hub.
-EINPROGRESS – if an connection attempt is already in progress.
-ENOENT – if the library is not in disconnected state.
-EINVAL – if the provided configuration is invalid.
-EMSGSIZE – if the provided device ID is larger than the internal buffer size.
-EFAULT – if there was an internal error in the library.
-
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.
- Return values
0 – If successful.
-ENOTCONN – if the device is not connected to an IoT Hub.
-ENXIO – if the MQTT library reported an error.
-
int azure_iot_hub_send(const struct azure_iot_hub_msg *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.
- Return values
0 – If successful.
-EINVAL – if a NULL pointer was provided.
-ENOMSG – if the provided message topic was invalid.
-EMSGSIZE – an internal buffer is too small to hold the topic data. This can for instance happen if message properties are in use, as they are appended to the topic.
-ENOTCONN – if the device is not connected to an IoT Hub.
-ENOMEM – if the request ID buffer was insufficient to create the ID.
-EFAULT – if there was an internal error in the library.
-
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.
- Return values
0 – If successful.
-EINVAL – if a NULL pointer was provided.
-ENOTCONN – if there was no iot hub connection.
-EFAULT – if there was an error when creating the response message.
-ENXIO – if the MQTT library reported an error when publishing the response.
-
struct azure_iot_hub_buf
- #include <azure_iot_hub.h>
Buffer to store data together with buffer size.
-
struct azure_iot_hub_property
- #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 or empty.
Note
If value is provided as a string, it’s the equivalent to “key=value”. If the value is empty, it’s the equivalent of “key=” or “key”.
Public Members
-
struct azure_iot_hub_buf key
Property key.
-
struct azure_iot_hub_buf value
Property value.
-
struct azure_iot_hub_buf 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.
-
struct azure_iot_hub_buf name
Topic name ptr and size.
-
enum azure_iot_hub_topic_type type
-
struct azure_iot_hub_msg
- #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.
-
struct azure_iot_hub_buf payload
Pointer to the payload sent/received from Azure IoT Hub.
-
struct azure_iot_hub_buf request_id
Request ID that can be populated if relevcant for the message type.
-
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 topic
-
struct azure_iot_hub_method
- #include <azure_iot_hub.h>
Azure IoT Hub direct method data.
Public Members
-
struct azure_iot_hub_buf name
Method name.
-
struct azure_iot_hub_buf request_id
Method request ID.
-
struct azure_iot_hub_buf payload
Method payload.
-
struct azure_iot_hub_buf name
-
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).
Public Members
-
struct azure_iot_hub_buf request_id
Request ID to which the result belongs.
-
uint32_t status
Status code.
-
struct azure_iot_hub_buf payload
Result payload.
-
struct azure_iot_hub_buf request_id
-
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 type
-
struct azure_iot_hub_config
- #include <azure_iot_hub.h>
Structure for Azure IoT Hub connection parameters.
Public Members
-
struct azure_iot_hub_buf hostname
Hostname to IoT Hub to connect to. If the buffer size is zero, the device ID provided by
CONFIG_AZURE_IOT_HUB_HOSTNAME
is used. If DPS is enabled anduse_dps
is set to true, the provided hostname is ignored.
-
struct azure_iot_hub_buf device_id
Device id for the Azure IoT Hub connection. If the buffer size is zero, the device ID provided by Kconfig is used.
-
bool use_dps
Use DPS to obtain hostname and device ID if true. Using DPS requires that
CONFIG_AZURE_IOT_HUB_DPS
is enabled and DPS configured accordingly. If a hostname and device ID have already been obtained previously, the stored values will be used. To re-run DPS, the DPS information must be reset first. Note that using this option will use the device ID as DPS registration ID and the ID cope fromCONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE
. For more fine-grained control over DPS, use the azure_iot_hub_dps APIs directly insted.
-
struct azure_iot_hub_buf hostname
-
typedef void (*azure_iot_hub_evt_handler_t)(struct azure_iot_hub_evt *evt)