Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wolkabout/wolkgatewaymodule-modbus

WolkGateway module for connecting Modbus devices to WolkAbout IoT Platform by communicating with WolkGateway.
https://github.com/wolkabout/wolkgatewaymodule-modbus

gateway iot modbus modbus-rtu modbus-tcp wolkabout wolkgateway

Last synced: 4 days ago
JSON representation

WolkGateway module for connecting Modbus devices to WolkAbout IoT Platform by communicating with WolkGateway.

Host: GitHub
URL: https://github.com/wolkabout/wolkgatewaymodule-modbus
Owner: Wolkabout
License: apache-2.0
Created: 2018-04-11T13:41:47.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2024-03-29T09:53:23.000Z (8 months ago)
Last Synced: 2024-03-29T10:53:36.630Z (8 months ago)
Topics: gateway, iot, modbus, modbus-rtu, modbus-tcp, wolkabout, wolkgateway
Language: C++
Homepage:
Size: 885 KB
Stars: 5
Watchers: 6
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# WolkGateway Module Modbus

WolkGateway module for connecting Modbus devices to WolkAbout IoT Platform by communicating
with [WolkGateway](https://github.com/Wolkabout/WolkGateway).

Supported protocol(s):

* Wolkabout Protocol

Installing from source
----------------------

This repository must be cloned from the command line using:

```sh
git clone --recurse-submodules https://github.com/Wolkabout/WolkGatewayModule-Modbus.git
```

Prerequisite
------------
Following tools/libraries are required in order to build WolkGateway Module Modbus

* cmake - version 3.5 or later
* autotools
* automake
* autoconf
* g++
* m4
* zlib1g-dev
* libtool
* openssl

Former can be installed on Debian based system from terminal by invoking:

```sh
sudo apt-get install automake g++ autotools-dev autoconf m4 zlib1g-dev cmake libtool libssl-dev
```

Afterwards dependencies are built, and Makefile build system is generated by invoking:

```sh
./configure
```

Generated build system is located inside `out` directory To build the module, invoke:

```sh
cd out
make -j$(nproc)
sudo make install
```

Installing will place the application in PATH, and create a systemctl unit, which you can use with:

```sh
sudo service modbus_module status/start/stop/restart
```

The configuration files used are placed in `/etc/modbusModule/`, which you should configure before you start your
service. If you don't know how to configure the module, continue on to the next part.

Configuring Module
--------------------
Module configuration consists of 2 configurations files

* moduleConfiguration.json
* devicesConfiguration.json

Below are sections describing each of these configuration files that need to be edited with the parameters of your
modbus devices before running the application. These files are located in `out` directory, and are passed to Modbus
module executable in following manner:

```sh
./modbusModule moduleConfiguration.json devicesConfiguration.json
```

moduleConfiguration.json
--------------------
Module configuration file contains settings that relate to communication with WolkGateway, and outgoing Modbus
connection, reading period time and response timeout.

```json5
{
"mqttHost": "tcp://localhost:1883",
// Address of local MQTT broker (connection with WolkGateway)
"connectionType": "SERIAL/RTU",
// Modbus connection type, choice between "SERIAL/RTU" and "TCP/IP"
"tcp/ip": {
// TCP/IP connection properties (ignored if connectionType is "SERIAL/RTU")
"host": "192.168.x.x",
// IP address of Modbus server (mandatory if connectionType is "TCP/IP")
"port": 502
// Port of Modbus server (default is 502, if not stated)
},
"serial/rtu": {
// Serial/RTU connection properties (ignored if connectionType is "TCP/IP")
"serialPort": "SERIAL_PORT",
// Serial port location such as /dev/ttyS0 (mandatory if connection type is "SERIAL/RTU")
"baudRate": 115200,
// Baud rate for serial connection (default is 115200, if not stated)
"dataBits": 8,
// DataBits for Modbus RTU (default is 8, if not stated)
"stopBits": 1,
// StopBits for Modbus RTU (default is 1, if not stated)
"bitParity": "NONE"
// BitParity for Modbus RTU, can be "NONE", "EVEN", "ODD" (default is "NONE", if not stated)
},
"responseTimeoutMs": 200,
// Wait time for respond from slaves/servers (default is 200, if not stated)
"registerReadPeriodMs": 500
// Period of reading all registers/devices (default is 500, if not stated)
}
```

devicesConfiguration.json
-----------------------
Devices configuration file contains information necessary to define templates, which include registers that bind to
Wolkabout IoT Platform sensors/actuators/alarms/configurations, and then devices, with their information, and a
template. This is the guide by which the module will register devices, and then send data for.

You define templates, that are described by their name, and mappings.

```json5
{
"templates": [
{
"name": "",
"mappings": [
// define mappings
]
}
]
}
```

After doing so, you define all the mappings inside a template.

Single mapping includes one or more Modbus registers that produce a single sensor/actuator/alarm/configuration on a
device, on the platform. They're characterized by a name, and a reference key, used to identify them, by their register
type (necessary), data type (necessary), operation type (necessary for some output types), and mapping type.

There are optional features you can enable for mappings, such as:

- Unit type
- Deadband and Frequency filtering
- Repeated write
- Default value
- Safe Mode value
- AutoLocalUpdate toggle
- AutoReadAfterWrite toggle

#### Register types:

* Read & Write:
- `COIL`
- `HOLDING_REGISTER`
* Read Only:
- `INPUT_REGISTER`
- `INPUT_CONTACT`

#### Data types:

- UINT16/INT16
- BOOL
- UINT32/INT32 (with merge operations)
- FLOAT (with merge operation)
- STRING (with stringify operations)

#### Operation types:

- `MERGE_BIG_ENDIAN` or `MERGE_LITTLE_ENDIAN` (in combination with `"dataType": "UINT32/INT32"`)
- `MERGE_FLOAT_BIG_ENDIAN` or `MERGE_FLOAT_LITTLE_ENDIAN` (in combination with `"dataType": "FLOAT"`)
- `TAKE_BIT` (in combination with `"dataType": "BOOL"`)
- `STRINGIFY_ASCII_BIG_ENDIAN`, `STRINGIFY_ASCII_LITTLE_ENDIAN`, `STRINGIFY_UNICODE_BIG_ENDIAN` or `STRINGIFY_UNICODE_LITTLE_ENDIAN` (in combination with `"dataType": "STRING"`)

#### Unit types:

You can add a field `"unit": "CELSIUS"` to a mapping that will register the feed on the platform with the GUID of the
unit on the platform.

#### Deadband and frequency filters:

You can add fields `"deadBandFilter":0.1` and `"frequencyFilterValue":1` to add a deadband and frequency filter to your
mappings.

#### Repeated write

If this feature is enabled, it will write overwrite the value in the register after some time even if the value has not
changed.
You can add a field `"repeat":500` and the value will be overwritten every 500ms.

#### Default value

If you want to set a value that will be written in as soon as the application launches, write it in as the default
value.
You can add a field `"defaultValue":123` and it will be written in when the application launches.

#### Safe Mode value

If you want a value written into a mapping when the gateway and the module lose connectivity with the platform, you can
write the value here.
You can add a field `"safeMode":123` and it will be written in when the communication with the platform is lost.

#### AutoLocalUpdate

The software keeps a local copy of the value of all mappings, and the message to the platform about updates is sent when
a new value gets read from the modbus register. By default actuation will write into the register, but not in the local
copy,
so the value will be read in the next read cycle and sent to the platform.
If you want the local copy of mapping values to be updated, set the `"autoLocalUpdate":true` for the mapping. This will
result
in a message about the feed to never be sent to the platform, and the platform will just implicitly take it as the
actuation was successful.

#### AutoReadAfterWrite

On actuation, the module will write the value directly into the registers as needed. But it will also read the same
registers, and notify the platform of value changes if detected - updating the local copy of the values as well.
If you want this behavior to be turned off, set the `"autoReadAfterWrite":false` for the mapping. This will disable
the automatic read after writing into a mapping.

```json5
{
// Inside of a template
"name": "",
"mappings": [
{
"name": "mappingName",
// Register name
"reference": "mappingReference",
// Unique reference used to differ register on WolkAbout IoT Platform
"minimum": -32768,
// Minimum value that can be held in register. Required for visualization on WolkAbout IoT Platform
"maximum": 32767,
// Maximum value that can be held in register. Required for visualization on WolkAbout IoT Platform
"address": 0,
// Register address
"registerType": "INPUT_REGISTER",
// Register type - "INPUT_REGISTER" or "HOLDING_REGISTER_ACTUATOR" or "HOLDING_REGISTER_SENSOR" or "INPUT_CONTACT" or "COIL"
"dataType": "INT16"
// Data type stored in register - "INT16" or "UINT16" or "REAL32" for "INPUT_REGISTER"/"HOLDING_REGISTER_ACTUATOR"/"HOLDING_REGISTER_SENSOR" register type, and "BOOL" for "COIL"/"INPUT_CONTACT"
},
{
"name": "mappingName2",
"reference": "mappingReference2",
"minimum": -4000,
"maximum": 4000,
"address": 1,
"registerType": "HOLDING_REGISTER",
"dataType": "FLOAT",
"deadbandValue": 4.0,
// Optional - Indicates a change in value of the mapping that is insignificant data. Applicable to numeric mappings.
"frequencyFilterValue": 250
// Optional - When register changes value often, disregard changes until X milliseconds pass since last accepted value.
},
{
"name": "mappingName3",
"reference": "mappingReference3",
"address": 1,
"registerType": "INPUT_CONTACT",
"dataType": "BOOL"
// This is where for the first time, we override the default Mapping type
},
{
"name": "mappingName4",
"reference": "mappingReference4",
"address": 2,
"registerType": "HOLDING_REGISTER",
"operationType": "MERGE_BIG_ENDIAN",
"dataType": "UINT32"
},
{
"name": "mappingReference5",
"reference": "mappingReference5",
"address": 3,
"registerType": "COIL",
"dataType": "BOOL",
"writeOnly": true
// If the mapping needs to be Write-Only, you put this attribute.
},
{
"name": "mappingReference6",
"reference": "mappingReference6",
"address": 10,
"addressCount": 10,
"registerType": "HOLDING_REGISTER",
"dataType": "STRING",
"operationType": "STRINGIFY_ASCII_BIG_ENDIAN",
"autoLocalUpdate": true,
"autoReadAfterWrite": false
},
{
"name": "mappingReference7",
"reference": "mappingReference7",
"address": 8,
"bitIndex": 0,
"registerType": "INPUT_REGISTER",
"operationType": "TAKE_BIT",
"dataType": "BOOL"
}
]
}
```

After you completely defined a template, you can list a device.

```json5
{
"devices": [
{
"name": "",
// User readable device name, necessary to register a device
"key": "",
// Unique device key
"slaveAddress": 1,
// Slave address (obligatory if connection type is "SERIAL/RTU"), must be unique in this list
"template": ""
// Name of defined template
}
// other devices
]
// templates
}
```

In "TCP/IP" mode, device count is maxed at 1, and you don't need to state a slaveAddress for the device.

If the user happens to enter an invalid template name, the device won't be created. Module will function if at least one
device is valid. If there are no devices that have been inputted correctly, the module will exit out, and used will be
notified.