The file simulation.json defines the simulation to run. It allows to:

  • Define groups and devices to simulate inside the groups object.

  • Configure how to interact with the user application inside the user_app object.

Property Required Type Description

groups

Array of objects

List of device groups to simulate.

Must include the definition of at least one item.

See groups object.

user_app

Object

Defines how the Digi IoT Device Simulator interacts with the user application in case any custom behavior has to be provided to the groups.

Only required if:

See user_app object.

simulation.json example

{
    "groups": [
        {
            "name": "Trucks",
            "profile_id": "truck",
            "num_devices": 5,
            "setup": {
                "vendor_id": "FE080003",
                "type": "refrigerated-truck",
                "initial_device_id": "FF0FF0FF-FF0FF001",
                "name_prefix": "Truck",
                "fw_version": "1.0.0.0"
            },
            "mobility": {
                "type": "auto",
                "routes_id": "truck_routes",
                "random_start": true,
                "stops_wait_time": "PT2M"
            }
        },
        {
            "name": "Bikes",
            [...]
        }
    ],
    "user_app": {
        "initial_dr_port": 5577,
        "initial_dp_port": 6577,
        "log_level": "info"
    }
}

1. groups

groups is a list of device groups to simulate.

groups property Required Type Description

name

String

Name of the group to identify them.

All the simulated devices of the group will be assigned to this group when registered in Remote Manager.

It must contain at least one character but no more than 80. It can contain letters, numbers, dash, underscore, period and space, [\w\. -]{1,80}.

profile_id

String

Device profile associated to the group. This defines the list of features the devices of the group will have.

This identifier must be the name without extension of a JSON file inside the profiles directory of your simulation. It must have a maximum on 100 characters between letters, numbers, dash, underscore, and period, ^[\w\.-]+$.

If the corresponding file is not found, the simulation fails to start.

See Device profiles definition.

num_devices

Integer

Number of devices to be simulated and registered inside this group.

It must be between 1 and 200.

The maximum number of simulated devices is 200. To increase this limit, contact your Digi Sales Representative.

setup

Object

Initial setup information of the group.

This is the minimum required information, specific to the group, that allows to extrapolate all the required information to build the group.

See setup object.

mobility

Object

Mobility information.

For each group, a user can define a list of routes in JSON format or configure it to ask the custom application for locations. See Routes for your devices.

See mobility object.

1.1. setup

setup property Required Type Description

vendor_id

String

Vendor ID of the group devices.

It must be an hexadecimal string.

Only the available values from this list are valid:

  • FE080003: Digi Embedded Yocto

  • FE000006: XBee Cellular

type

String

Type of devices in the group. It defines the name of the device model.

It must contain at least one character and a maximum of 255.

initial_device_id

String

Initial device ID.

A device ID is specified as four groups of eight hexadecimal digits separated by dashes, ^[A-F0-9]{8}\-[A-F0-9]{8}$.

This value only specifies the last 2 chunks, the rest are automatically generated by the IoT Device Simulator.

The value in this field represents the last half of the ID of the first simulated device in the group. For subsequent devices, the value is incremented to select the next available device ID.

name_prefix

String

Device name prefix.

This is the prefix for the name of the devices in the groups. The final name include an auto incremented index.

This prefix can have 1 to 52 letters, numbers, and hyphens. It may not start with a hyphen.

^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,50}[a-zA-Z0-9])?$

fw_version

String

Firmware version of the devices in the group.

A version number is formed by 4 numeric values separated by a dot, ^(?:[0-9]+\.){3}[0-9]+$.

1.2. mobility

mobility property Required Type Description

type

String

Routes generation type.

Possible values:

  • auto: The IoT Device Simulator automatically generates routes based on the set of files located in the routes subdirectory specified in routes_id.

  • custom: The IoT Device Simulator asks a custom application for a new location every sampling_rate. This application is configured in the user_app object.

auto if it is not defined.

See Routes for your devices.

routes_id

String

Set of routes associated to the group.

Only for auto type.

This identifier must be the name of a sub-directory of the routes folder in your simulation.

Every file inside a routes directory represents a valid route. When the simulation starts, the devices of the group choose random routes amongst those in the configured directory for the group.

If the corresponding directory is not found, the simulation fails to start.

See Routes for your devices.

random_start

Boolean

Whether the devices of the group should start at a random point in the route or not.

Only for auto type.

false if it is not defined.

stops_wait_time

String

Waiting time on each stop of the route.

Only for auto type.

It must be ISO 8601 string for duration, ^PT(?=\d)(\d{1,3}H)?(\d{1,3}M)?(\d{1,3}S)?$.

Minimum value is 1 second.

Each route has a minimum of two stops, the beginning and the end. Optionally, you can add stops throughout the route, see Routes for your devices.

sampling_rate

String

Rate at which location is sampled, that is when new location coordenates are going to be generated.

Only for custom type.

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.

2. user_app

user_app property Required Type Description

initial_dr_port

Integer

Port for data request communication between the IoT Device Simulator and your application.

Only one available port should be set.

initial_dp_port

Integer

Port for data streams communication between the IoT Device Simulator and your application.

Only one available port should be set.

log_level

String

Log level for the user application:

  • error

  • warn

  • info

  • debug

  • trace

By default, if this is not specified, log level is info.

The ports provided here are used by the IoT Device Simulator to establish communication channels with the user application. Whenever you select one, make sure it is free, and at least the next subsequent 10 ports.

Data requests and data streams do not share ports, so make sure that each one has at least 10 ports free for usage.

3. Usage examples

Here is a list of simple examples that you can test on your own.

Define four groups that use different profiles

This configuration defines a total of four groups:

  • Each group has a different number of devices.

  • Last two groups define the same features for their devices by using the same profile, profile3. This means that there must be a file called profile3.json inside the profiles directory of the simulation.

  • Last group is the only one without a mobility specification, their devices do not have a location defined.

  • The rest of the groups have their routes defined inside routes_01, routes_02, and routes_03 directories of the routes folder of the simulation.

{
    "groups": [
        {
            "name": "Group 01",
            "profile_id": "profile1",
            "num_devices": 3,
            "setup": {
                "vendor_id": "FE080003",
                "type": "DEY device",
                "initial_device_id": "FF0FF0FF-FF0FF001",
                "name_prefix": "93 - 1",
                "fw_version": "1.0.0.0"
            },
            "mobility": {
                "type": "auto",
                "routes_id": "routes_01",
                "random_start": true,
                "stops_wait_time": "PT20M"
            }
        },
        {
            "name": "Group 02",
            "profile_id": "profile2",
            "num_devices": 2,
            "setup": {
                "vendor_id": "FE000006",
                "type": "XBee3 Cellular LTE-M/NB-IoT Global",
                "initial_device_id": "EE0EE0EE-EE0EE001",
                "name_prefix": "cell - 1",
                "fw_version": "17.4.1.10"
            },
            "mobility": {
                "type": "auto",
                "routes_id": "routes_02",
                "random_start": true,
                "stops_wait_time": "PT10M"
            }
        },
        {
            "name": "Group 03",
            "profile_id": "profile3",
            "num_devices": 1,
            "setup": {
                "vendor_id": "FE080003",
                "type": "DEY device",
                "initial_device_id": "AA0AA0AA-AA0AA001",
                "name_prefix": "8X - 1",
                "fw_version": "1.0.0.0"
            },
            "mobility": {
                "type": "auto",
                "routes_id": "routes_03",
                "random_start": true,
                "stops_wait_time": "PT1H"
            }
        },
        {
            "name": "Group 04",
            "profile_id": "profile3",
            "num_devices": 4,
            "setup": {
                "vendor_id": "FE080003",
                "type": "DEY device",
                "initial_device_id": "BB0BB0BB-BB0BB001",
                "name_prefix": "8MM - 1",
                "fw_version": "1.0.0.0"
            }
        }
    ]
}

Define two groups with the same configuration

In this case two groups are defined:

  • Each group with ten simulated devices.

  • Both use the same profile, profileA, and the same mobility configuration. This means that there must be a file called profileA.json inside the profiles directory of the simulation.

{
    "groups": [
        {
            "name": "Group A",
            "profile_id": "profileA",
            "num_devices": 10,
            "setup": {
                "vendor_id": "FE080003",
                "type": "DEY device",
                "initial_device_id": "AA0AA0AA-AA0AA001",
                "name_prefix": "8X - 1",
                "fw_version": "1.0.0.0"
            },
            "mobility": {
                "type": "auto",
                "routes_id": "routes_A",
                "random_start": true,
                "stops_wait_time": "PT1H"
            }
        },
        {
            "name": "Group B",
            "profile_id": "profileA",
            "num_devices": 10,
            "setup": {
                "vendor_id": "FE080003",
                "type": "DEY device",
                "initial_device_id": "BB0BB0BB-BB0BB001",
                "name_prefix": "8MM - 1",
                "fw_version": "1.0.0.0"
            },
            "mobility": {
                "type": "auto",
                "routes_id: "routes_A",
                "random_start": true,
                "stops_wait_time": "PT1H"
            }
        }
    ]
}