Overview

On this page you will find explanation of how and what can be configured using the json configuration. This json configuration can be used to initialize the Modbus Slave Device Simulator, but in addition this configuration can be used to create a Modbus Device. Here is how a json configuration file would look like. Actually the following example shows basically everything that might be configured. From now on, by Discrete Object we will mean a coil, or discrete input, by Register we will mean input or holding register and by Modbus Object we will mean any Discrete Object or Register.

Simulator Configuration

{

"deviceConfiguration": {

    "id": "1234567890",

        "oidPrefix": "1.3.6.1.4.1.46863.218",

        "type": "Modbus",

        "connections": [{

            "type": "TCP_IP",

            "port": "502"

        }]

    },

    "sensors": [{

        "id": "101",

        "address": 10,

        "objectType": "inputRegister",

        "dataDefinition": {

            "dataType": "int16",

            "valueType": "Measurement Value",

            "initialValue": 1000,

            "min": 10,

            "max": 100

        },

        "automation": {

            "values": [10, 20, 30, 40, 50, 60]

        }

    }, {

        "id": "102",

        "address": 50,

        "objectType": "holdingRegister",

        "dataDefinition": {

            "dataType": "int16",

            "valueType": "Measurement Value",

            "min": 100,

            "max": 1000,

            "factor": 10,

            "offset": 100000

        },

        "automation": {

            "values": [100, 200, 300, 400, 500]

        }

    }, {

        "id": "103",

        "address": 51,

        "objectType": "holdingRegister",

        "dataDefinition": {

            "dataType": "int32",

            "valueType": "Notification Value"

        },

        "dataAccessChannels": [{

            "type": "Modbus_TCP",

            "refreshRate": 2,

            "minimalMeaningfulValueDifference": 0.5,

        }],

        "automation": {

            "values": [100000, 200000, 3000000, 40000000]

        }

    }, {

        "id": "104",

        "address": 10,

        "objectType": "coil",

        "dataDefinition": {

            "dataType": "bool",

            "valueType": "Alarm",

            "referenceObjectId": "103",

            "valueChangeNotificationCondition": "valueIncremented"

        },

        "automation": {

            "values": [1, 1, 0, 0, 1, 0]

        }

    }, {

        "id": "105",

        "address": 11,

        "objectType": "coil",

        "dataDefinition": {

            "dataType": "bool",

            "valueType": "Warning"

        },

        "automation": {

            "values": [3, 2, 1, 0]

        }

    }, {

        "id": "106",

        "address": 13,

        "objectType": "discreteInput",

        "dataDefinition": {

            "dataType": "bool",

            "valueType": "Measurement Value"

        },

        "automation": {

            "values": [1, 0, 1, 0, 1, 0]

        }

    }, {

        "id": "107",

        "address": 14,

        "objectType": "discreteInput",

        "dataDefinition": {

            "dataType": "bool",

            "valueType": "Notification Value"

        }

    }, {

        "id": "108",

        "address": 510,

        "objectType": "inputRegister",

        "initialValue": "hi",

        "dataDefinition": {

            "dataType": "char[10]",

            "valueType": "Notification Value"

        },

        "automation": {

            "values": ["hello", "world"]

        }

    }, {

        "id": "109",

        "address": 516,

        "objectType": "holdingRegister",

        "dataDefinition": {

            "dataType": "int16",

        },

        "automation": {

            "values": [15, 20, 25, 30, 35, 40, 45, 50],

            "interval": 10

        }

    }, {

        "id": "110",

        "address": 12,

        "objectType": "coil",

        "dataDefinition": {

            "dataType": "char[5]",

            "valueType": "Warning"

        },

        "automation": {

            "values": ["11100", "101010"]

        }

    }, {

        "id": "111",

        "address": 17,

        "objectType": "coil",

        "dataDefinition": {

            "dataType": "int8",

            "valueType": "Warning"

        },

        "automation": {

            "values": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]

        }

    }, {

        "id": "112",

        "address": 25,

        "objectType": "coil",

        "dataDefinition": {

            "dataType": "char[1]",

            "valueType": "Warning"

        },

        "automation": {

            "values": ["1", "0", "0"]

        }

    }]

}

Configuration Description

Some of the items in the json configuration are used only when creating a Modbus Master Device with this configuration. In here we will describe only the ones used by the simulator.

We can split the configuration on two parts – the first one describes how the simulator can connect with the other devices and the second one describes the data model of the simulator.

1. General Device Parameters:
   • id – not actually used by the simulator itself.
   • oidPrefix – not used by the simulator
   • type – can be used to change the behaviour of the simulator. In here we will describe the usage of the "Modbus" simulator. If some of this behaviour does not fit some corner case we can extend or modify this behavior by providing additional simulator type
   • connections – This can be used to provide different connection type for the simulator. For now the only supported connection is Modbus TCP.
     • type – the type of the connection
     • port – the TCP/IP port on which the simulator will listen
2. Sensors – This json array describes fully the data model of the simulator. The idea behind the sensors is simple. In a real slave device some sensors would track some physical activity and write this in the data model. In our simulator the physical activity can be actually automated, but the principle is the same. The sensor gets some data and writes it somewhere in the device memory. This part of the memory can be a group of Discrete Inputs, a group of Coils, a group of Input Registers, or a group of Holding Registers. The implementation supports 65535 coils, 65535 discrete inputs, 65535 input registers and 65535 holding registers. An important point is that two sensors can overlap.
   • id – the id of the sensor. It really needs to be unique within the device and should be used when accessing the device via the API and not via Modbus.
   • address – the address of the first Modbus Object corresponding to this sensor. Since the sensors can overlap it is very important to take care of the addressing to avoid unwanted and even strange results.
   • objectType – Defines the Modbus Objects that this sensor is responsible for, i.e. whether this sensor writes to Discrete Objects, Coils, Input Registers or Holding registers. The available values are "discreteInput", "coil", "holdingRegister", and "inputRegister".
   • dataDefinition – Describes some properties of the data that this sensor writes. Basically instructs the simulator how many objects it will cover and how to transform the data when reading from the data model or when writing to the data model.
     • dataType – The type of the data that this sensor produces. The available types are "bool", "int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "enum", "float", "double", "timestamp32", "timestamp64", and char*, where * means count of ASCII characters.
     • initialValue – initializes the device with some initial value. If not set all of the sensors are initialized to 0.
   • automation – instructs the sensor how and when to update the values. Currently there are two types of automation. The first one updates the values once a value is read via Modbus. The other one changes the values on equal intervals. To activate the automation one needs to provide the "automation" object, and it must contain "values" object.
     • values – The values that will be written by the automation. If this is not added in the automation object, the automation will not be activated. If the "interval" parameter Is not presented this is going to activate the first mode in which the values are changed after read via Modbus. The update of the values is circular, meaning it starts with the first one, then the next one and when the last value is read, the first one will be written again.
     • interval – activates the periodic value change in the sensor and disables the changes of the values after read via Modbus. It still requires values array. This automation is also circular.

Data Types

The Simulator does not actually make any difference between the data types. These data types are used when configuring a device to communicate with this simulator. The various data types are used exclusively to get the count of registers the sensor is going to occupy.

Here we will add detailed explanation of the supported data types.

• bool – used to store single flag. Takes single Modbus Object.
• int8 – A signed 8-bit integer value. Takes single Register or eight Discrete Objects.
• uint8 – An unsigned 8-bit integer value. Takes single Register or eight Discrete Objects.
• int16 – Signed 16-bit integer value. Takes single Register or sixteen Discrete Objects.
• uint16 – An unsigned 16-bit integer value. Takes single Register or sixteen Discrete Objects.
• int32 – Signed 32-bit integer value. Takes two Registers or thirty-two Discrete Objects.
• uint32 – Unsigned 32-bit integer value. Takes two Registers or thirty-two Discrete Objects.
• int64 – Signed 64-bit integer value. Takes four Registers or sixty-four Discrete Objects.
• uint64 – Unsigned 64-bit integer value. Takes four Registers or sixty-four Discrete Objects.
• enum – Takes single Register or sixteen Discrete Objects. Does not make huge difference for the simulator itself.
• float – Single precision IEEE-754 floating point number. Uses 32-bits, so this takes two Registers or thirty-two Discrete Objects.
• double – Double precision IEEE-754 floating point number. Uses 64-bits, so this takes four Registers or sixty-four Discrete Objects.
• timestamp32 – 32-bit representation of a Unix timestamp. Takes two Registers or thirty-two Discrete Objects.
• timestamp64 – 64-bit representation of a Unix timestamp. Takes four Registers or sixty-four Discrete Objects.
• char[<LENGTH>] – The <LENGTH> is the maximal characters count in the array, when Registers are used. In this case this sensor occupies <LENGTH> / 2 + 1 Registers. When Discrete objects are used then this sensors covers <LENGTH> Discrete Objects.

Value to Modbus Objects Mapping

The simulator understands two types of Java objects – String and Long. The configuration parser converts the Double and Float values to Long value, and then provides these to the simulator. Here is how the Long and String values are converted to Registers and Discrete Objects.

Long Value

As Registers

The Least significant 16 bits are taken as an integer value and are written in the base address of the sensor, if the sensor occupies more than one Register, then the next 16-bit are taken and written in the nest register and so on, until all of the registers are filled.

As Discrete Object

The least significant bit is taken and written in the first Discrete Object, then the next bit is written in the next Discrete Object and so on, until all of the Discrete Objects assigned to this sensor are written.

String Value

As Registers

The first character is put as the most significant byte and the next one as the least significant byte of the first register. If the sensor spans on more than one register the next two characters are written in the next register and so on, until all of the registers are filled.

As Discrete Object

If the first character is '1' then the first Discrete Object is raised, i.e. 1 is written in it. otherwise it is a zero. If there is another discrete object, and another character they are processed in the same manner. If the length of the String value is less than the Discrete Objects count then these discrete objects are filled with zeroes. There is some small trick here. If the string itself equals "true" then all of the Discrete Objects will be filled with ones.