modbus_master.h File Reference

Modbus TCP master codec + register scanner (PROTOCORE_ENABLE_MODBUS_MASTER). More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	ModbusMasterNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Functions
	PROTOCORE_NS_LAYOUT (ModbusMasterNs, build_read, parse_response, build_read_bits, parse_read_bits_response, build_write_single_coil, build_write_multiple_coils, build_write_single, build_write_multiple, parse_write_response, build_mask_write, build_read_write_multiple, parse_mask_write_response)
size_t	protocore_modbus_master_build_read (uint8_t *work, uint8_t fc, uint16_t txid, uint8_t unit, uint16_t start, uint16_t count, uint8_t *out, size_t cap)
	Build a read-request ADU (FC 0x03 holding or 0x04 input registers).
int	protocore_modbus_master_parse_response (uint8_t *work, const uint8_t *adu, size_t len, uint16_t *regs_out, size_t max_regs, uint8_t *exception_out)
	Parse a read-response ADU into register values.
size_t	protocore_modbus_master_build_read_bits (uint8_t *work, uint8_t fc, uint16_t txid, uint8_t unit, uint16_t start, uint16_t count, uint8_t *out, size_t cap)
	Build a read-bits request ADU (FC 0x01 coils or 0x02 discrete .
int	protocore_modbus_master_parse_read_bits_response (uint8_t *work, const uint8_t *adu, size_t len, uint16_t count, uint8_t *bits_out, size_t max_bits, uint8_t *exception_out)
	Parse a read-bits response ADU (FC 0x01 / 0x02) into one byte (0/1).
size_t	protocore_modbus_master_build_write_single_coil (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t addr, proto_bool on, uint8_t *out, size_t cap)
	Build a Write Single Coil request ADU (FC 0x05).
size_t	protocore_modbus_master_build_write_multiple_coils (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t start, const uint8_t *bits, uint16_t count, uint8_t *out, size_t cap)
	Build a Write Multiple Coils request ADU (FC 0x0F).
size_t	protocore_modbus_master_build_write_single (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t addr, uint16_t value, uint8_t *out, size_t cap)
	Build a Write Single Register request ADU (FC 0x06).
size_t	protocore_modbus_master_build_write_multiple (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t start, const uint16_t *values, uint16_t count, uint8_t *out, size_t cap)
	Build a Write Multiple Registers request ADU (FC 0x10).
int	protocore_modbus_master_parse_write_response (uint8_t *work, const uint8_t *adu, size_t len, uint16_t *addr_out, uint8_t *exception_out)
	Parse a write-response ADU (FC 0x05, 0x06, 0x0F, or 0x10). A normal .
size_t	protocore_modbus_master_build_mask_write (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t addr, uint16_t and_mask, uint16_t or_mask, uint8_t *out, size_t cap)
	Build a Mask Write Register request ADU (FC 0x16). The slave .
size_t	protocore_modbus_master_build_read_write_multiple (uint8_t *work, uint16_t txid, uint8_t unit, uint16_t read_start, uint16_t read_count, uint16_t write_start, const uint16_t *values, uint16_t write_count, uint8_t *out, size_t cap)
	Build a Read/Write Multiple Registers request ADU (FC 0x17): write.
int	protocore_modbus_master_parse_mask_write_response (uint8_t *work, const uint8_t *adu, size_t len, uint16_t *addr_out, uint16_t *and_out, uint16_t *or_out, uint8_t *exception_out)
	Parse a Mask Write Register response (FC 0x16), which echoes the .

Variables
PROTOCORE_NS ModbusMasterNs ModbusMaster	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

Modbus TCP master codec + register scanner (PROTOCORE_ENABLE_MODBUS_MASTER).

The master/client side of Modbus: build a read-request ADU (MBAP header + PDU) and parse the slave's response into register values, so an application can poll or auto-discover a slave's registers. Pure - no sockets, no heap - so it is host-tested as a full round-trip against the slave codec (Modbus.process_adu). The app supplies the transport (send the ADU, receive the reply).

Auto-discovery pattern: walk the address space one read at a time; a register exists where the response parses without a Modbus exception.

work is bytes the CALLER holds. This module reads none of them: it carries nothing between calls, so there is no state to keep and nothing to wipe. The parameter is there so a caller drives every namespace the same way.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file modbus_master.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	ModbusMasterNs	,
		build_read	,
		parse_response	,
		build_read_bits	,
		parse_read_bits_response	,
		build_write_single_coil	,
		build_write_multiple_coils	,
		build_write_single	,
		build_write_multiple	,
		parse_write_response	,
		build_mask_write	,
		build_read_write_multiple	,
		parse_mask_write_response
	)

protocore_modbus_master_build_read()

size_t protocore_modbus_master_build_read	(	uint8_t *	work,
		uint8_t	fc,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	start,
		uint16_t	count,
		uint8_t *	out,
		size_t	cap
	)

Build a read-request ADU (FC 0x03 holding or 0x04 input registers).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
fc	MODBUS_FC_READ_HOLDING_REGS (0x03) or MODBUS_FC_READ_INPUT_REGS (0x04)
txid	transaction id echoed by the slave (caller's correlation token)
unit	unit / slave id
start	first register address
count	number of registers (1..125)
out	destination buffer
cap	destination capacity (>= 12)

Returns

The size_t.

protocore_modbus_master_parse_response()

int protocore_modbus_master_parse_response	(	uint8_t *	work,
		const uint8_t *	adu,
		size_t	len,
		uint16_t *	regs_out,
		size_t	max_regs,
		uint8_t *	exception_out
	)

Parse a read-response ADU into register values.

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
adu	response bytes (MBAP + PDU)
len	response length
regs_out	destination for parsed 16-bit register values
max_regs	capacity of regs_out
exception_out	set to the Modbus exception code if the slave returned one (then the function returns 0

Returns

The int.

protocore_modbus_master_build_read_bits()

size_t protocore_modbus_master_build_read_bits	(	uint8_t *	work,
		uint8_t	fc,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	start,
		uint16_t	count,
		uint8_t *	out,
		size_t	cap
	)

Build a read-bits request ADU (FC 0x01 coils or 0x02 discrete .

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
fc	MODBUS_FC_READ_COILS (0x01) or ::MODBUS_FC_READ_DISCRETE_INPUTS (0x02)
txid	transaction id echoed by the slave
unit	unit / slave id
start	first bit address
count	number of bits (1..2000)
out	destination buffer
cap	destination capacity (>= 12)

Returns

The size_t.

protocore_modbus_master_parse_read_bits_response()

int protocore_modbus_master_parse_read_bits_response	(	uint8_t *	work,
		const uint8_t *	adu,
		size_t	len,
		uint16_t	count,
		uint8_t *	bits_out,
		size_t	max_bits,
		uint8_t *	exception_out
	)

Parse a read-bits response ADU (FC 0x01 / 0x02) into one byte (0/1).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
adu	Adu
len	Len
count	the number of bits requested (1..2000)
bits_out	destination for count unpacked bits (nullable to just validate)
max_bits	capacity of bits_out
exception_out	set to the Modbus exception code if the slave returned one (then 0 is returned)

Returns

The int.

protocore_modbus_master_build_write_single_coil()

size_t protocore_modbus_master_build_write_single_coil	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	addr,
		proto_bool	on,
		uint8_t *	out,
		size_t	cap
	)

Build a Write Single Coil request ADU (FC 0x05).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	Txid
unit	Unit
addr	Addr
on	the coil value; encoded on the wire as 0xFF00 (on) or 0x0000 (off) per the Modbus spec
out	Out
cap	destination capacity (>= 12)

Returns

The size_t.

protocore_modbus_master_build_write_multiple_coils()

size_t protocore_modbus_master_build_write_multiple_coils	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	start,
		const uint8_t *	bits,
		uint16_t	count,
		uint8_t *	out,
		size_t	cap
	)

Build a Write Multiple Coils request ADU (FC 0x0F).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	Txid
unit	Unit
start	Start
bits	one byte (0/1) per coil to write; packed LSB-first into the wire bytes
count	number of coils (1..1968)
out	Out
cap	destination capacity (>= 14 + ceil(count/8))

Returns

The size_t.

protocore_modbus_master_build_write_single()

size_t protocore_modbus_master_build_write_single	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	addr,
		uint16_t	value,
		uint8_t *	out,
		size_t	cap
	)

Build a Write Single Register request ADU (FC 0x06).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	transaction id echoed by the slave
unit	unit / slave id
addr	register address
value	16-bit value to write
out	destination buffer
cap	destination capacity (>= 12)

Returns

The size_t.

protocore_modbus_master_build_write_multiple()

size_t protocore_modbus_master_build_write_multiple	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	start,
		const uint16_t *	values,
		uint16_t	count,
		uint8_t *	out,
		size_t	cap
	)

Build a Write Multiple Registers request ADU (FC 0x10).

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	transaction id echoed by the slave
unit	unit / slave id
start	first register address
values	the count register values
count	number of registers (1..123)
out	destination buffer
cap	destination capacity (>= 13 + 2*count)

Returns

The size_t.

protocore_modbus_master_parse_write_response()

int protocore_modbus_master_parse_write_response	(	uint8_t *	work,
		const uint8_t *	adu,
		size_t	len,
		uint16_t *	addr_out,
		uint8_t *	exception_out
	)

Parse a write-response ADU (FC 0x05, 0x06, 0x0F, or 0x10). A normal .

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
adu	response bytes (MBAP + PDU)
len	response length
addr_out	set to the echoed address / start (nullable)
exception_out	set to the Modbus exception code if the slave returned one (then 0 is returned)

Returns

The int.

protocore_modbus_master_build_mask_write()

size_t protocore_modbus_master_build_mask_write	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	addr,
		uint16_t	and_mask,
		uint16_t	or_mask,
		uint8_t *	out,
		size_t	cap
	)

Build a Mask Write Register request ADU (FC 0x16). The slave .

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	Txid
unit	Unit
addr	Addr
and_mask	And mask
or_mask	Or mask
out	Out
cap	destination capacity (>= 14)

Returns

The size_t.

protocore_modbus_master_build_read_write_multiple()

size_t protocore_modbus_master_build_read_write_multiple	(	uint8_t *	work,
		uint16_t	txid,
		uint8_t	unit,
		uint16_t	read_start,
		uint16_t	read_count,
		uint16_t	write_start,
		const uint16_t *	values,
		uint16_t	write_count,
		uint8_t *	out,
		size_t	cap
	)

Build a Read/Write Multiple Registers request ADU (FC 0x17): write.

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
txid	Txid
unit	Unit
read_start	/ read_count the registers to read back (1..125)
read_count	Read count
write_start	/ write_count the registers to write (1..121); values holds write_count words
values	Values
write_count	Write count
out	Out
cap	destination capacity (>= 17 + 2*write_count)

Returns

The size_t.

protocore_modbus_master_parse_mask_write_response()

int protocore_modbus_master_parse_mask_write_response	(	uint8_t *	work,
		const uint8_t *	adu,
		size_t	len,
		uint16_t *	addr_out,
		uint16_t *	and_out,
		uint16_t *	or_out,
		uint8_t *	exception_out
	)

Parse a Mask Write Register response (FC 0x16), which echoes the .

Parameters

work	PROTOCORE_MODBUS_MASTER_BORROW bytes the caller took. Not held past the call.
adu	Adu
len	Len
addr_out	/ and_out / or_out receive the echoed fields (each nullable)
and_out	And out
or_out	Or out
exception_out	set to the Modbus exception code if the slave returned one

Returns

The int.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS ModbusMasterNs ModbusMaster PROTOCORE_UNUSED

Initial value:

= {
    .build_read = protocore_modbus_master_build_read,
    .parse_response = protocore_modbus_master_parse_response,
    .build_read_bits = protocore_modbus_master_build_read_bits,
    .parse_read_bits_response = protocore_modbus_master_parse_read_bits_response,
    .build_write_single_coil = protocore_modbus_master_build_write_single_coil,
    .build_write_multiple_coils = protocore_modbus_master_build_write_multiple_coils,
    .build_write_single = protocore_modbus_master_build_write_single,
    .build_write_multiple = protocore_modbus_master_build_write_multiple,
    .parse_write_response = protocore_modbus_master_parse_write_response,
    .build_mask_write = protocore_modbus_master_build_mask_write,
    .build_read_write_multiple = protocore_modbus_master_build_read_write_multiple,
    .parse_mask_write_response = protocore_modbus_master_parse_mask_write_response}

Module namespace.

Definition at line 225 of file modbus_master.h.