Kelvin Modbus Bridge App¶

Modbus is a serial communication protocol developed by Modicon for use with its programmable logic controllers (PLCs). Modbus is often used to connect a supervisory computer with a remote terminal unit (RTU) in supervisory control and data acquisition (SCADA) systems. Modbus is transmitted over serial lines between devices.

The Kelvin Modbus Bridge App is a Kelvin App runs on KICS. It is a data connector application that connects and communicate with devices running Modbus protocol.

Metrics mapping¶

The metrics map will map the Modbus addresses to the inputs and outputs of the application.

Each metric has the following general configurations:

Name	Description	Default/Required
`name`	The metric name	Required
`asset_name`	The asset name associated to the metric name	Required
`data_type`	The data type of the metric	Required
`access`	Whether the metric is `RO` (read-only) or `RW` (read-write)	Default: `RO`

Name	Applicable to	Description
`protocol_type`	All	The primitive data type
`address`	All	The Modbus' register address to be read
`polling_rate`	All	The register polling period
`stroke_number`	Stroke number	Indicates the address is the stroke number
`buffer_address`	Downhole/surface	The first address of the buffer
`buffer_size`	Downhole/surface	The size of the buffer

Example

Below is an example of a Modbus Bridge application's metrics_map configuration for dynacards, the one present in the downloaded configuration file.

app:
  bridge:
    # ...

    metrics_map:
    - name: stroke_number
      asset_name: modbus_simulator
      data_type: raw.uint32
      configuration:
        address: 2518
        protocol_type: uint32
        polling_rate: 15
        stroke_number: true
    - name: downhole
      asset_name: modbus_simulator
      data_type: raw.dynacard
      configuration:
        protocol_type: downhole
        polling_rate: 15
        buffer_address: 46165
        buffer_size: 200
    - name: surface
      asset_name: modbus_simulator
      data_type: raw.dynacard
      configuration:
        protocol_type: surface
        polling_rate: 15
        buffer_address: 45756
        buffer_size: 400

Global configuration¶

General¶

General configuration related to the Modbus connection.

Name	Description
`minus_offset`	Modbus register offset (`1` is the most commonly used value)
`timestamp_sync`	Timestamp synchronization across all metrics read within the same polling period (`true` or `false`)
`chunk_size`	Maximum amount of registers to read per request (`125` for Serial and `123` for TCP)
`debug`	`libmodbus` debug logs (`true` or `false`)

Example

app:
  bridge:

    configuration:
      minus_offset: 0
      chunk_size: 120
      timestamp_sync: false
      debug: false

      connection:
        # ...

Connection¶

Modbus connection configuration that can be applied to both the TCP and serial connection.

Common¶

Name	Description
`type`	Establish the connection to ModBus via "tcp" or "serial"
`slave_id`	Slave ID of the remote device to talk in Master mode (`1`-`255`)
`timeout`	Timeout interval (in seconds) used to wait for a response
`reconnect_delay`	Delay (in seconds) before attempt to reconnect to the Modbus Slave
`retry_attempts`	Read requests maximum retry attempts
`retry_delay`	Delay (in seconds) between read requests retry attempts

Example

app:
  bridge:

    configuration:
      # ...

      connection:
        slave_id: 255
        timeout: 5
        reconnect_delay: 15
        retry_attempts: 0
        retry_delay: 0

        type: tcp
          # ...

TCP¶

To connect to Modbus via TCP, the connection type must be tcp.

Name	Description
`ip`	IP address of the server to which the client wants to establish a connection
`port`	Port to use (Modbus TCP default is `502`)

The ip field can be an IP address as well as an host name. Inside both KICS and KSDK's emulation environment, that host name may point to another running application. That name is <app-name/workload-name>.app.

Example

app:
  bridge:

    configuration:
      connection:
        # ...

        type: tcp
        tcp:
          ip: kelvin-modbus-simulator.app
          port: 502

Serial¶

To connect to Modbus via TCP, the connection type must be serial.

Name	Description
`serial_port`	Name of the serial port handled by the OS, i.e. `/dev/ttyS0` or `/dev/ttyUSB0`
`baudrate`	Baud rate of the communication, i.e. `9600`, `19200`, `57600`, `115200`, etc
`data_bits`	Number of bits of data, the allowed values are `5`, `6`, `7` and `8`
`parity`	`N` for none, `E` for even, and `O` for odd
`stop_bits`	The bits of stop, the allowed values are `1` and `2`
`serial_mode`	Serial line communication, `RS232` and `RS485`
`rts_mode`	(RS485 only) Mode to communicate on a RS485 serial bus, `UP` (default) or `DOWN`
`rts_delay`	(RS485 only) Request to send delay period (in seconds)
`error_recovery`	If set to `true`, it will attempt to reconnect when disconnected (not recommended for slave mode)

Example

app:
  bridge:
    configuration:
      connection:
        # ...

        type: serial
        serial:
          serial_port: /dev/ttyXRUSB1
          baudrate: 19200
          parity: N
          data_bits: 8
          stop_bits: 1