Greengrass Modbus TCP Protocol Adapter

This component provides the ability to read / write device data using Modbus TCP protocol.
The basic usage of this component is based on the same concept as Modbus RTU protocol adapter.
In addition, planning to provide read / write capabilities for asset data based on simple asset modeling feature.

Installation

You can either use a prebuilt binary or build yourself.

Use prebuilt binary

Download the following files from releases page.

• ModbusTCP-<version>.jar: Executable JAR file
• aws.greengrass.labs.ModbusTCP-<version>.yaml: Recipe template

Edit the following placeholders in recipe template.

• <MODBUS_TCP_HOST>: Host name or IP address of Modbus TCP device.
• <MODBUS_TCP_PORT>: Port number of Modbus TCP device.
• <MODBUS_TCP_UNIT_NAME>: Unique name of Modbus TCP device. Used as the last part of IPC topic.
• <BUCKET_NAME>: S3 bucket name, if uploaded ModbusTCP-.jar to your S3 bucket.

Follow the developer guide to publish Modbus TCP protocol adapter or deploy locally.

How to build

If you choose to build yourself, you can build by the following steps below.

Prerequisite

Install Java Development Kit 11 or above. We recommend that you use Amazon Corretto 11 or OpenJDK 11.

Build

Checkout this repository, cd to the repository root, and execute the following command.

For Linux

./gradlew jar

For Windows

.\gradlew jar

If successful, a JAR file will be created in build/libs.

Usage

Configure the component

This component has the following ComponentConfiguration items.

• Modbus: Root of Modbus related configuration.
  
  • Endpoints: Modbus TCP endpoint configuration.
    
  • Host: Host name or IP address of the Modbus TCP server.
    
  • Port: (Optional) Port number of the Modbus TCP server. Default is 502.
    
  • Timeout: (Optional) Modbus TCP communication timeout in seconds. Default is 5.
    
  • Devices: Modbus TCP device (unit) configuration.
    
    • Name: Name of the device (unit).
      
    • UnitId: (Optional) Unit id of the device (unit). Default is 0
      

Example

ComponentConfiguration:
  DefaultConfiguration:
    Modbus:
      Endpoints:
      - Host: "localhost"
        Port: 5020
        Devices:
        - Name: "test"
          UnitId: 0

Send Modbus TCP command using Greengrass IPC local messages

You can send a command to Modbus device by publishing a request to the following topic.

• modbus/request/{device name}

Sample request

{
  "id": "TestRequest",
  "function": "ReadCoils",
  "address": 1,
  "quantity": 1
}

And you can receive the result from the device as a response by subscribing to the following topic.

• modbus/response/{device name}

Sample response

{
  "id": "TestRequest",
  "type": "ReadCoils",
  "bits": [true]
}

Sample error response

{
  "id": "TestRequest",
  "type": "ExceptionCode",
  "code": "IllegalDataAddress"
}

{
  "id": "TestRequest",
  "type": "Timeout"
}

{
  "type": "BadRequest"
}

Supported commands

Common parameters

• id: string
  An arbitrary ID for the request. Use this property to map an input request to an output response.

ReadCoils

Request

• function: "ReadCoils"
• address: integer
  Starting address of the coils for read.
• quantity: integer
  Quantity of the coils for read.

Response

• type: "ReadCoils"
• bits: [boolean]
  Values of the coils.

ReadDiscreteInputs

Read discrete inputs

Request

• function: "ReadDiscreteInputs"
• address: integer
  Starting address of the discrete inputs for read.
• quantity: integer
  Quantity of the discrete inputs for read.

Response

• type: "ReadDiscreteInputs"
• bits: [boolean]
  Values of the discrete inputs.

ReadHoldingRegisters

Read holding registers

Request

• function: "ReadHoldingRegisters"
• address: integer
  Starting address of the holding registers for read.
• quantity: integer
  Quantity of the holding registers for read.

Response

• type: "ReadHoldingRegisters"
• bytes: [integer]
  Values of the holding registers.

ReadInputRegisters

Read input registers

Request

• function: "ReadInputRegisters"
• address: integer
  Starting address of the input registers for read.
• quantity: integer
  Quantity of the input registers for read.

Response

• type: "ReadInputRegisters"
• bytes: [integer]
  Values of the input registers.

WriteSingleCoil

Write single coil

Request

• function: "WriteSingleCoil"
• address: integer
  Address of the coil for write.
• value: boolean
  Value for write

Response

• type: "WriteSingleCoil"
• address: integer
• value: boolean
  Same as the request

WriteSingleRegister

Write single register

Request

• function: "WriteSingleRegister"
• address: integer
  Address of the register for write.
• value: integer
  Value for write

Response

• type: "WriteSingleRegister"
• address: integer
• value: integer
  Same as the request

WriteMultipleCoils

Write multiple coils

Request

• function: "WriteMultipleCoils"
• address: integer
  Starting address of the coils for write.
• bits: [boolean]
  Values for write.

Response

• type: "WriteMultipleCoils"
• address: integer
  Same as the request
• quantity: integer
  Quantity of written values

WriteMultipleRegisters

Write multiple registers

Request

• function: "WriteMultipleRegisters"
• address: integer
  Starting address of the registers for write.
• bytes: [integer]
  Values for write.

Response

• type: "WriteMultipleRegisters"
• address: integer
  Same as the request
• quantity: integer
  Quantity of written values

MaskWriteRegister

Mask write register

Request

• function: "MaskWriteRegister"
• address: integer
  Address of the register for mask.
• andMask: integer
  AND mask
• orMask: integer
  OR mask

Response

• type: "MaskWriteRegister"
• address: integer
• andMask: integer
• orMask: integer
  Same as the request

ReadWriteMultipleRegisters

Read and write multiple registers

Request

• function: "ReadWriteMultipleRegisters"
• readAddress: integer
  Starting address of the registers for read.
• readQuantity: integer
  Quantity of the registers for read.
• writeAddress: integer
  Starting address of the registers for write.
• bytes: [integer]
  Values for write.

Response

• type: "ReadWriteMultipleRegisters"
• bytes: [integer]
  Values of the registers.

Error response

• type: "ExceptionCode"
• code: string
  Exception code of the error.

External libraries

This component includes the following external libraries:

• Digital Petri Modbus

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.