Modbus notes

From Wiki at Neela Nurseries
Revision as of 21:13, 21 November 2019 by Ted (talk | contribs) (^ LPC Stuff)
Jump to: navigation, search




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.



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()? . . .

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

2019-11-20 Question: how does FreeModbus RTU protocol version get to the state of "received frame"?

$ grep -nr STATE_RX_RCV ./* | grep -v '^Binary'
./Modbus/ascii/mbascii.c:61:    STATE_RX_RCV,               /*!< Frame is beeing received. */
./Modbus/ascii/mbascii.c:237:    case STATE_RX_RCV:
./Modbus/ascii/mbascii.c:301:            eRcvState = STATE_RX_RCV;
./Modbus/ascii/mbascii.c:321:            eRcvState = STATE_RX_RCV;
./Modbus/ascii/mbascii.c:417:    case STATE_RX_RCV:
./Modbus/ascii/mbascii.c:423:        assert( ( eRcvState == STATE_RX_RCV ) || ( eRcvState == STATE_RX_WAIT_EOF ) );
./Modbus/rtu/mbrtu.c:58:    STATE_RX_RCV,               /*!< Frame is beeing received. */
./Modbus/rtu/mbrtu.c:261:        eRcvState = STATE_RX_RCV;
./Modbus/rtu/mbrtu.c:272:    case STATE_RX_RCV:
./Modbus/rtu/mbrtu.c:339:    case STATE_RX_RCV:
./Modbus/rtu/mbrtu.c:350:                ( eRcvState == STATE_RX_RCV ) || ( eRcvState == STATE_RX_ERROR ) );


In following paragraph, FreeModbus source files are ./mb.c, ./rtu/mbrtu.c, and ./port/mv_portserial.c.

In our case, FreeModbus routine eMBInit() calls routine eMBRTUInit(). Routine eMBRTUInit() seems to ignore the caller's passed Modbus slave device address . . . strange. This routine in turn calls xMBPortSerialInit() with parameters:  ucPort, ulBaudRate, 8, eParity. . . .


Aside question: in the Kargs BACNet stack what does the following line of code carry out?

  # ./BACnet/src/mstp.c:307:                mstp_port->SilenceTimerReset((void *) mstp_port);


^ LPC Stuff

In file [project]/Common/lpc_chip/chip_11u6x/clock_11u6x.c:

313
314 /* Return system clock rate */
315 uint32_t Chip_Clock_GetSystemClockRate(void)
316 {
317         /* No point in checking for divide by 0 */
318         return Chip_Clock_GetMainClockRate() / LPC_SYSCTL->SYSAHBCLKDIV;
319 }
clock_11u6x.c [dos] (09:59 30/10/2019) 


^ Related Tools and Resources

Search string "FreeModbus configure UART lpc microcontroller":


- - - top of page - - -