This is a library that allows you to implement ioBroker Adapter that communicates via ModBus with devices.
It could accept a TSV file as a configuration. TSV files could be created as export in ioBroker.modbus adapter.
You can find an example here.
import ModbusTemplate, { tsv2registers } from '@iobroker/modbus';
import type { AdapterOptions } from '@iobroker/adapter-core';
import { readFileSync } from 'node:fs';
const adapterName = JSON.parse(readFileSync(`${__dirname}/../io-package.json`, 'utf8')).common.name;
export class ModbusAdapter extends ModbusTemplate {
public constructor(adapterOptions: Partial<AdapterOptions> = {}) {
const holdingRegs = tsv2registers('holdingRegs', `${__dirname}/../data/holdingRegs.tsv`);
super(
adapterName,
adapterOptions,
{
params: {
// Do not show addresses in the object IDs
doNotIncludeAdrInId: true,
// Remove the leading "_" in the names
removeUnderscorePrefix: true,
// Do not show aliases, because we don't want to see addresses
showAliases: false,
// Replace holdingRegister (and so on) with "data" in the object names
registerTypeInName: 'data',
},
holdingRegs,
},
);
}
}
// If started as allInOne mode => return function to create instance
if (require.main !== module) {
// Export the constructor in compact mode
module.exports = (options: Partial<AdapterOptions> | undefined) => new ModbusAdapter(options);
} else {
// otherwise start the instance directly
(() => new ModbusAdapter())();
}const IoBrokerModbus = require ('@iobroker/modbus');
const { readFileSync } = require('node:fs');
const adapterName = JSON.parse(readFileSync(`${__dirname}/../io-package.json`, 'utf8')).common.name;
export class ModbusAdapter extends ModbusTemplate {
public constructor(options) {
const holdingRegs = tsv2registers('holdingRegs', `${__dirname}/../data/holdingRegs.tsv`);
super(adapterName, options, { holdingRegs });
}
}
// If started as allInOne mode => return function to create instance
if (require.main !== module) {
// Export the constructor in compact mode
module.exports = options => new ModbusAdapter(options);
} else {
// otherwise start the instance directly
(() => new ModbusAdapter())();
}import ModbusTemplate, { tsv2registers } from '@iobroker/modbus';
import type { AdapterOptions } from '@iobroker/adapter-core';
import { readFileSync } from 'node:fs';
const adapterName = JSON.parse(readFileSync(`${__dirname}/../io-package.json`, 'utf8')).common.name;
export class ModbusAdapter extends ModbusTemplate {
public constructor(options: Partial<AdapterOptions> = {}) {
super(
adapterName,
options,
{
params: {
port: 520, // you can override all parameters here
},
parameterNameForFile: 'deviceType', // name of the attribute in config to read files from
adapterRootDirectory: `${__dirname}/..`, // adapter diractory
}
);
}
}
// If started as allInOne mode => return function to create instance
if (require.main !== module) {
// Export the constructor in compact mode
module.exports = (options: Partial<AdapterOptions> | undefined) => new ModbusAdapter(options);
} else {
// otherwise start the instance directly
(() => new ModbusAdapter())();
}In the second example the adapter will read from its configuration attribute deviceType the type of the device and tries to find a file:
<adapterDirectory>/<valueOfDeviceType>- holding registers- or
<adapterDirectory>/<valueOfDeviceType without '.tsv'>inputRegs.tsv- for input registers
If the value of deviceType is data/holdingRegs.tsv or data/holdingRegs the adapter will search for file <adapterDirectory>/data/holdingRegs.tsv.
If the value of deviceType is data/m100.tsv or data/m100 the adapter will search for files <adapterDirectory>/data/m100coils.tsv, <adapterDirectory>/data/m100disInputs.tsv, <adapterDirectory>/data/m100inputRegs.tsv, <adapterDirectory>/data/m100holdingRegs.tsv
If you want to use serial port, you have to include serialport package into 'package.json' of your adapter, because @iobroker/modbus does not have this dependency by default.
There are some programs in folder test to test the TCP communication:
- Ananas32/64 is a slave simulator (only holding registers and inputs, no coils and digital inputs)
- RMMS is a master simulator
- mod_RSsim.exe is a slave simulator. It can be that you need Microsoft Visual C++ 2008 SP1 Redistributable Package to start it (because of a Side-By-Side error).
- (@GermanBluefox) Added a proxy mode (issue #775): a master instance can additionally serve its polled data as a Modbus TCP slave and forward client writes back to the device (
proxy/proxyBind/proxyPort)
- (@GermanBluefox) Fixed
Put.floatle()to write a valid IEEE-754 little-endian float and to stop dropping data written after it - (@GermanBluefox) Added unit tests for the Modbus packet builder (
Put) and the CRC-16/MODBUS checksum
- (@johannes-lode) Fixed FC1 coil reads returning stale data: the slave now refreshes the coil buffer before responding (event name matched the listener)
- (@johannes-lode) Fixed the TCP slave crashing on server listen errors (e.g. address already in use or privileged port without permission); such errors are now logged instead
- (@johannes-lode) Fixed coil/discrete-input reads being written to the wrong buffer bit for start addresses other than 0
- (@johannes-lode) Fixed the coil/discrete-input buffer size when the highest address is a multiple of 8 (
ceil(addressHigh / 8))
- (@GermanBluefox) Allowed distinguishing two identical USB chips (same vendor/product, no serial number) by their physical USB port: device IDs now fall back to
/dev/serial/by-pathon Linux and to the pnpId/location elsewhere, and the dropdown label shows that location. Legacyvendor:product:serialIDs keep working.
- (@GermanBluefox) Added selection of the serial device by its stable USB ID (vendor/product/serial) via the new
listUartDevicesmessage andselectBy/comDeviceIdparameters
- (@GermanBluefox) Corrected room definition for the first register
- (@GermanBluefox) Added "ttyADM***" to the list of possible serial ports
- (@GermanBluefox) Write cyclic values even if they are not polled
- (@GermanBluefox) Corrected potential errors
- (@GermanBluefox) Added sanity check for the configuration
- (@GermanBluefox) Disable logging of request timeout if
disableLoggingparameter is set to true
- (@GermanBluefox) Corrected the reading of registers
- (@GermanBluefox) Corrected the type of
info.connection
- (@GermanBluefox) Corrected parsing of TSV files
- (@GermanBluefox) Updated packages
- (@GermanBluefox) Corrected serial communication
- (@GermanBluefox) Added
onBeforeReadymethod to do something before adapter starts
- (@GermanBluefox) Added
hostparameter for master connection
- (@GermanBluefox) Added
removeUnderscorePrefixparameter - (@GermanBluefox) Added
noRegisterTypeInNameparameter - (@GermanBluefox) Allowed to set a custom channel name
- (bluefox) initial commit
The MIT License (MIT)
Copyright (c) 2015-2026 Bluefox dogafox@gmail.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.