az iot device

Is this page helpful?

Any additional feedback?

Feedback will be sent to Microsoft: By pressing the submit button, your feedback will be used to improve Microsoft products and services. Privacy policy.

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.24.1 or higher). The extension will automatically install the first time you run an az iot device command. Learn more about extensions.

Leverage device-to-cloud and cloud-to-device messaging capabilities.

Commands

az iot device c2d-message	Cloud-to-device messaging commands.
az iot device c2d-message abandon	Abandon a cloud-to-device message.
az iot device c2d-message complete	Complete a cloud-to-device message.
az iot device c2d-message purge	Purge cloud-to-device message queue for a target device.
az iot device c2d-message receive	Receive a cloud-to-device message.
az iot device c2d-message reject	Reject or deadletter a cloud-to-device message.
az iot device c2d-message send	Send a cloud-to-device message.
az iot device send-d2c-message	Send an mqtt device-to-cloud message. The command supports sending messages with application and system properties. Note: The command only works for symmetric key auth (SAS) based devices.
az iot device simulate	Simulate a device in an Azure IoT Hub. While the device simulation is running, the device will automatically receive and acknowledge cloud-to-device (c2d) messages. For mqtt simulation, all c2d messages will be acknowledged with completion. For http simulation c2d acknowledgement is based on user selection which can be complete, reject or abandon. The mqtt simulation also supports direct method invocation which can be acknowledged by a response status code and response payload. Note: MQTT simulation is only supported for symmetric key auth (SAS) based devices. Note: The command by default will set content-type to application/json and content-encoding to utf-8. This can be overriden.
az iot device upload-file	Upload a local file as a device to a pre-configured blob storage container.

az iot device send-d2c-message

Send an mqtt device-to-cloud message. The command supports sending messages with application and system properties.

Note: The command only works for symmetric key auth (SAS) based devices.

az iot device send-d2c-message --device-id
                               [--da]
                               [--hub-name]
                               [--login]
                               [--mc]
                               [--properties]
                               [--resource-group]

Examples

Basic usage

az iot device send-d2c-message -n {iothub_name} -d {device_id}

Basic usage with custom data

az iot device send-d2c-message -n {iothub_name} -d {device_id} --data {message_body}

Send application properties

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props 'key0=value0;key1=value1'

Send system properties (Message Id and Correlation Id)

az iot device send-d2c-message -n {iothub_name} -d {device_id} --props '$.mid=<id>;$.cid=<id>'

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--da --data

Message body.

default value: Ping from Az CLI IoT Extension

--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--mc --msg-count

Number of device messages to send to IoT Hub.

default value: 1

--properties --props -p

Message property bag in key-value pairs with the following format: a=b;c=d. For mqtt messaging - you are able to send system properties using $.=value. For instance $.cid=12345 sets the system correlation Id property. Other system property identifier examples include $.ct for content type, $.mid for message Id and $.ce for content encoding.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot device simulate

Simulate a device in an Azure IoT Hub.

While the device simulation is running, the device will automatically receive and acknowledge cloud-to-device (c2d) messages. For mqtt simulation, all c2d messages will be acknowledged with completion. For http simulation c2d acknowledgement is based on user selection which can be complete, reject or abandon. The mqtt simulation also supports direct method invocation which can be acknowledged by a response status code and response payload.

Note: MQTT simulation is only supported for symmetric key auth (SAS) based devices.

Note: The command by default will set content-type to application/json and content-encoding to utf-8. This can be overriden.

az iot device simulate --device-id
                       [--da]
                       [--hub-name]
                       [--init-reported-properties]
                       [--login]
                       [--mc]
                       [--method-response-code]
                       [--method-response-payload]
                       [--mi]
                       [--properties]
                       [--proto {http, mqtt}]
                       [--receive-settle {abandon, complete, reject}]
                       [--resource-group]

Examples

Basic usage (mqtt)

az iot device simulate -n {iothub_name} -d {device_id}

Send mixed properties (mqtt)

az iot device simulate -n {iothub_name} -d {device_id} --properties "myprop=myvalue;$.ct=application/json"

Send direct method response status code and direct method response payload as raw json (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --method-response-code 201 --method-response-payload '{"result":"Direct method successful"}'

Send direct method response status code and direct method response payload as path to local file (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --method-response-code 201 --method-response-payload '../my_direct_method_payload.json'

Send the initial state of device twin reported properties as raw json for the target device (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --init-reported-properties '{"reported_prop_1":"val_1", "reported_prop_2":val_2}'

Send the initial state of device twin reported properties as path to local file for the target device (mqtt only)

az iot device simulate -n {iothub_name} -d {device_id} --init-reported-properties '../my_device_twin_reported_properties.json'

Basic usage (http)

az iot device simulate -n {iothub_name} -d {device_id} --protocol http

Send mixed properties (http)

az iot device simulate -n {iothub_name} -d {device_id} --protocol http --properties "iothub-app-myprop=myvalue;content-type=application/json;iothub-correlationid=12345"

Choose total message count and interval between messages

az iot device simulate -n {iothub_name} -d {device_id} --msg-count 1000 --msg-interval 5

Reject c2d messages (http only)

az iot device simulate -n {iothub_name} -d {device_id} --rs reject --protocol http

Abandon c2d messages (http only)

az iot device simulate -n {iothub_name} -d {device_id} --rs abandon --protocol http

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--da --data

Message body.

default value: Ping from Az CLI IoT Extension

--hub-name -n

IoT Hub name. Required if --login is not provided.

--init-reported-properties --irp

Initial state of twin reported properties for the target device when the simulator is run. Optional param, only supported for mqtt.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--mc --msg-count

Number of device messages to send to IoT Hub.

default value: 100

--method-response-code --mrc

Status code to be returned when direct method is executed on device. Optional param, only supported for mqtt.

--method-response-payload --mrp

Payload to be returned when direct method is executed on device. Provide file path or raw json. Optional param, only supported for mqtt.

--mi --msg-interval

Delay in seconds between device-to-cloud messages.

default value: 3

--properties --props -p

Message property bag in key-value pairs with the following format: a=b;c=d. For mqtt messaging - you are able to send system properties using $.=value. For instance $.cid=12345 sets the system correlation Id property. Other system property identifier examples include $.ct for content type, $.mid for message Id and $.ce for content encoding. For http messaging - application properties are sent using iothub-app-=value, for instance iothub-app-myprop=myvalue. System properties are generally prefixed with iothub- like iothub-correlationid but there are exceptions such as content-type and content-encoding.

--proto --protocol

Indicates device-to-cloud message protocol.

accepted values: http, mqtt

default value: mqtt

--receive-settle --rs

Indicates how to settle received cloud-to-device messages. Supported with HTTP only.

accepted values: abandon, complete, reject

default value: complete

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az iot device upload-file

Upload a local file as a device to a pre-configured blob storage container.

az iot device upload-file --content-type
                          --device-id
                          --file-path
                          [--hub-name]
                          [--login]
                          [--resource-group]

Required Parameters

--content-type --ct

MIME Type of file.

--device-id -d

Target Device.

--file-path --fp

Path to file for upload.

Optional Parameters

--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters

--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.