modbus_plugin

Documentation

Index

• Variables
• type ModbusDataItemWithAddress
• type ModbusInput
  • func (m *ModbusInput) Close(context.Context) error
  • func (m *ModbusInput) Connect(context.Context) error
  • func (m *ModbusInput) CreateBatchesFromAddresses(addresses []ModbusDataItemWithAddress) (RequestSet, error)
  • func (m *ModbusInput) ReadBatch(ctx context.Context) (service.MessageBatch, service.AckFunc, error)
• type RequestSet

Variables

var ModbusConfigSpec = service.NewConfigSpec().
	Summary("Creates an input that reads data from Modbus devices. Created & maintained by the United Manufacturing Hub. About us: www.umh.app").
	Description("This input plugin enables Benthos to read data directly from Modbus devices using the Modbus protocol.").
	Field(service.NewDurationField("timeBetweenReads").Description("The time between two reads of a Modbus device. Useful if you want to read the device every x seconds. Not to be confused with TimeBetweenRequests.").Default("1s")).
	Field(service.NewStringField("controller").Description("The Modbus controller address, e.g., 'tcp://localhost:502'").Default("tcp://localhost:502")).
	Field(service.NewStringField("transmissionMode").Description("Transmission mode: 'TCP', 'RTUOverTCP', or 'ASCIIOverTCP'").Default("TCP")).
	Field(service.NewIntField("slaveID").Description("Slave ID of the Modbus device").Default(1)).
	Field(service.NewIntListField("slaveIDs").Description("Slave ID of the Modbus device").Default([]int{1})).
	Field(service.NewDurationField("timeout").Description("").Default("1s")).
	Field(service.NewIntField("busyRetries").Description("Maximum number of retries when the device is busy").Default(3)).
	Field(service.NewDurationField("busyRetriesWait").Description("Time to wait between retries when the device is busy").Default("200ms")).
	Field(service.NewStringField("optimization").Description("Request optimization algorithm: 'none' or 'max_insert'").Default("none")).
	Field(service.NewIntField("optimizationMaxRegisterFill").Description("Maximum number of registers to insert for optimization").Default(50)).
	Field(service.NewStringField("byteOrder").Description("Byte order: 'ABCD', 'DCBA', 'BADC', or 'CDAB'").Default("ABCD")).
	Field(service.NewObjectField("workarounds",
		service.NewDurationField("pauseAfterConnect").Description("Pause after connect to delay the first request").Default("0s"),
		service.NewBoolField("oneRequestPerField").Description("Send each field in a separate request").Default(false),
		service.NewBoolField("readCoilsStartingAtZero").Description("Read coils starting at address 0 instead of 1").Default(false),
		service.NewStringField("stringRegisterLocation").Description("String byte-location in registers: 'lower', 'upper', or empty for both").Default(""),
		service.NewDurationField("timeBetweenRequests").Description("imeBetweenRequests is the time between two requests to the same device. Useful to avoid flooding the device. Not to be confused with TimeBetweenReads.").Default("0s")).
		Description("Modbus workarounds. Required by some devices to work correctly. Should be left alone by default and must not be changed unless necessary.")).
	Field(service.NewObjectListField("addresses",
		service.NewStringField("name").Description("Field name"),
		service.NewStringField("register").Description("Register type: 'coil', 'discrete', 'holding', or 'input'").Default("holding"),
		service.NewIntField("address").Description("Address of the register to query"),
		service.NewStringField("type").Description("Data type of the field"),
		service.NewIntField("length").Description("Number of registers, only valid for STRING type").Default(0),
		service.NewIntField("bit").Description("Bit of the register, only valid for BIT type").Default(0),
		service.NewFloatField("scale").Description("Factor to scale the variable with").Default(0.0),
		service.NewStringField("output").Description("Type of resulting field: 'INT64', 'UINT64', 'FLOAT64', or 'native'").Default("")).
		Description("List of Modbus addresses to read"))

ModbusConfigSpec defines the configuration options available for the ModbusInput plugin. It outlines the required information to establish a connection with the Modbus device and the data to be read.

Types

type ModbusDataItemWithAddress

type ModbusDataItemWithAddress struct {
	Name     string // Field Name
	Register string // Register type. Can be "coil", "discrete", "holding" or "input". Defaults to "holding".
	Address  uint16 // Address of the register to query. For coil and discrete inputs this is the bit address.

	// Type is the type of the modbus field
	// Can be
	// BIT (single bit of a register)
	//	INT8L, INT8H, UINT8L, UINT8H (low and high byte variants)
	//	INT16, UINT16, INT32, UINT32, INT64, UINT64 and
	//	FLOAT16, FLOAT32, FLOAT64 (IEEE 754 binary representation)
	//	STRING (byte-sequence converted to string)
	Type string

	// Length is the number of registers, ONLY valid for STRING type. Defaults to 1.
	Length uint16

	// Bit is the bit of the register, ONLY valid for BIT type. Defaults to 0.
	Bit uint16

	// Scale is the factor to scale the variable with. Defaults to 1.0.
	Scale float64

	// Output is the type of resulting field, can be INT64, UINT64 or FLOAT64. Defaults to FLOAT64 if
	// "scale" is provided and to the input "type" class otherwise (i.e. INT* -> INT64, etc).
	Output string

	ConverterFunc converterFunc
}

ModbusDataItemWithAddress struct defines the structure for the data items to be read from the Modbus device.

type ModbusInput

type ModbusInput struct {

	// Benthos
	TimeBetweenReads time.Duration // The time between two reads of a Modbus device. Useful if you want to read the device every x seconds. Defaults to 1s. Not to be confused with TimeBetweenRequests.

	// Standard
	Controller       string        // e.g., "tcp://localhost:502"
	TransmissionMode string        // Can be "TCP" (default), "RTUOverTCP", "ASCIIOverTCP"\
	SlaveIDs         []byte        // This allows to fetch the same Addresses from different SlaveIDs
	Timeout          time.Duration // Timeout for the connection
	BusyRetries      int           // Maximum number of retries when the device is busy
	BusyRetriesWait  time.Duration // Time to wait between retries when the device is busy

	// Optimization Request optimization algorithm across metrics
	//  |---none       -- Do not perform any optimization and just group requests
	//  |                 within metrics (default)
	//  |---max_insert -- Collate registers across all defined metrics and fill in
	//                    holes to optimize the number of requests.
	Optimization string

	// OptimizationMaxRegisterFill is the maximum number of registers the optimizer is allowed to insert between
	// non-consecutive registers to save requests.
	// This option is only used for the 'max_insert' optimization strategy and
	// effectively denotes the hole size between registers to fill.
	OptimizationMaxRegisterFill int

	// ByteOrder is the byte order of the registers. The default is big endian.
	//  |---ABCD -- Big Endian (Motorola)
	//  |---DCBA -- Little Endian (Intel)
	//  |---BADC -- Big Endian with byte swap
	//  |---CDAB -- Little Endian with byte swap
	ByteOrder string

	// Modbus Workarounds. Required by some devices to work correctly
	PauseAfterConnect       time.Duration // PauseAfterConnect is the pause after connect delays the first request by the specified time. This might be necessary for (slow) devices.
	OneRequestPerField      bool          // OneRequestPerField sends each field in a separate request. This might be necessary for some devices. see https://github.com/influxdata/telegraf/issues/12071.
	ReadCoilsStartingAtZero bool          // ReadCoilsStartingAtZero reads coils starting at address 0 instead of 1. This might be necessary for some devices. See https://github.com/influxdata/telegraf/issues/8905
	TimeBetweenRequests     time.Duration // TimeBetweenRequests is the time between two requests to the same device. Useful to avoid flooding the device. Defaults to 0s. Not to be confused with TimeBetweenReads.

	// StringRegisterLocation is the String byte-location in registers AFTER byte-order conversion.
	// Some device (e.g. EM340) place the string byte in only the upper
	// or lower byte location of a register
	// see https://github.com/influxdata/telegraf/issues/14748
	// Available settings:
	//   lower -- use only lower byte of the register i.e. 00XX 00XX 00XX 00XX
	//   upper -- use only upper byte of the register i.e. XX00 XX00 XX00 XX00
	// By default both bytes of the register are used i.e. XXXX XXXX.
	StringRegisterLocation string

	// Addresses is a list of Modbus addresses to read
	Addresses []ModbusDataItemWithAddress

	// Requests is the auto-generated list of requests to be made
	// They are creates based on the addresses and the optimization strategy
	RequestSet RequestSet

	// Internal
	Handler        modbus.ClientHandler
	SlaveMutex     sync.Mutex // Add a mutex to avoid mixing up slave responses
	CurrentSlaveID byte       // The current slave ID
	Client         modbus.Client
	Log            *service.Logger

	LastHeartbeatMessageReceived atomic.Uint32
	LastMessageReceived          atomic.Uint32
}

ModbusInput struct defines the structure for our custom Benthos input plugin. It holds the configuration necessary to establish a connection with a Modbus PLC,

func (*ModbusInput) Close

func (m *ModbusInput) Close(context.Context) error

func (*ModbusInput) Connect

func (m *ModbusInput) Connect(context.Context) error

func (*ModbusInput) CreateBatchesFromAddresses

func (m *ModbusInput) CreateBatchesFromAddresses(addresses []ModbusDataItemWithAddress) (RequestSet, error)

func (*ModbusInput) ReadBatch

func (m *ModbusInput) ReadBatch(ctx context.Context) (service.MessageBatch, service.AckFunc, error)

type RequestSet

type RequestSet struct {
	// contains filtered or unexported fields
}