weModbus.h File Reference

Modbus functions for Raspberry Pis. More...

#include "weUtil.h"

Data Structures
struct	modRS_t
	Structure for Modbus RS485 (RTU). More...

Typedefs
typedef enum modRS485state_t	modRS485state_t
	A definition for possible states of a Modbus RS485 interface. More...

Enumerations
enum	modRS485state_t {   RS_OFF , RS_ON , RS_INICOM , RS_ERR_ANY ,   RS_ERR_CTX , RS_ERR_CON , RS_ERR_SLA , RS_ERR_BAD ,   RS_OFF , RS_ON , RS_INICOM , RS_ERR_ANY ,   RS_ERR_CTX , RS_ERR_CON , RS_ERR_SLA , RS_ERR_BAD }
	A definition for possible states of a Modbus RS485 interface. More...

Functions
void	modRSclose (modRS_t *modRS)
	Close a Modbus RS link and destroy the (libmodbus) structure. More...
int	modRSconnect (modRS_t *modRS, int currentSlave)
	Connect a the Modbus (libmodbus) structure for RS485 (RTU). More...
int	modRSctxNew (modRS_t *modRS, int currentSlave)
	Make a new Modbus (libmodbus) structure for RS485. More...
int	modRSswitchSlave (modRS_t *modRS, int currentSlave)
	Switch the slave on a connected Modbus (libmodbus) structure for RS485. More...
int	parseModPort (const char *str)
	Parse string as Modbus port with checks. More...
void	reg2val32 (dualReg_t *const dest, dualReg_t const *const source)
	Copy float (32 bit) Modbus input to correctly ordered value. More...
uint16_t	regs2string (char *dest, uint16_t *source, int n)
	Copy a sequence of character pairs from registers to a string. More...
void	regs2vals32 (float *const dest, dualReg_t const *const source, int const n)
	Copy n float (32 bit) Modbus input to correctly ordered values. More...

Detailed Description

Modbus functions for Raspberry Pis.

Copyright  (c)  2019   Albrecht Weinert
weinert-automation.de      a-weinert.de
 
    /         /      /\
   /         /___   /  \      |
   \        /____\ /____\ |  _|__
    \  /\  / \    /      \|   |
     \/  \/   \__/        \__/|_                                 

Revision history

Rev. 72 12.11.2024
Rev.  38 22.08.2017 : new
Rev. 187 14.10.2018 : minor typos
Rev. 191 15.02.2019 : minor comment text changes
Rev. 212 04.08.2019 : regs2string added
Rev. 216 31.08.2019 : modRS_t int conErr removed (never used)
Rev. 260 06.11.2024 : functions reduced to Modbus RTU for smart meters

This was a supplementary (basic) library. The functions and structures defined here did work with Stéphane Raimbault's Modbus library libmodbus.

Some structures and utilities are to support smart meters like e.g. SDM230Modbus, SMD630Modbus and SDM538Modbus as servers/slaves, especially their handling of (32 bit) float values.

Typedef Documentation

modRS485state_t

typedef enum modRS485state_t modRS485state_t

A definition for possible states of a Modbus RS485 interface.

With Modbus TCP one has not to handle the (Ethernet or WLAN) interface. One just has to listen at a port or connect to IPadress:port. The handling of multiple connections on the network is done by the operating system and the network infrastructure.

With an RS485 "bus" connecting Modbus devices it's different. Every device's software has to handle the physical interface. Usually only Modbus devices can be at that "bus" — 2 to 247. The communication is client request --> server response (as always), but request response pairs to/from different servers cannot overlap. (Additionally the telegrams are short and slow.)

Hence with RS485 (RTU) the handling of multiple (server) connections has to be implemented in the client application, and the RS485 interface/bus state has to be separated from (multiple) server-link states.
With RS232 the complications and disadvantages are the same while being restricted to point to point (P2P, no bus).

Enumeration Type Documentation

modRS485state_t

enum modRS485state_t

A definition for possible states of a Modbus RS485 interface.

With Modbus TCP one has not to handle the (Ethernet or WLAN) interface. One just has to listen at a port or connect to IPadress:port. The handling of multiple connections on the network is done by the operating system and the network infrastructure.

With an RS485 "bus" connecting Modbus devices it's different. Every device's software has to handle the physical interface. Usually only Modbus devices can be at that "bus" — 2 to 247. The communication is client request --> server response (as always), but request response pairs to/from different servers cannot overlap. (Additionally the telegrams are short and slow.)

Hence with RS485 (RTU) the handling of multiple (server) connections has to be implemented in the client application, and the RS485 interface/bus state has to be separated from (multiple) server-link states.
With RS232 the complications and disadvantages are the same while being restricted to point to point (P2P, no bus).

Enumerator
RS_OFF	do not use Modbus RS485 link (no ctx structure made)
RS_ON	may be usable, but totally uninitialised (no com.)
RS_INICOM	initialised (ready for communication)
RS_ERR_ANY	no concrete error, lower bound of all error states
RS_ERR_CTX	no structure made (hopeless when re-occurring)
RS_ERR_CON	open serial failed
RS_ERR_SLA	any slave error requiring re-open
RS_ERR_BAD	recurring error in usage (try conn. re-init)
RS_OFF	do not use Modbus RS485 link (no ctx structure made)
RS_ON	may be usable, but totally uninitialised (no com.)
RS_INICOM	initialised (ready for communication)
RS_ERR_ANY	no concrete error, lower bound of all error states
RS_ERR_CTX	no structure made (hopeless when re-occurring)
RS_ERR_CON	open serial failed
RS_ERR_SLA	any slave error requiring re-open
RS_ERR_BAD	recurring error in usage (try conn. re-init)

Function Documentation

parseModPort()

int parseModPort

(

const char *

str

)

Parse string as Modbus port with checks.

502 or 1024..65535

modRSctxNew()

int modRSctxNew	(	modRS_t *	modRS,
		int	currentSlave
	)

Make a new Modbus (libmodbus) structure for RS485.

This function makes a new modTCP.ctx according to .addr and .port; it does NOT check NOR change .rsState.

Parameters

modRS	pointer to modRS_t structure to be used
currentSlave	1..247 sets the slave number; sets .currentSlave

Returns

0 : OK; else: error: -1: modRS null; -2: slave number: -3: no ctx

modRSconnect()

int modRSconnect	(	modRS_t *	modRS,
		int	currentSlave
	)

Connect a the Modbus (libmodbus) structure for RS485 (RTU).

This function makes a new modRS.ctx according to .device and else. Then it "connects" it. On success 0 is returned. On failure -1 is returned and modTCP.ctx will be destroyed.

This function does NOT check NOR change .rsState.

Parameters

modRS	pointer to modRS_t structure to be used
currentSlave	if 1..247; sets the slave number to be used next and changes .currentSlave

modRSswitchSlave()

int modRSswitchSlave	(	modRS_t *	modRS,
		int	currentSlave
	)

Switch the slave on a connected Modbus (libmodbus) structure for RS485.

This function changes nothing on a functional and connected modRS.ctx setting than the slave number.

Modbus RS485 (RTU) can handle multiple slaves on the same serial interface. This has to be one at a time in a pure sequential matter: hence this slave switching.
With RS232 the one slave's number once correctly established would stay fixed.

Unfortunately (by a libmodbus deficiency) a communication error of one slave would require a total new connect (modRSconnect()) for all slaves; switching to a "good slave" won't help.

Parameters

modRS	pointer to modRS_t structure to be used
currentSlave	if 1..247; sets .currentSlave

Returns

-1: error wrong parameter or no modRS; 0: no change or no ctx; 1..247: changed currentSlave; OK

modRSclose()

void modRSclose

(

modRS_t *

modRS

)

Close a Modbus RS link and destroy the (libmodbus) structure.

This function destroys modRS.ctx (if existing). .rsState will not be changed.

Parameters

modRS

pointer to modRS_t structure to be used

reg2val32()

void reg2val32	(	dualReg_t *const	dest,
		dualReg_t const *const	source
	)

Copy float (32 bit) Modbus input to correctly ordered value.

This function copies a 32bit (e.g.) float value input from Modbus — with correct byte ordering at 16 bit level (!) — to a correctly ordered (32 bit) value.
Destination and source pointers may be the same, but not NULL.
The swap of the 16-bit parts only occurs, when the platform is little endian.
See also: PLATFlittlE and regs2vals32()

Parameters

dest	the dual registers to store the result in
source	the dual registers with the potentially wrong endianess

regs2vals32()

void regs2vals32	(	float *const	dest,
		dualReg_t const *const	source,
		int const	n
	)

Copy n float (32 bit) Modbus input to correctly ordered values.

This function copies n 32bit (e.g.) float values input from Modbus — with correct byte ordering at 16 bit level (!) — to correctly ordered (32 bit) values.
Destination and source pointers may be the same, but not NULL.
The swap of the 16-bit parts only occurs, when the platform is little endian.
See also: PLATFlittlE and reg2val32()

Parameters

dest	the array of dual registers to store the result in
source	the array of dual registers with potentially wrong endianess
n	the number of dual registers to treat

regs2string()

uint16_t regs2string	(	char *	dest,
		uint16_t *	source,
		int	n
	)

Copy a sequence of character pairs from registers to a string.

Growatt inverter holding registers, for example, deliver strings as pairs of ASCII characters in consecutive registers. If the number of characters is odd the last register holds just one character. Some of those strings in registers are 0-terminated and some are not. In the first case the transfer stops at the 0, in the latter case a 0 is appended to the destination string as n+1st character.
The sequence of the two characters in each register is (as usual with Modbus) in wrong order. Hence, memcopy and consorts would fail.

Parameters

dest	the array of characters to store the result in
source	the array registers with wrong character sorting
n	the number of dual registers to treat

Returns

the number of characters transfered to dest including the terminating 0