Configure a facility device simulator

You can set up a facility device simulator to generate telemetry data for a specific facility.

Prerequisites

Important: The simulator currently only supports Azure IoT Hub and AWS IoT Core. GCP has been deprecated.

Before you create a facility device simulator and run a scenario, you must first:

Set up and run a scenario

You must set up and run a scenario for your facility device simulator to work. A scenario is a series of telemetry events produced by a collection of devices.

To set up and run a scenario, see the following steps:

  1. Create a scenario configuration file with the following attributes:
    • WorkspaceId: the ID of the owner of the scenario.
    • FacilityId: the facility being simulated.
    • Devices: a list of devices related to the facility.
    • SinkSetting: Scenario level telemetry sink configuration describing where the telemetry data is sent to.
    • The facility simulator will generate ScenarioId for the scenario, so this value should not be set when creating one.
  2. Call the POST api/v1/workspaces/{workspaceId}/scenarios endpoint to create the scenario. The scenario object in the response will include the newly generated scenario ID.
  3. Call the POST api/v1/workspaces/{workspaceId}/scenarios/{scenarioId}/start endpoint to run the scenario.

Note: you can only run one scenario for a specific facility at a time.

Device configuration

You can configure a list of devices related to the facility. Your Devices list of objects can include the following attributes:

  • DataSource: where the telemetry data for the devices comes from.
  • Schedule: the frequency at which the devices emit events.
  • DeviceSinkSetting: the part of the telemetry sink configuration used to create telemetry sinks specific to the devices.
  • Type: Type of the device used to group together similar devices (ex.: Solar panels).

Schedule configuration

You can configure the frequency of each telemetry event and limit the number of times the events are emitted through the following Schedule attributes:

  • Frequency: how often a telemetry event is emitted. For example, 10s means an event is emitted every 10 seconds.
  • Repeats: how many times an event is emitted for your defined frequency. If you don't specify a number of repeats, the device emits the event continuously until you stop the scenario from running.

Data source configuration

The simulated telemetry data is sourced from data sources, which can be either file based or dynamic.

Dynamic data source configuration

You can use a dynamic data source to configure telemetry data without replayable sample data through the following DataSource attributes:

  • Header: a list of the telemetry fields.
  • Values: a list of configurations that define how values for a specific telemetry field are generated.
File data source configuration

You can use a file data source to configure telemetry data using replayable sample data. To replay a telemetry file, you must first save it to the database using the telemetryFile endpoints. When you use this file data source, the simulator goes through the telemetry file's lines to retrieve telemetry data. When the simulator reaches the end of the telemetry file, it restarts the process. Set which file to use as a data source with the following DataSource attributes:

  • FileName: Name of the telemetry file. This is unique within a given workspace.
  • Format: File format. Currently the only supported format is CSV.

SinkSetting configuration

Currently there are two supported telemetry sink types in the simulator. AzureMqtt and AwsMqtt send telemetry data to their respective cloud MQTT topics.

Azure value configuration

If you choose to set up your facility device simulator with Azure, you must update the Value attribute with the following:

  • PrivateKeyPemSecret: Name of the secret generated by the user secret endpoint when the secret was added.
  • IotHubHostName: Name of the host.
  • SharedAccessPolicyName: Name of the access policy used to create and access devices in the Azure IoT Hub instance. Optional. If not set, the default facilitysimulator value is used. In this case, a shared access policy with this name must exist in the Azure IoT Hub instance in order for the simulator to access it.

AWS value configuration

If you choose to set up your facility device simulator with AWS IoT Core, you must update the Value attribute with the following:

  • ThingGroupName: Name of the facility that groups together the specified devices.
  • Region: AWS region where the resources are configured (for example, us-east-1).
  • PrivateKeyId: Name of the secret ID generated by the user secret endpoint when the value was added.
  • PrivateKeyPemSecret: Name of the secret value generated by the user secret endpoint when the value was added.

Example

Refer to the following code sample for an example of the scenario creation request:

{
    "FacilityId": "4aa38d3c-026e-48df-9f24-6a7762fb344b",
    "WorkspaceId": "4a638d3c-026e-48df-9f24-6a7762fb344b",
    "Devices": [
        {
            "Name": "light_767797",
            "Id": "light_767797",
            "DataSource": {
                "TypeDiscriminator": "Dynamic",
                "TypeValue": {
                    "Header": "Temperature,PowerConsumed,Status",
                    "Values": "[40..70],[0..0.5],[1,0]"
                }
            },
            "Schedule": [
                {
                    "Frequency": "1s",
                    "Repeats": 100
                }
            ],
            "DeviceSinkSetting": {
                "DeviceName": "light_767797",
                "DeviceId": "light_767797"
            },
            "Type": "light"
        },
        {
          "Name": "windturbine_2134",
          "Id": "windturbine_2134",
          "DataSource": {
            "TypeDiscriminator": "File",
            "TypeValue": {
              "FileName": "windturbine_2134_telemetries.csv",
              "Format": "CSV"
            }
          },
          "Schedule": [
            {
              "Frequency": "10s"
            }
          ],
          "DeviceSinkSetting": {
            "DeviceName": "windturbine_2134",
            "DeviceId": "windturbine_2134"
          },
          "Type": "windturbine"
        }
    ],
    "SinkSetting": {
      "TypeDiscriminator": "AzureMqtt",
      "TypeValue": {
        "IotHubHostName": "testfacility.azure-devices.net",
        "PrivateKeyPemSecret": "user-secret_f46eca89-3215-4259-9a71-deeb4625371e_secret-name",
        "SharedAccessPolicyName": "facilitysimulator"
      }
  }
}