Modbus notes
Contents
OVERVIEW
This wiki article contains some notes and references on FreeModbus, an opensource C library to support a Modbus protocol stack in stand-alone applications as well as operating system and scheduler based systems. This article also contains a number of links to more general C language references, which discuss function pointers in C, and the type defining of function pointers.
- https://libmodbus.org/ . . . Ubuntu package is 'libmodbus5' and 'libmodbus-dev'
Note: FreeModbus project uses a variable and routine naming scheme where many names begin with one or two lower-case characters. From context in the file ./modbus/mb.c, it looks like 'uc' may stand for 'unsigned char' data type. The starting lower case 'e' stands for 'enumeration':
62 static UCHAR ucMBAddress; 63 static eMBMode eMBCurrentMode;
- 2019-11-08 FRI -
When working with FreeModbus, be sure to pay attention to the versions of protocol available, and likely, we only want to enable one of these. See Modbus/include/mbconfig.h. See also Modbus/include/mb.h for instructions on how to initialize and begin to use an instance of FreeModbus stack in given program. Also mention that eMBPoll() routine may be set up as a task in an RTOS, to realize the periodic polling which is part of the stack's runtime manifestation . . .
Looks like also this function to register callbacks for end-user-device-specific Modbus registers will be important:
eMBErrorCode eMBRegisterCB ( UCHAR ucFunctionCode,
pxMBFunctionHandler pxHandler
)
This function signature part of documentation found at https://www.embedded-solutions.at/en/freemodbus/api-documentation/, which gives Doxygen generated API help in an embedded pane in the browser window on which it is visited.
2019-11-12 Tuesday - trying to figure out how pxMBFunctionHandler is defined . . . from http://www.teamfdi.com/uez/docs/mbproto_8h.html:
Typedefs typedef eMBException(* pxMBFunctionHandler )(UCHAR *pucFrame, USHORT *pusLength)
...from this typedef looks like Modbus routines implemented by the end user/end designer must have parameter lists which match "unsigned char pointer, unsigned integer pointer".
2019-11-13
Further search for FreeModbus callback registering code"
downloads/freemodbus/freemodbus-v1.5.0$ grep -nr pxMBFunctionHandler ./* ./modbus/mb.c:226:eMBRegisterCB( UCHAR ucFunctionCode, pxMBFunctionHandler pxHandler ) ./modbus/include/mbproto.h:72:typedef eMBException( *pxMBFunctionHandler ) ( UCHAR * pucFrame, USHORT * pusLength ); ./modbus/include/mbproto.h:77: pxMBFunctionHandler pxHandler; ./modbus/include/mb.h:266: pxMBFunctionHandler pxHandler )
And the entire section of typedefs from mbproto.h:
/* ----------------------- Type definitions ---------------------------------*/
typedef enum
{
MB_EX_NONE = 0x00,
MB_EX_ILLEGAL_FUNCTION = 0x01,
MB_EX_ILLEGAL_DATA_ADDRESS = 0x02,
MB_EX_ILLEGAL_DATA_VALUE = 0x03,
MB_EX_SLAVE_DEVICE_FAILURE = 0x04,
MB_EX_ACKNOWLEDGE = 0x05,
MB_EX_SLAVE_BUSY = 0x06,
MB_EX_MEMORY_PARITY_ERROR = 0x08,
MB_EX_GATEWAY_PATH_FAILED = 0x0A,
MB_EX_GATEWAY_TGT_FAILED = 0x0B
} eMBException;
typedef eMBException( *pxMBFunctionHandler ) ( UCHAR * pucFrame, USHORT * pusLength );
typedef struct
{
UCHAR ucFunctionCode;
pxMBFunctionHandler pxHandler;
} xMBFunctionHandler;
^ Obscurely defined FreeModbus variables
Where is the following demo/LPC214X/port/port.c variable defined? Does not appear defined in any file of FreeModbus 1.5.0 download. Note however that this may be an LPC microcontroller register name:
VICIntEnable
See http://www.keil.com/dd/vtr/3880/9794.htm for a brief mention of this term. - TMH
^ Modbus frames and framing handling
This search result may not be directly useful to getting a first modbus routine running and testable:
./modbus/include/mbport.h:109:extern BOOL( *pxMBFrameCBByteReceived ) ( void ); Binary file ./modbus/include/.mbport.h.swp matches ./modbus/mb.c:85:BOOL( *pxMBFrameCBByteReceived ) ( void ); ./modbus/mb.c:153: pxMBFrameCBByteReceived = xMBRTUReceiveFSM; ./modbus/mb.c:167: pxMBFrameCBByteReceived = xMBASCIIReceiveFSM;
^ Modbus register input callback routine
Here is a search history, some searches run in the STR71X demo. These variables and routines look more promising in terms of telling us how to implement a routine of our own which properly ties in with FreeModbus library code. What these variables and routines lead us to examine, is how the code developers, us, using FreeModbus can return data from a device to a meaningful place in memory, which FreeModbus then reads and send out along the physical link layer to a given Modbus master.
From the following searches,
1004 grep -nr usRegInputBuf ./* 1005 grep -n pucRegBuffer ./* 1006 # eMBRegInputCB, third token for which to search
We quickly come to the routine named eMBRegInputCB(). It turns out this routine is implemented in various FreeModbus demos, which is to say it is not a FreeModbus library routine. But part of FreeModbus library source calls or needs to call a routine by this name. So it looks like as users of FreeModbus, we are bound to define a routine by this name and with its enumerated return type and parameter list as defined in freemodbus-v1.5.0/modbus/include/mb.h.
Variable usRegInputBuf is in source file simple2.c a static array of bytes, which hold values that a Modbus function returns,
<./simple2.c:42:static unsigned short usRegInputBuf[REG_INPUT_NREGS]; ./simple2.c:76: usRegInputBuf[0]++; ./simple2.c:79: usRegInputBuf[1] = ( unsigned portSHORT )( xLastWakeTime >> 16UL ); ./simple2.c:80: usRegInputBuf[2] = ( unsigned portSHORT )( xLastWakeTime & 0xFFFFUL ); ./simple2.c:82: usRegInputBuf[3] = 33; ./simple2.c:99: ( unsigned char )( usRegInputBuf[iRegIndex] >> 8 ); ./simple2.c:101: ( unsigned char )( usRegInputBuf[iRegIndex] & 0xFF );
We look then at pucRegBuffer because of the following assignments in a callback routine of this demo:
86 eMBErrorCode
87 eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
88 {
89 eMBErrorCode eStatus = MB_ENOERR;
90 int iRegIndex;
91
92 if( ( usAddress >= REG_INPUT_START )
93 && ( usAddress + usNRegs <= REG_INPUT_START + REG_INPUT_NREGS ) )
94 {
95 iRegIndex = ( int )( usAddress - usRegInputStart );
96 while( usNRegs > 0 )
97 {
98 *pucRegBuffer++ =
99 ( unsigned char )( usRegInputBuf[iRegIndex] >> 8 );
100 *pucRegBuffer++ =
101 ( unsigned char )( usRegInputBuf[iRegIndex] & 0xFF );
102 iRegIndex++;
103 usNRegs--;
104 }
105 }
106 else
107 {
108 eStatus = MB_ENOREG;
109 }
110
111 return eStatus;
112 }
Now the question is, which code calls the routine eMBErrorCode eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )? This routine is not called by any code in this specific demo:
$ grep -nr -A 1 eMBRegInputCB ./*
./excoils.c:130:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./excoils.c-131-{
--
./exdisc.c:118:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./exdisc.c-119-{
--
./exholding.c:86:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./exholding.c-87-{
--
./simple2.c:87:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./simple2.c-88-{
--
./simple.c:94:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./simple.c-95-{
Looking now a level or two up and at the FreeModbus library sources . . . there is a longer function in file ./modbus/functions/mbfuncinput.c but worth noting here, as it parses the modbus PDU to figure out what type of PDU read versus write it is, and how many bytes are expected to follow or are being requested. Worth noting the function definition in full here:
/* ----------------------- Start implementation -----------------------------*/
#if MB_FUNC_READ_INPUT_ENABLED > 0
eMBException
eMBFuncReadInputRegister( UCHAR * pucFrame, USHORT * usLen )
{
USHORT usRegAddress;
USHORT usRegCount;
UCHAR *pucFrameCur;
eMBException eStatus = MB_EX_NONE;
eMBErrorCode eRegStatus;
if( *usLen == ( MB_PDU_FUNC_READ_SIZE + MB_PDU_SIZE_MIN ) )
{
usRegAddress = ( USHORT )( pucFrame[MB_PDU_FUNC_READ_ADDR_OFF] << 8 );
usRegAddress |= ( USHORT )( pucFrame[MB_PDU_FUNC_READ_ADDR_OFF + 1] );
usRegAddress++;
usRegCount = ( USHORT )( pucFrame[MB_PDU_FUNC_READ_REGCNT_OFF] << 8 );
usRegCount |= ( USHORT )( pucFrame[MB_PDU_FUNC_READ_REGCNT_OFF + 1] );
/* Check if the number of registers to read is valid. If not
* return Modbus illegal data value exception.
*/
if( ( usRegCount >= 1 )
&& ( usRegCount < MB_PDU_FUNC_READ_REGCNT_MAX ) )
{
/* Set the current PDU data pointer to the beginning. */
pucFrameCur = &pucFrame[MB_PDU_FUNC_OFF];
*usLen = MB_PDU_FUNC_OFF;
/* First byte contains the function code. */
*pucFrameCur++ = MB_FUNC_READ_INPUT_REGISTER;
*usLen += 1;
/* Second byte in the response contain the number of bytes. */
*pucFrameCur++ = ( UCHAR )( usRegCount * 2 );
*usLen += 1;
eRegStatus =
eMBRegInputCB( pucFrameCur, usRegAddress, usRegCount );
/* If an error occured convert it into a Modbus exception. */
if( eRegStatus != MB_ENOERR )
{
eStatus = prveMBError2Exception( eRegStatus );
}
else
{
*usLen += usRegCount * 2;
}
}
else
{
eStatus = MB_EX_ILLEGAL_DATA_VALUE;
}
}
else
{
/* Can't be a valid read input register request because the length
* is incorrect. */
eStatus = MB_EX_ILLEGAL_DATA_VALUE;
}
return eStatus;
}
#endif
user@~/projects/freemodbus-v1.5.0$ grep -nr eMBRegInputCB ./* ./demo/WIN32/demo.cpp:221:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71XGCC/demo.c:101:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/ATSAM3S_FREERTOS/demo.c:168:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/BARE/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/exdisc.c:118:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/excoils.c:130:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/simple2.c:87:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) Binary file ./demo/STR71X/.simple2.c.swp matches ./demo/STR71X/exholding.c:86:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/simple.c:94:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LPC214X/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LINUX/demo.c:264:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LINUXTCP/demo.c:219:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MSP430/demo.c:81:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/HCS08/demo.c:149:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235TCP/demo.c:129:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/WIN32TCP/demo.cpp:214:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AVR/demo.c:63:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AVR/excoils.c:101:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235CW/demo.c:92:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235/demo.c:71:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71XTCP/demo.c:243:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/ATSAM3S/demo.c:111:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/Z8ENCORE/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AT91SAM7X_ROWLEY/demo.c:98:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./modbus/include/mb.h:101: * eMBRegInputCB( ). ./modbus/include/mb.h:312:eMBErrorCode eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, ./modbus/functions/mbfuncinput.c:96: eMBRegInputCB( pucFrameCur, usRegAddress, usRegCount ); user@~/projects/freemodbus-v1.5.0$
^ C function pointers and further references
What do we need to pass to eMBRegisterCB()? . . .
-
C function pointer syntax:
2019-11-14 Thursday:
A highlighting test . . .
ted@kalaru:/var/local/ted/projects/lsa/freemodbus-v1.5.0$ grep -nr eMBRegInputCB ./*
./demo/WIN32/demo.cpp:221:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71XGCC/demo.c:101:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/ATSAM3S_FREERTOS/demo.c:168:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/BARE/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/exdisc.c:118:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/excoils.c:130:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71X/simple2.c:87:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) Binary file ./demo/STR71X/.simple2.c.swp matches
./demo/STR71X/exholding.c:86:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs )
./demo/STR71X/simple.c:94:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LPC214X/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LINUX/demo.c:264:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/LINUXTCP/demo.c:219:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MSP430/demo.c:81:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/HCS08/demo.c:149:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235TCP/demo.c:129:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/WIN32TCP/demo.cpp:214:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AVR/demo.c:63:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AVR/excoils.c:101:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235CW/demo.c:92:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/MCF5235/demo.c:71:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/STR71XTCP/demo.c:243:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/ATSAM3S/demo.c:111:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/Z8ENCORE/demo.c:55:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./demo/AT91SAM7X_ROWLEY/demo.c:98:eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, USHORT usNRegs ) ./modbus/include/mb.h:101: * eMBRegInputCB( ). ./modbus/include/mb.h:312:eMBErrorCode eMBRegInputCB( UCHAR * pucRegBuffer, USHORT usAddress, ./modbus/functions/mbfuncinput.c:96: eMBRegInputCB( pucFrameCur, usRegAddress, usRegCount );
^ xFunctionHandlers
This looks important:
./modbus/mb.c:95:static xMBFunctionHandler xFuncHandlers[MB_FUNC_HANDLERS_MAX] = {
The full declaration is:
static xMBFunctionHandler xFuncHandlers[MB_FUNC_HANDLERS_MAX] = {
#if MB_FUNC_OTHER_REP_SLAVEID_ENABLED > 0
{MB_FUNC_OTHER_REPORT_SLAVEID, eMBFuncReportSlaveID},
#endif
#if MB_FUNC_READ_INPUT_ENABLED > 0
{MB_FUNC_READ_INPUT_REGISTER, eMBFuncReadInputRegister},
#endif
#if MB_FUNC_READ_HOLDING_ENABLED > 0
{MB_FUNC_READ_HOLDING_REGISTER, eMBFuncReadHoldingRegister},
#endif
#if MB_FUNC_WRITE_MULTIPLE_HOLDING_ENABLED > 0
{MB_FUNC_WRITE_MULTIPLE_REGISTERS, eMBFuncWriteMultipleHoldingRegister},
#endif
#if MB_FUNC_WRITE_HOLDING_ENABLED > 0
{MB_FUNC_WRITE_REGISTER, eMBFuncWriteHoldingRegister},
#endif
#if MB_FUNC_READWRITE_HOLDING_ENABLED > 0
{MB_FUNC_READWRITE_MULTIPLE_REGISTERS, eMBFuncReadWriteMultipleHoldingRegister},
#endif
#if MB_FUNC_READ_COILS_ENABLED > 0
{MB_FUNC_READ_COILS, eMBFuncReadCoils},
#endif
#if MB_FUNC_WRITE_COIL_ENABLED > 0
{MB_FUNC_WRITE_SINGLE_COIL, eMBFuncWriteCoil},
#endif
#if MB_FUNC_WRITE_MULTIPLE_COILS_ENABLED > 0
{MB_FUNC_WRITE_MULTIPLE_COILS, eMBFuncWriteMultipleCoils},
#endif
#if MB_FUNC_READ_DISCRETE_INPUTS_ENABLED > 0
{MB_FUNC_READ_DISCRETE_INPUTS, eMBFuncReadDiscreteInputs},
#endif
};
FreeModbus presently supports sixteen function handlers in this array:
./include/mbconfig.h:86:#define MB_FUNC_HANDLERS_MAX ( 16 )
^ Modbus RTU
^ Modbus tools and resources
- - - top of page - - -
