feat: Modbus connection settings (serial)

[srebhan]

Required for all PRs:

• Updated associated README.md.
• Wrote appropriate unit tests.

resolves #9253
resolves #8225

With this PR we add options to enable debugging of modbus connections and to configure the connection handling more fine-grained.
With close_connection_after_gather you can force the plugin to close and reopen the connection in each gather cycle. This is especially important for long intervals and/or modbus devices with a restricted number of simultaneous connections.
The second option pause_between_requests allows to add a pause between two requests (e.g. when querying non-consecutive registers). This is required by some serial devices (see Issue #9253).

[binueda]

Tested with pause_between_requests = "100ms" with non-consecutive registers and found working perfect 👍

[binueda]

Tested with pause_between_requests = "100ms" with non-consecutive registers and found working perfect 👍

Configuration

trace_connection = true
close_connection = false
name = "BM"
slave_id = 10
timeout = "4s"
pause_between_requests = "100ms"
#   ## Serial (RS485; RS232)
   controller = "file:///dev/ttyAMA0"
   baud_rate = 9600
   data_bits = 8
   parity = "E"
   stop_bits = 1
   transmission_mode = "RTU"
holding_registers = [
        { name = "Watts Total-CH1",     byte_order = "CDAB",   data_type = "FLOAT32-IEEE", scale=1.0,address = [4100,4101]},
        { name = "Total Current-2",       byte_order = "CDAB",   data_type = "FLOAT32-IEEE", scale=1.0,address = [4202,4203]},
   ]

Result

2021-05-11T11:31:49Z D! [agent] Starting service inputs
2021-05-11T11:31:50Z D! [inputs.modbus] modbus: send 0a 03 10 04 00 02 80 71
2021-05-11T11:31:50Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:31:50Z D! [inputs.modbus] got holding@4100[2]: [0 0 0 0]
2021-05-11T11:31:50Z D! [inputs.modbus]   field Watts Total-CH1 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:31:50Z D! [inputs.modbus] modbus: send 0a 03 10 6a 00 02 e1 ac
2021-05-11T11:31:50Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:31:50Z D! [inputs.modbus] got holding@4202[2]: [0 0 0 0]
2021-05-11T11:31:50Z D! [inputs.modbus]   field Total Current-2 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:31:55Z D! [inputs.modbus] modbus: send 0a 03 10 04 00 02 80 71
2021-05-11T11:31:55Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:31:55Z D! [inputs.modbus] got holding@4100[2]: [0 0 0 0]
2021-05-11T11:31:55Z D! [inputs.modbus]   field Watts Total-CH1 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:31:55Z D! [inputs.modbus] modbus: send 0a 03 10 6a 00 02 e1 ac
2021-05-11T11:31:55Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:31:55Z D! [inputs.modbus] got holding@4202[2]: [0 0 0 0]
2021-05-11T11:31:55Z D! [inputs.modbus]   field Total Current-2 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:31:59Z D! [outputs.file] Wrote batch of 2 metrics in 615.843µs
2021-05-11T11:31:59Z D! [outputs.file] Buffer fullness: 0 / 10000 metrics
2021-05-11T11:32:00Z D! [inputs.modbus] modbus: send 0a 03 10 04 00 02 80 71
2021-05-11T11:32:00Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:32:00Z D! [inputs.modbus] got holding@4100[2]: [0 0 0 0]
2021-05-11T11:32:00Z D! [inputs.modbus]   field Watts Total-CH1 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:32:00Z D! [inputs.modbus] modbus: send 0a 03 10 6a 00 02 e1 ac
2021-05-11T11:32:00Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:32:00Z D! [inputs.modbus] got holding@4202[2]: [0 0 0 0]
2021-05-11T11:32:00Z D! [inputs.modbus]   field Total Current-2 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:32:05Z D! [inputs.modbus] modbus: send 0a 03 10 04 00 02 80 71
2021-05-11T11:32:05Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:32:05Z D! [inputs.modbus] got holding@4100[2]: [0 0 0 0]
2021-05-11T11:32:05Z D! [inputs.modbus]   field Watts Total-CH1 with offset 0 with len 4: [0 0 0 0] --> 0
2021-05-11T11:32:05Z D! [inputs.modbus] modbus: send 0a 03 10 6a 00 02 e1 ac
2021-05-11T11:32:05Z D! [inputs.modbus] modbus: recv 0a 03 04 00 00 00 00 40 f3
2021-05-11T11:32:05Z D! [inputs.modbus] got holding@4202[2]: [0 0 0 0]
2021-05-11T11:32:05Z D! [inputs.modbus]   field Total Current-2 with offset 0 with len 4: [0 0 0 0] --> 0

[rwalli]

workarounds = { close_connection_after_gather = true }

is working for me.

[srebhan]

@rwalli btw using workarounds.close_connection_after_gather = true should also work according to the TOML syntax or

[inputs.modbus.workarounds]
    close_connection_after_gather = true

:-)

Thanks for testsing!

[Hipska]

Any reason to go for the workarounds = { } notation instead of [inputs.modbus.workarounds]?

[srebhan]

Any reason to go for the workarounds = { } notation instead of [inputs.modbus.workarounds]?

No special intention behind it. It just matches the register definition a bit better, but if you insist on the [inputs.modbus.workarounds] notation for the sample it's also fine with me. However, @rwalli is right, you cannot configure other options afterwards as everything is then assigned to the workarounds table. That's the downside of having no grouping in this part of the TOML syntax.

[Hipska]

It seems like the [] notation seems more preferred by telegraf/InfluxDB?

[srebhan]

@Hipska I agree, however using this notation will probably lead to problems for less-experienced users as this

[[inputs.modbus]]
    ...
    holding_registers = [
        { name = "power_factor", byte_order = "AB",   data_type = "FIXED", scale=0.01,  address = [8]},
        { name = "voltage",      byte_order = "AB",   data_type = "FIXED", scale=0.1,   address = [0]},
        { name = "energy",       byte_order = "ABCD", data_type = "FIXED", scale=0.001, address = [5,6]}
    ]

    [inputs.modbus.workarounds]
        pause_between_requests = "100ms"

will work just fine. However, this

[[inputs.modbus]]
    ...
    [inputs.modbus.workarounds]
        pause_between_requests = "100ms"

    holding_registers = [
        { name = "power_factor", byte_order = "AB",   data_type = "FIXED", scale=0.01,  address = [8]},
        { name = "voltage",      byte_order = "AB",   data_type = "FIXED", scale=0.1,   address = [0]},
        { name = "energy",       byte_order = "ABCD", data_type = "FIXED", scale=0.001, address = [5,6]}
    ]

will fail as now holding_registers actually becomes inputs.modbus.workarounds.holding_registers instead of inputs.modbus.holding_registers.

In contrast

[[inputs.modbus]]
    ...
    workarounds = {
        pause_between_requests = "100ms"
    }

    holding_registers = [
        { name = "power_factor", byte_order = "AB",   data_type = "FIXED", scale=0.01,  address = [8]},
        { name = "voltage",      byte_order = "AB",   data_type = "FIXED", scale=0.1,   address = [0]},
        { name = "energy",       byte_order = "ABCD", data_type = "FIXED", scale=0.001, address = [5,6]}
    ]

will work in both positions due to the explicit start { and end } markers.

Should we really put the fragile formatting in the example?

[Hipska]

I agree, but just saying it has always been like this. See for example tag/field filtering documentation…

[telegraf-tiger]

Looks like new artifacts were built from this PR. Get them here!

Artifact URLs

• x86_64.rpm

• freebsd_amd64.tar.gz

• linux_amd64.tar.gz

• amd64.deb

• armel.rpm

• linux_armel.tar.gz

• armel.deb

• ppc64le.rpm

• linux_ppc64le.tar.gz

• ppc64el.deb

• armv6hl.rpm

• freebsd_armv7.tar.gz

• linux_armhf.tar.gz

• armhf.deb

• i386.rpm

• freebsd_i386.tar.gz

• linux_i386.tar.gz

• i386.deb

• static_linux_amd64.tar.gz

• s390x.rpm

• linux_s390x.tar.gz

• s390x.deb

• linux_mipsel.tar.gz

• mipsel.deb

• aarch64.rpm

• linux_arm64.tar.gz

• arm64.deb

• linux_mips.tar.gz

• mips.deb

• darwin_amd64.tar.gz

• windows_amd64.zip

• windows_i386.zip

[telegraf-tiger]

📦 Looks like new artifacts were built from this PR.

Expand this list to get them here! 🐯

Artifact URLs

DEB	RPM	TAR GZ	ZIP
amd64.deb	aarch64.rpm	darwin_amd64.tar.gz	windows_amd64.zip
arm64.deb	armel.rpm	freebsd_amd64.tar.gz	windows_i386.zip
armel.deb	armv6hl.rpm	freebsd_armv7.tar.gz
armhf.deb	i386.rpm	freebsd_i386.tar.gz
i386.deb	ppc64le.rpm	linux_amd64.tar.gz
mips.deb	s390x.rpm	linux_arm64.tar.gz
mipsel.deb	x86_64.rpm	linux_armel.tar.gz
ppc64el.deb		linux_armhf.tar.gz
s390x.deb		linux_i386.tar.gz
		linux_mips.tar.gz
		linux_mipsel.tar.gz
		linux_ppc64le.tar.gz
		linux_s390x.tar.gz
		static_linux_amd64.tar.gz