modbus

Modbus Service

The Modbus service manages Modbus TCP clients for things and groups. Each client connects to a Modbus TCP device on a schedule. A read client reads the configured registers or coils, and a write client writes the configured values and reads them back; both publish the values as a JSON message on behalf of the associated thing.

Modbus Clients

A Modbus client defines the connection parameters, schedule, and data fields to read from or write to a Modbus TCP device.

Function Codes

A client with a write function code writes the value of each data field on every scheduled run, then reads the written registers or coils back and publishes them in the same format as a read client. Adjacent fields are written in one request; a block of one coil or register uses 0x05 or 0x06, and a longer block uses 0x0F or 0x10. WriteCoils fields must have the bool type, and string fields are not writable.

Scheduler

The scheduler object controls when the client reads from or writes to the device.

Data Fields

Each entry in data_fields describes a single register or coil to read or write.

The read result is published as a JSON object keyed by field name, for example:

{"temperature": 23.5, "humidity": 61}

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Deployment

The service itself is distributed as Docker container. Check the modbus service section in docker-compose to see how service is deployed.

To start the service, execute the following shell script:

# Download the latest version of the service
git clone https://github.com/MainfluxLabs/mainflux

cd mainflux

# compile the modbus service
make modbus

# Copy binary to bin
make install

# Set the environment variables and run the service
MF_MODBUS_LOG_LEVEL=[Modbus log level] \
MF_BROKER_URL=[Message broker instance URL] \
MF_MODBUS_HTTP_PORT=[Modbus service HTTP port] \
MF_MODBUS_DB_HOST=[Database host address] \
MF_MODBUS_DB_PORT=[Database host port] \
MF_MODBUS_DB_USER=[Database user] \
MF_MODBUS_DB_PASS=[Database password] \
MF_MODBUS_DB=[Modbus database name] \
MF_THINGS_AUTH_GRPC_URL=[Things service Auth gRPC URL] \
MF_THINGS_AUTH_GRPC_TIMEOUT=[Things service Auth gRPC request timeout] \
$GOBIN/mainfluxlabs-modbus

Usage

Creating clients (POST /things/{thingId}/clients, Content-Type: application/json)

A JSON array of client objects (see fields above), each with data_fields given inline. Multiple clients can be created in one request.

curl -X POST http://localhost:9028/things/<thingId>/clients \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '[{"name":"pump-1","ip_address":"10.0.0.5","port":"502","slave_id":1,"function_code":"ReadHoldingRegisters","scheduler":{"frequency":"minutely","minute":5,"time_zone":"UTC"},"data_fields":[{"name":"temperature","type":"float32","byte_order":"ABCD","address":0}]}]'

Importing a client creates a single client whose connection info is given as a client form field (JSON, same shape as above without data_fields) and whose data_fields are parsed from an uploaded file part. Meant for a client with many registers, so they don't have to be entered one by one through a form. Both import endpoints require Content-Type: multipart/form-data.

Importing a client with a CSV file (POST /things/{thingId}/clients/csv)

The file needs a header row naming columns, one row per register; header names are matched case-insensitively and unknown columns are ignored. type and byte_order values are also matched case-insensitively (e.g. Float32, FLOAT32, and float32 are equivalent) — this only normalizes casing, not vendor type names that differ from ours entirely (see below).

name,type,unit,scale,byte_order,address,length
temperature,float32,celsius,0.1,ABCD,0,
humidity,float32,%,,ABCD,2,

curl -X POST http://localhost:9028/things/<thingId>/clients/csv \
  -H "Authorization: Bearer <token>" \
  -F 'client={"name":"pump-1","ip_address":"10.0.0.5","port":"502","slave_id":1,"function_code":"ReadHoldingRegisters","scheduler":{"frequency":"minutely","minute":5,"time_zone":"UTC"}}' \
  -F "file=@registers.csv"

Adapting a vendor register map

Modbus itself doesn't define a file format for register maps, but vendor datasheets commonly publish one with columns like Address (hex/dec), Description, Format, Unit, N, Access, Function Code. To import one:

• Rename the decimal address column to address (the hex column isn't needed).
• Rename the description/name column to name.
• Rename the data-type column to type, translating vendor type codes to ours, e.g. U16→uint16, S16→int16, U32→uint32, Float→float32. Casing doesn't matter (Float32 and FLOAT32 both work), but the word itself still needs to match one of ours — Float alone isn't float32.
• Function Code in particular is set once via the client field, not per register, so a register map spanning more than one function code needs to be split into separate imports (see Function Codes above).

Importing a client with a JSON file (POST /things/{thingId}/clients/json)

The file is a JSON array of data field objects, same shape as data_fields above. type and byte_order values are matched case-insensitively, same as the CSV import.

curl -X POST http://localhost:9028/things/<thingId>/clients/json \
  -H "Authorization: Bearer <token>" \
  -F 'client={"name":"pump-1","ip_address":"10.0.0.5","port":"502","slave_id":1,"function_code":"ReadHoldingRegisters","scheduler":{"frequency":"minutely","minute":5,"time_zone":"UTC"}}' \
  -F 'file=[{"name":"temperature","type":"float32","byte_order":"ABCD","address":0}]'

For the full HTTP API reference, see the OpenAPI specification.