Modbus Prometheus API Server

Table of Contents

• 1. Introduction
• 2. API routes
• 3. Get started
  • 3.1. Build and run the Applications
  • 3.2. Monitor the Applications
  • 3.3. Add a client
• 4. Links

1. Introduction

This server is a REST API server to access Modbus registers and coils. It is written in Rust and uses the warp-web framework. It uses the modbus-async. Additionally it provides a Prometheus endpoint to access the Modbus registers and coils as Prometheus metrics. The current limit of clients is 10.

2. API routes

Route	Input	Output	Description
GET /metrics	none	none	Real values of all Modbus registers of all clients as Prometheus standard metric endpoint
GET /clients	none	HTML	Get a string of all configured clients
POST /clients	JSON body	return HTTP status code	Create a new client. Stores local config JSON <client-name>-config.json
DELETE /clients/{name}	none	return HTTP status code	Delete a specific client. Deletes local config JSON <client-name>-config.json
GET /clients/{name}	none	JSON body	Gets the config JSON of a specific client
PUT /clients/{name}/set-register?{register_name}={value}	none	return HTTP status code	Set a specific register (input register)
PUT /clients/{name}/set-coil?{coil_name}={value}	none	return HTTP status code	Set a specific coil (coil)

3. Get started

The following graph show the testing architecture for the current version. The Modbus server is simulated with Node-red. The Prometheus server is running in a docker container. The Modbus Prometheus API Server is running on the host machine.

3.1. Build and run the Applications

Node-red is used for simulating a Modbus server. You can build a modbus test server (corresponding to the .config/test_client.json) with:

cd /docker/node-red && build -t modbus-test-server .

You can build the Prometheus Image locally with:

cd /docker/prometheus && build -t prometheus .

After building both of the images, start the containers:

docker run -p 9090:9090 prometheus
docker run -p 1880:1880 -p 502:502 modbus-test-server
docker run -p 3000:3000 grafana/grafana-oss:latest (extra, not needed)

If you add the Prometheus as a datasource, use the Container IP. You can get the IP with:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container-id>

Then you can start the server with:

cargo run

3.2. Monitor the Applications

You can monitor the applications with the following URLs:

• Grafana (optional)

• Prometheus (Prometheus metrics)

• Node-red (Modbus server)

3.3. Add a client

{
  "name": "test_client",
  "ip_address": "127.0.0.1",
  "port": 502,
  "protocol": "tcp",
  "registers": [
    {
      "name": "test_register_1",
      "objecttype": "holding",
      "address": 0,
      "length": 1,
      "datatype": "int16",
      "factor": 0,
      "value": 0
    },
    {
      "name": "test_register_2",
      "objecttype": "input",
      "address": 0,
      "length": 1,
      "datatype": "int16",
      "factor": 0,
      "value": 0
    }
  ],
  "coils": [
    {
      "name": "test_coil_1",
      "objecttype": "coil",
      "address": 0,
      "value": false
    },
    {
      "name": "test_coil_2",
      "objecttype": "discrete",
      "address": 0,
      "value": false
    }
  ]
}

4. Links

Follow these tutorials to understand better:

• Using Prometheus metrics in a Rust web service

• Rust Web Development by Bastian Gruber (@gruberb)