Each file inside the data_streams directory of the simulation defines a set of data streams that the simulated devices of a group support.

Each data stream set can be used by one or more profiles defined in the profiles directory. They are identified by the file name without extension in the data_streams_id property. The file name must have a maximum on 100 characters between letters, numbers, dash, underscore, and period, ^[\w\.-]+$.

See Device profiles definition.

Data streams set example

{
    "system_monitor/frequency": {
        "type": "integer",
        "units": "kHz",
        "sampling_rate": "PT1M",
        "data_source": {
            "mode": "range",
            "initial_value": "166000000",
            "limits": "80000000,166000000",
            "deviation": "random"
        }
    },
    "temperature": {
        "type": "double",
        "units": "C",
        "sampling_rate": "PT5S",
        "data_source": {
            "mode": "command",
            "timeout": 5
        }
    },
    [...]
}

1. Data stream

Each data stream is defined in a block using its data stream identifier as the property name. These identifiers must be unique in the set.

For example:

{
    "system_monitor/frequency": {
        [...]
    },
    "temperature": {
        [...]
    },
    [...]
}
Property Required Type Description

type

String

Data type in the data stream.

Possible values are:

  • integer

  • long

  • float

  • double

  • string

  • json

  • geoson

units

String

String to define the unit of the data in the stream, such as, seconds, C, etc.

If it is not defined, no units are uploaded for the data stream to Remote Manager.

sampling_rate

String

Rate at which data is sampled, that is when samples are going to be generated.

It must be an ISO 8601 duration string, ^PT(?=\d)(\d{1,3}H)?(\d{1,3}M)?(\d{1,3}S)?$, with a minimum value of 1 second.

A simulated device samples data at the configured rate in the corresponding stream (sampling_rate), but the upload depends on the configured method:

  • Batch upload: Samples are accumulated until the device has to upload the data to Remote Manager.

  • Individual upload: Samples are uploaded as they are generated.

See data_streams object in profiles definition.

data_source

Object

Configuration to generate simulated data.

Simulated data samples can be provided by:

  • The IoT Device Simulator.

    It can generate:

    • static values: integer, long, float, double, string

    • incremental values: integer, long, float, double

    • range values: integer, long, float, double

  • A custom application.

    The IoT Device Simulator can launch a custom application to get values.

See data_source object.

For samples generated by the IoT Device Simulator (in static, incremental, and range modes), the configured sampling rate should correspond to the moment when the device must provide a new value. Note that these modes will make the simulator generate new device data at regular intervals, not based on specific conditions.

In contrast, for samples generated by an application (command mode), the configured sampling rate represents how often the IoT Device Simulator checks with the user application for new data to sample. The user application can either send data based on information provided by the IoT Device Simulator or respond that there is no new data to upload. See Upload customized data samples.

1.1. data_source

data_source property Required Type Description

mode

String

This value determines how simulated data samples are generated.

Possible values:

  • static: The IoT Device Simulator always provides initial_value as next sample data.

  • incremental: The IoT Device Simulator generates incremental samples starting from initial_value and incrementing deviation value. Only for integer, long, float, double data streams types.

  • range: The IoT Device Simulator generates samples in a provided range of values (limits) with a given delta (deviation) starting from initial_value. Only for integer, long, float, double data streams types.

  • command: A custom application provides the sample values.

    The application is configured in simulation.json file. See user_app object and Custom code implementation.

initial_value

String

Initial sample value.

It must be a numeric as a string.

Applicable to static, incremental, and range modes.

limits

String

Minimum and maximum values a range sample can take.

It must contain a minimum and a maximum value separated by a comma.

Applicable to range mode.

deviation

String

This is a delta value used by the IoT Device Simulator to generate the next samples.

Applicable to incremental and range modes.

It must contain:

  • A numeric value as a string:

    • For incremental mode, the next value is calculated by increasing last sample by this delta.

    • For range mode, the next value is calculated by increasing or decreasing last sample by this value.

  • random:

    • For incremental mode, the next value is calculated by increasing last sample by a random number between negative current value and positive current value.

    • For range mode, the next value is calculated by increasing or decreasing last sample by a random number between.

Given an integer data type, if the deviation is 2, each subsequent sample starting of by the initial value will be 2 units greater or lower than the previous sampled value but always within the valid values for the specific stream. Not applicable to command type data_source.

By default, if it is not defined, its value is random.

timeout

Integer

The maximum timeout in seconds to quit the execution of the command to avoid deadlocks.

Applicable to command mode.

2. Usage examples

Sample incremental data periodically

This example simulates a incremental data value. For example, we can simulate the uptime of a simulated device.

Define the stream by including:

  1. The stream identifier, system_monitor/uptime.

  2. The data type, integer.

  3. The units, seconds.

  4. The sampling frequency, sampling_rate, a sample per 30 seconds.

  5. The generation mode, incremental:

    1. Set the initial sample value, 0.

    2. Configure the deviation between samples, the increment, 1.

In this case, we are sampling the uptime of a device as an integer value in seconds every second.

This data is sampled at the configured frequency in sampling_rate, but it is uploaded to Remote Manager at batch_upload_frequency in the data_streams_configuration section of the profile.

{
    "system_monitor/uptime": {
        "type": "integer",
        "units": "seconds",
        "sampling_rate": "PT30S",
        "data_source": {
            "mode": "incremental",
            "deviation": "1",
            "initial_value": "0"
        }
    }
}

Sample data in a range periodically

A use case for a data stream may be to read data periodically from a diagnostics file or a sensor. An example of this behavior is the sampling of free memory of your simulated device.

Define the stream by including:

  1. The stream identifier, system_monitor/free_memory.

  2. The data type, double.

  3. The units, kB.

  4. The sampling frequency, sampling_rate, a sample per minute.

  5. The generation mode, range:

    1. Set the initial sample value, 6000000.0.

    2. Configure the deviation between samples, the increment, 200.0.

    3. Set the lower and higher limits, 0.0 and 6000000.0.

In this case, we are sampling the free memory of a device as a double value in kB every minute. Its values can go from 0 to 6000000 kB and each sample can differ from the previous with 200 kB.

This data is sampled at the configured frequency in sampling_rate, but it is uploaded to Remote Manager at batch_upload_frequency in the data_streams_configuration section of the profile.

{
    "system_monitor/free_memory": {
        "type": "double",
        "units": "kB",
        "sampling_rate": "PT1M",
        "data_source": {
            "mode": "range",
            "deviation": "200.0",
            "limits": "0.0,6000000.0",
            "initial_value": "6000000.0"
        }
    },
    [...]
}

Generate samples in code

There are scenarios where incremental and range samples generation are not enough. In those cases, it is possible to provide sample values from code, using an application. See Custom code implementation to get more information about the required code.

For example, simulate data from a temperature sensor that when is out of the a range of values, the sample must be uploaded immediately to Remote Manager. To satisfy these requisites some code must be provided and the stream must be configured to use your code:

  1. The stream identifier, temperature.

  2. The data type, double.

  3. The units, C.

  4. The sampling frequency, sampling_rate, a sample every ten minutes.

  5. The generation mode, command. The simulator asks for a new sample every sampling_rate period of time.

  6. The timeout. Maximum amount of time in seconds the simulator waits for a sample from the application.

This data is sampled at the configured frequency in sampling_rate, but it is uploaded to Remote Manager at batch_upload_frequency in the data_streams_configuration section of the profile.

{
    "temperature": {
        "type": "double",
        "units": "C",
        "sampling-rate": "PT10M",
        "data_source": {
            "mode": "command",
            "timeout": 5
        }
    },
    [...]
}