Azure IoT Device Simulator - Help

This section describes the different artifacts of the solution and how they work.

Application

The application consist of:

an application console (.NET Core 3.x)
configuration files:
- appsettings.json (described below)
- devicesettings.json (described below)
- modulessettings.json (described below)
message template files
- commissioning.json (examples below)
- error.json (examples below)
- measureddata.json (examples below)

Global device model architecture

Features

Device

D2C

Messages

Commissioning messages
Measured data messages (aka telemetry)
Error messages (functional errors sent by devices)

Twins

The device sends updated Reported Properties (Twins) after many operations/commands.

Note

Example: after an OnOff Direct Method request, the device sends its status to the cloud solution (Microsoft Azure IoT Hub) using the Twin Reported Properties.

C2D

Direct Methods

Method name	Description	Request	Response	Comments
SendLatencyTest	Allows to start a latency test between a given device and the Microsoft Azure IoT Hub where the device is registered.	`{ "deviceId":"", "messageType":"latency", "startTimestamp":12345}`	NA	The request contains the initial timpestamp, which is sent back to the device after all the process in order to allow him to measure latency. NOTE: this feature requires an Azure Function responding to the latency test requests and calling back the C2D LatencyTestCallBack Direct Method.
LatencyTestCallBack	Allows to end a latency test between a given device and the Microsoft Azure IoT Hub where the device is registered.	`startTimestamp` value, allowing to math the latency (string)	message notifying that the LatencyTestCallBack Direct Method has been called (string). result code, 200	NA
Reboot	Simulates a device reboot operation.	NA	message notifiying that the Reboot Direct Method has been called (string). result code, 200	Sends Twins (Reported properties) notifying the reboot.
OnOff	Turns a given device on/off.	JSON Object	message notifying that the OnOff Direct Method has been called (string). The message contains request's payload. result code, 200
ReadTwins	Orders a given device to read its Twin data.	NA	message notifying that the ReadTwins Direct Method has been called (string). result code, 200
GenericJToken	Generic method	JSON Token	message notifying that the GenericJToken Direct Method has been called (string). result code, 200
Generic	Generic method	string	message notifying that the Generic Direct Method has been called (string). result code, 200
SetTelemetryInterval	Updates the time rate used to send telemetry data.	seconds (int)	message notifying that the SetTelemetryInterval Direct Method has been called (string). result code, 200

Messages

The device can be configured to receive generic messages coming from the cloud (Microsoft Azure IoT Hub C2D Messages).

Twins

Desired

Any change in a Desired Property (device level) is notified to the device and it can be handled.

![NOTE]

Tags and Microsoft IoT Hub Jobs

The simulator can benefit from the use of Microsoft IoT Hub Jobs for operations based in property queries. A typical example of this would be a FOTA (Firmware Over The Air) update according to criteria based in *Twin.Tag properties (ex: firmwareVersion, location, environment, etc).

Modules

M2C

Messages

Commissioning messages
Measured data messages (aka telemetry)
Error messages (functional errors sent by devices)

Twins

Modules send updated Reported Properties (Twins) after many operations/commands.

Note

Example: after a OnOff Direct Method request, a givne module sends its status to the cloud solution (Microsoft Azure IoT Hub) using the Twin Reported Properties.

C2M

Direct Methods

Method name	Description	Request	Response	Comments
Reboot	Simulates a device reboot operation.	NA	message notifying that the Reboot Direct Method has been called (string). result code, 200	Sends Twins (Reported properties) notifying the reboot.
OnOff	Turns a given device on/off.	JSON Object	message notifying that the OnOff Direct Method has been called (string). The message contains request's payload. result code, 200
ReadTwins	Orders a given device to read its Twin data.	NA	message notifying that the ReadTwins Direct Method has been called (string). result code, 200.
GenericJToken	Generic method	JSON Token	message notifying that the GenericJToken Direct Method has been called (string). result code, 200
Generic	Generic method	string	message notifying that the Generic Direct Method has been called (string). result code, 200
SetTelemetryInterval	Updates the time rate used to send telemetry data.	seconds (int)	message notifying that the SetTelemetryInterval Direct Method has been called (string). result code, 200

Messages

Each module can be configured to receive generic messages coming from the cloud (Microsoft Azure IoT Hub).

Twins

Desired

Any change in a Desired property (module level) is notified to the module and it can be handled.

How does the simulator work?

Description

The application is configurable by an appsettings.json file.

The features of the application rely on two main components:

device (one single device per application)
modules (none, one or many modules per device)

The device component is configured by a devicesettings.json file while the modules are configured by a modulessettings.json file.

Device model architecture

Runing the simulator

The simulator is a .NET Core application.

To run the simulator, there are two alternatives:

running the simulator as a .NET Core application (Console Application)
running the Docker container (which contains in turn the .NET Core binaries, packages and other required prerequisites)

![NOTE]

See Docker and container oriented development for those who are not familiar with.

Whatever the alternative will be, check that the 3 configuration files are set properly.

![IMPORTANT]

The 3 configurations files have be present and contain the proper Microsoft Azure IoT Hub connection strings, IDs or keys.

Runing .NET Core application

Run the command below:

dotnet IoT.Simulator.dll

Runing Docker container

docker run -ti --name [containername] [imagename]

You can get ready to use Docker images of the Azure IoT Device Simulator here.

Configurations

Application

Technical settings of the application can be configured at appsettings.json.

Example (Production environment):

{
 "Logging": {
   "LogLevel": {
     "Default": "Warning"
   }
 }
}

Note

The solution contains different settings depending on the environment (similar to transformation files).

Example (Development environment) - appsettings.Development.json:

{
"Logging": {
  "Debug": {
    "LogLevel": {
      "Default": "Trace"
    }
  },
  "Console": {
    "IncludeScopes": true,
    "LogLevel": {
      "Default": "Trace"
    }
  },
  "LogLevel": {
    "Default": "Trace",
    "System": "Trace",
    "Microsoft": "Trace"
  }
}
}

Device

IoT Simulator is linked to one and only one device. The device behavior is configured by the devicessettings.json configuration file.

Example:

{
  "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];SharedAccessKey=[KEY]",
  "simulationSettings": {
    "enableLatencyTests": false,
    "latencyTestsFrecuency": 10,
    "enableDevice": true,
    "enableModules": true,
    "enableTelemetryMessages": false,
    "telemetryFrecuency": 60,
    "enableErrorMessages": false,
    "errorFrecuency": 60,
    "enableCommissioningMessages": false,
    "commissioningFrecuency": 60,
    "enableTwinReportedMessages": false,
    "twinReportedMessagesFrecuency": 60,
    "enableReadingTwinProperties": false,
    "enableC2DDirectMethods": true,
    "enableC2DMessages": true,
    "enableTwinPropertiesDesiredChangesNotifications": true
  }
}

Properties are quite self-explanatory.

Note

Emission intervals are set in seconds.

Modules

IoT Simulator's device can contain zero, one or more modules but no module is mandatory. Behaviors of modules are configured by the modulessettings.json configuration file.

Example of a configuration file of two modules:

{
 "modules":[
    {
      "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];ModuleId=[MODULE ID];SharedAccessKey=[KEY]",
      "simulationSettings": {
        "enableLatencyTests": false,
        "latencyTestsFrecuency": 10,
        "enableTelemetryMessages": false,
        "telemetryFrecuency": 60,
        "enableErrorMessages": false,
        "errorFrecuency": 60,
        "enableCommissioningMessages": false,
        "commissioningFrecuency": 60,
        "enableTwinReportedMessages": false,
        "twinReportedMessagesFrecuency": 60,
        "enableReadingTwinProperties": false,
        "enableC2DDirectMethods": true,
        "enableC2DMessages": true,
        "enableTwinPropertiesDesiredChangesNotifications": true
      }
    },
    {
      "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];ModuleId=[MODULE ID];SharedAccessKey=[KEY]",
      "simulationSettings": {
        "enableLatencyTests": false,
        "latencyTestsFrecuency": 10,
        "enableTelemetryMessages": false,
        "telemetryFrecuency": 60,
        "enableErrorMessages": false,
        "errorFrecuency": 60,
        "enableCommissioningMessages": false,
        "commissioningFrecuency": 60,
        "enableTwinReportedMessages": false,
        "twinReportedMessagesFrecuency": 60,
        "enableReadingTwinProperties": false,
        "enableC2DDirectMethods": true,
        "enableC2DMessages": true,
        "enableTwinPropertiesDesiredChangesNotifications": true
      }
    }
  ]
}

Note

Emission intervals are set in seconds.

Configuration files reminder

appsettings.json

{
 "Logging": {
   "LogLevel": {
     "Default": "Warning"
   }
 }
}

devicesettings.json

{
  "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];SharedAccessKey=[KEY]",
  "simulationSettings": {
    "enableLatencyTests": false,
    "latencyTestsFrecuency": 10,
    "enableDevice": true,
    "enableModules": true,
    "enableTelemetryMessages": false,
    "telemetryFrecuency": 60,
    "enableErrorMessages": false,
    "errorFrecuency": 60,
    "enableCommissioningMessages": false,
    "commissioningFrecuency": 60,
    "enableTwinReportedMessages": false,
    "twinReportedMessagesFrecuency": 60,
    "enableReadingTwinProperties": false,
    "enableC2DDirectMethods": true,
    "enableC2DMessages": true,
    "enableTwinPropertiesDesiredChangesNotifications": true
  }
}

Properties are quite self-explanatory.

Note

Emission intervals are set in seconds.

modulessettings.json

{
 "modules":[
    {
      "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];ModuleId=[MODULE ID];SharedAccessKey=[KEY]",
      "simulationSettings": {
        "enableLatencyTests": false,
        "latencyTestsFrecuency": 10,
        "enableTelemetryMessages": false,
        "telemetryFrecuency": 60,
        "enableErrorMessages": false,
        "errorFrecuency": 60,
        "enableCommissioningMessages": false,
        "commissioningFrecuency": 60,
        "enableTwinReportedMessages": false,
        "twinReportedMessagesFrecuency": 60,
        "enableReadingTwinProperties": false,
        "enableC2DDirectMethods": true,
        "enableC2DMessages": true,
        "enableTwinPropertiesDesiredChangesNotifications": true
      }
    },
    {
      "connectionString": "HostName=[IOTHUB NAME].azure-devices.net;DeviceId=[DEVICE ID];ModuleId=[MODULE ID];SharedAccessKey=[KEY]",
      "simulationSettings": {
        "enableLatencyTests": false,
        "latencyTestsFrecuency": 10,
        "enableTelemetryMessages": false,
        "telemetryFrecuency": 60,
        "enableErrorMessages": false,
        "errorFrecuency": 60,
        "enableCommissioningMessages": false,
        "commissioningFrecuency": 60,
        "enableTwinReportedMessages": false,
        "twinReportedMessagesFrecuency": 60,
        "enableReadingTwinProperties": false,
        "enableC2DDirectMethods": true,
        "enableC2DMessages": true,
        "enableTwinPropertiesDesiredChangesNotifications": true
      }
    }
  ]
}

Note

Emission intervals are set in seconds.

Messages

The messages below are basic proposals to start working. You will probably need to adjust them to each of your IoT projects taking into account your customers' requirements.

Tip

deviceId and messageType fields have been included in the message to simplify processes in the backend side. Indeed, even though these two properties can be reachable in the metadata of the message, having them inside the message itself brings simplicity to richer scenarios (ex: gateways sending messages in behalf of devices) and storing that information in the repository (autosufficient message). Debugging and message routing in Microsoft Azure IoT Hub are other of the fields that benefit from this practice.

This being said, if at some point you need to avoid including that information in the message, feel free to do it. Routing could also work on metadata.

Note

Microsoft Azure IoT Hub does not require the devices send JSON messages. If your project requires other formats (ex: very small hexadecimal messages, frequent in IoT small devices), Microsoft Azure IoT Hub has no problem in processing them. Also, you can still use Azure IoT Device Simulator; it will require small code changes in the Message Service but all the remaining implemented features remain valid.

Warning

Not all the IoT projects can implement C2D features. Devices and communication platforms have to take into account the requirements of such features.

commissioning.json

{
  "deviceId": "",
  "messageType": "commissioning",
  "timestamp": 13456,
  "userId": "",
  "building": {
    "buildingId": "",
    "floor": "",
    "departmentId": "",
    "roomId": null
  }
}

Warning

No moduleId is required since commissioning is related to devices and only devices (functional choice).

error.json

{
  "deviceId": "",
  "moduleId": "",
  "messageType": "error",
  "errorCode": "code",
  "errorSeverity": "severity",
  "errorStatus": "status",
  "timestamp": 13456
}

Warning

moduleId can be empty in case the message is sent by a device.

measureddata.json

We consider each item (device or module) can send many "measured data" in a single message. This responds to data flow optimization scenarios and explains the chosen message schema.

{
  "deviceId": "",
  "moduleId": "",
  "timestamp": 0,
  "schemaVersion": "v1.0",
  "messageType": "data",
  "data": [
    {
      "timestamp": 0,
      "propertyName": "P1",
      "propertyValue": 35,
      "propertyUnit": "T",
      "propertyDivFactor": 1
    },
    {
      "timestamp": 0,
      "propertyName": "P2",
      "propertyValue": 1566,
      "propertyUnit": "U",
      "propertyDivFactor": 10
    }
  ]
}

Warning

moduleId can be empty in case the message is sent by a device.

Evolutivity

If you need to customize messages, their generation relies on services that implement the interfaces below:

ITelemetryMessageService for telemetry or measured data
IErrorMessageService
ICommissioningMessageService

If you need richer business logic or more evolved dynamic ways to generate messages, you can easily use your own implementation of these interfaces and update the IoC/DI.

The method that registers services is located in the Program.cs class:

RegisterMessagingServices

Replace the lines below with your own implementation:

services.AddTransient<ITelemetryMessageService, SimpleTelemetryMessageService>();
services.AddTransient<IErrorMessageService, SimpleErrorMessageService>();       
services.AddTransient<ICommissioningMessageService, SimpleCommissioningMessageService>();

Glossary

A few word explanations to be sure they are understood in the context of this document.

Commissioning

Commissioning represents the act of linking a provisioned device and a user (or user related information).

Provisioning

Provisioning represents the action of creating an identity for the device in the Microsoft Azure IoT Hub.

Azure IoT related vocabulary

Twin

Device twins store device state information including metadata, configurations, and conditions. Microsoft Azure IoT Hub maintains a device twin for each device that you connect to IoT Hub.

Similarly, module twins play the same role thant device twins but at module level.

Twins contain 3 main sections:

Tags
Properties (Desired)
Properties (Reported)

For more details, follow the links provided.

Twin Desired properties

Used along with reported properties to synchronize device configuration or conditions. The solution back end can set desired properties, and the device app can read them. The device app can also receive notifications of changes in the desired properties.

Twin Reported properties

Used along with desired properties to synchronize device configuration or conditions. The device app can set reported properties, and the solution back end can read and query them.

Files

Help.md

Latest commit

History

Help.md

File metadata and controls

Azure IoT Device Simulator - Help

Application

Features

Device

D2C

Messages

Twins

C2D

Direct Methods

Messages

Twins

Desired

Tags and Microsoft IoT Hub Jobs

Modules

M2C

Messages

Twins

C2M

Direct Methods

Messages

Twins

Desired

How does the simulator work?

Description

Runing the simulator

Runing .NET Core application

Runing Docker container

Configurations

Application

Device

Modules

Configuration files reminder

appsettings.json

devicesettings.json

modulessettings.json

Messages

commissioning.json

error.json

measureddata.json

Evolutivity

Glossary

Commissioning

Provisioning

Azure IoT related vocabulary

Twin

Tags

Twin Desired properties

Twin Reported properties