Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Modbus connection settings (serial) #9256

Merged
merged 9 commits into from
Oct 19, 2021
Merged

feat: Modbus connection settings (serial) #9256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b3d1c07
Implement workarounds (pause between reads and disconnect after gathe…
Jun 14, 2021
011117b
Fix whitespaces in sampleconfig.
Jun 14, 2021
77137ef
Fix whitespaces in sample-config.
srebhan Jul 12, 2021
0406f5b
Fix more whitespaces in sample-config.
srebhan Jul 12, 2021
ca23d40
Convert workaround part to an actual toml section.
Jul 23, 2021
8bd2718
Formatting.
Aug 4, 2021
b3ed980
Be more precise about further workarounds in README.
Sep 23, 2021
496643e
Make clear that debug has to be enabled when you want to see `debug_c…
Sep 23, 2021
5e25a32
Add a further note about `debug_connections` and warn about too long …
Sep 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions plugins/inputs/modbus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Registers via Modbus TCP or Modbus RTU/ASCII.

# TCP - connect via Modbus/TCP
controller = "tcp://localhost:502"

## Serial (RS485; RS232)
# controller = "file:///dev/ttyUSB0"
# baud_rate = 9600
Expand All @@ -42,6 +42,10 @@ Registers via Modbus TCP or Modbus RTU/ASCII.
## For Serial you can choose between "RTU" and "ASCII"
# transmission_mode = "RTU"

## Trace the connection to the modbus device as debug messages
## Note: You have to enable telegraf's debug mode to see those messages!
# debug_connection = false

## Measurements
##

Expand Down Expand Up @@ -88,8 +92,22 @@ Registers via Modbus TCP or Modbus RTU/ASCII.
{ name = "tank_ph", byte_order = "AB", data_type = "INT16", scale=1.0, address = [1]},
{ name = "pump1_speed", byte_order = "ABCD", data_type = "INT32", scale=1.0, address = [3,4]},
]

## Enable workarounds required by some devices to work correctly
# [inputs.modbus.workarounds]
## Pause between read requests sent to the device. This might be necessary for (slow) serial devices.
# pause_between_requests = "0ms"
## Close the connection after every gather cycle. Usually the plugin closes the connection after a certain
## idle-timeout, however, if you query a device with limited simultaneous connectivity (e.g. serial devices)
## from multiple instances you might want to only stay connected during gather and disconnect afterwards.
# close_connection_after_gather = false
```

### Notes
You can debug Modbus connection issues by enabling `debug_connection`. To see those debug messages Telegraf has to be started with debugging enabled (i.e. with `--debug` option). Please be aware that connection tracing will produce a lot of messages and should **NOT** be used in production environments.

Please use `pause_between_requests` with care. Especially make sure that the total gather time, including the pause(s), does not exceed the configured collection interval. Note, that pauses add up if multiple requests are sent!

### Metrics

Metric are custom and configured using the `discrete_inputs`, `coils`,
Expand Down Expand Up @@ -131,6 +149,8 @@ with N decimal places'.
from unsigned values).

### Trouble shooting

#### Strange data
Modbus documentations are often a mess. People confuse memory-address (starts at one) and register address (starts at zero) or stay unclear about the used word-order. Furthermore, there are some non-standard implementations that also
swap the bytes within the register word (16-bit).

Expand All @@ -142,7 +162,15 @@ In case you get an `exception '2' (illegal data address)` error you might try to

In case you see strange values, the `byte_order` might be off. You can either probe all combinations (`ABCD`, `CDBA`, `BADC` or `DCBA`) or you set `byte_order="ABCD" data_type="UINT32"` and use the resulting value(s) in an online converter like [this](https://www.scadacore.com/tools/programming-calculators/online-hex-converter/). This makes especially sense if you don't want to mess with the device, deal with 64-bit values and/or don't know the `data_type` of your register (e.g. fix-point floating values vs. IEEE floating point).

If nothing helps, please post your configuration, error message and/or the output of `byte_order="ABCD" data_type="UINT32"` to one of the telegraf support channels (forum, slack or as issue).
If your data still looks corrupted, please post your configuration, error message and/or the output of `byte_order="ABCD" data_type="UINT32"` to one of the telegraf support channels (forum, slack or as issue).

#### Workarounds
Some Modbus devices need special read characteristics when reading data and will fail otherwise. For example, there are certain serial devices that need a certain pause between register read requests. Others might only offer a limited number of simultaneously connected devices, like serial devices or some ModbusTCP devices. In case you need to access those devices in parallel you might want to disconnect immediately after the plugin finished reading.

To allow this plugin to also handle those "special" devices there is the `workarounds` configuration options. In case your documentation states certain read requirements or you get read timeouts or other read errors you might want to try one or more workaround options.
If you find that other/more workarounds are required for your device, please let us know.

In case your device needs a workaround that is not yet implemented, please open an issue or submit a pull-request.

### Example Output

Expand Down
88 changes: 75 additions & 13 deletions plugins/inputs/modbus/modbus.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,19 +15,26 @@ import (
"github.com/influxdata/telegraf/plugins/inputs"
)

type ModbusWorkarounds struct {
PollPause config.Duration `toml:"pause_between_requests"`
CloseAfterGather bool `toml:"close_connection_after_gather"`
}

// Modbus holds all data relevant to the plugin
type Modbus struct {
Name string `toml:"name"`
Controller string `toml:"controller"`
TransmissionMode string `toml:"transmission_mode"`
BaudRate int `toml:"baud_rate"`
DataBits int `toml:"data_bits"`
Parity string `toml:"parity"`
StopBits int `toml:"stop_bits"`
Timeout config.Duration `toml:"timeout"`
Retries int `toml:"busy_retries"`
RetriesWaitTime config.Duration `toml:"busy_retries_wait"`
Log telegraf.Logger `toml:"-"`
Name string `toml:"name"`
Controller string `toml:"controller"`
TransmissionMode string `toml:"transmission_mode"`
BaudRate int `toml:"baud_rate"`
DataBits int `toml:"data_bits"`
Parity string `toml:"parity"`
StopBits int `toml:"stop_bits"`
Timeout config.Duration `toml:"timeout"`
Retries int `toml:"busy_retries"`
RetriesWaitTime config.Duration `toml:"busy_retries_wait"`
DebugConnection bool `toml:"debug_connection"`
Workarounds ModbusWorkarounds `toml:"workarounds"`
Log telegraf.Logger `toml:"-"`
// Register configuration
ConfigurationOriginal
// Connection handling
Expand Down Expand Up @@ -88,19 +95,24 @@ const sampleConfig = `

# TCP - connect via Modbus/TCP
controller = "tcp://localhost:502"

## Serial (RS485; RS232)
# controller = "file:///dev/ttyUSB0"
# baud_rate = 9600
# data_bits = 8
# parity = "N"
# stop_bits = 1
# transmission_mode = "RTU"

## Trace the connection to the modbus device as debug messages
srebhan marked this conversation as resolved.
Show resolved Hide resolved
## Note: You have to enable telegraf's debug mode to see those messages!
# debug_connection = false

## For Modbus over TCP you can choose between "TCP", "RTUoverTCP" and "ASCIIoverTCP"
## default behaviour is "TCP" if the controller is TCP
## For Serial you can choose between "RTU" and "ASCII"
# transmission_mode = "RTU"

## Measurements
##

Expand Down Expand Up @@ -148,6 +160,15 @@ const sampleConfig = `
{ name = "tank_ph", byte_order = "AB", data_type = "INT16", scale=1.0, address = [1]},
{ name = "pump1_speed", byte_order = "ABCD", data_type = "INT32", scale=1.0, address = [3,4]},
]

## Enable workarounds required by some devices to work correctly
# [inputs.modbus.workarounds]
## Pause between read requests sent to the device. This might be necessary for (slow) serial devices.
# pause_between_requests = "0ms"
## Close the connection after every gather cycle. Usually the plugin closes the connection after a certain
## idle-timeout, however, if you query a device with limited simultaneous connectivity (e.g. serial devices)
## from multiple instances you might want to only stay connected during gather and disconnect afterwards.
# close_connection_after_gather = false
`

// SampleConfig returns a basic configuration for the plugin
Expand Down Expand Up @@ -234,6 +255,11 @@ func (m *Modbus) Gather(acc telegraf.Accumulator) error {
m.collectFields(acc, timestamp, tags, requests.input)
}

// Disconnect after read if configured
if m.Workarounds.CloseAfterGather {
return m.disconnect()
}

return nil
}

Expand All @@ -253,14 +279,23 @@ func (m *Modbus) initClient() error {
case "RTUoverTCP":
handler := mb.NewRTUOverTCPClientHandler(host + ":" + port)
handler.Timeout = time.Duration(m.Timeout)
if m.DebugConnection {
handler.Logger = m
}
m.handler = handler
case "ASCIIoverTCP":
handler := mb.NewASCIIOverTCPClientHandler(host + ":" + port)
handler.Timeout = time.Duration(m.Timeout)
if m.DebugConnection {
handler.Logger = m
}
m.handler = handler
default:
handler := mb.NewTCPClientHandler(host + ":" + port)
handler.Timeout = time.Duration(m.Timeout)
if m.DebugConnection {
handler.Logger = m
}
m.handler = handler
}
case "file":
Expand All @@ -272,6 +307,9 @@ func (m *Modbus) initClient() error {
handler.DataBits = m.DataBits
handler.Parity = m.Parity
handler.StopBits = m.StopBits
if m.DebugConnection {
handler.Logger = m
}
m.handler = handler
case "ASCII":
handler := mb.NewASCIIClientHandler(u.Path)
Expand All @@ -280,6 +318,9 @@ func (m *Modbus) initClient() error {
handler.DataBits = m.DataBits
handler.Parity = m.Parity
handler.StopBits = m.StopBits
if m.DebugConnection {
handler.Logger = m
}
m.handler = handler
default:
return fmt.Errorf("invalid protocol '%s' - '%s' ", u.Scheme, m.TransmissionMode)
Expand Down Expand Up @@ -334,6 +375,7 @@ func (m *Modbus) gatherRequestsCoil(requests []request) error {
if err != nil {
return err
}
nextRequest := time.Now().Add(time.Duration(m.Workarounds.PollPause))
m.Log.Debugf("got coil@%v[%v]: %v", request.address, request.length, bytes)

// Bit value handling
Expand All @@ -345,6 +387,9 @@ func (m *Modbus) gatherRequestsCoil(requests []request) error {
request.fields[i].value = uint16((bytes[idx] >> bit) & 0x01)
m.Log.Debugf(" field %s with bit %d @ byte %d: %v --> %v", field.name, bit, idx, (bytes[idx]>>bit)&0x01, request.fields[i].value)
}

// Some (serial) devices require a pause between requests...
time.Sleep(time.Until(nextRequest))
srebhan marked this conversation as resolved.
Show resolved Hide resolved
}
return nil
}
Expand All @@ -356,6 +401,7 @@ func (m *Modbus) gatherRequestsDiscrete(requests []request) error {
if err != nil {
return err
}
nextRequest := time.Now().Add(time.Duration(m.Workarounds.PollPause))
m.Log.Debugf("got discrete@%v[%v]: %v", request.address, request.length, bytes)

// Bit value handling
Expand All @@ -367,6 +413,9 @@ func (m *Modbus) gatherRequestsDiscrete(requests []request) error {
request.fields[i].value = uint16((bytes[idx] >> bit) & 0x01)
m.Log.Debugf(" field %s with bit %d @ byte %d: %v --> %v", field.name, bit, idx, (bytes[idx]>>bit)&0x01, request.fields[i].value)
}

// Some (serial) devices require a pause between requests...
time.Sleep(time.Until(nextRequest))
}
return nil
}
Expand All @@ -378,6 +427,7 @@ func (m *Modbus) gatherRequestsHolding(requests []request) error {
if err != nil {
return err
}
nextRequest := time.Now().Add(time.Duration(m.Workarounds.PollPause))
m.Log.Debugf("got holding@%v[%v]: %v", request.address, request.length, bytes)

// Non-bit value handling
Expand All @@ -390,6 +440,9 @@ func (m *Modbus) gatherRequestsHolding(requests []request) error {
request.fields[i].value = field.converter(bytes[offset : offset+length])
m.Log.Debugf(" field %s with offset %d with len %d: %v --> %v", field.name, offset, length, bytes[offset:offset+length], request.fields[i].value)
}

// Some (serial) devices require a pause between requests...
time.Sleep(time.Until(nextRequest))
}
return nil
}
Expand All @@ -401,6 +454,7 @@ func (m *Modbus) gatherRequestsInput(requests []request) error {
if err != nil {
return err
}
nextRequest := time.Now().Add(time.Duration(m.Workarounds.PollPause))
m.Log.Debugf("got input@%v[%v]: %v", request.address, request.length, bytes)

// Non-bit value handling
Expand All @@ -413,6 +467,9 @@ func (m *Modbus) gatherRequestsInput(requests []request) error {
request.fields[i].value = field.converter(bytes[offset : offset+length])
m.Log.Debugf(" field %s with offset %d with len %d: %v --> %v", field.name, offset, length, bytes[offset:offset+length], request.fields[i].value)
}

// Some (serial) devices require a pause between requests...
time.Sleep(time.Until(nextRequest))
}
return nil
}
Expand Down Expand Up @@ -441,6 +498,11 @@ func (m *Modbus) collectFields(acc telegraf.Accumulator, timestamp time.Time, ta
}
}

// Implement the logger interface of the modbus client
func (m *Modbus) Printf(format string, v ...interface{}) {
m.Log.Debugf(format, v...)
srebhan marked this conversation as resolved.
Show resolved Hide resolved
}

// Add this plugin to telegraf
func init() {
inputs.Add("modbus", func() telegraf.Input { return &Modbus{} })
Expand Down