Modbus notes

From Wiki at Neela Nurseries
Revision as of 22:50, 15 November 2019 by Ted (talk | contribs) (^ Modbus frames and framing handling)
Jump to: navigation, search



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.



- 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:

 1004  grep -nr usRegInputBuf ./*
 1005  grep -n pucRegBuffer ./*
 1006  # eMBRegInputCB, third token for which to search


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:



^ Modbus tools and resources


- - - top of page - - -