Vendor-specific protocol over EtherCAT

‍⚠️ Important Note

This feature is part of premium SDK. In case you are using standard and need premium, please contact your regional TI sales representative for additional details.

Description

Vendor-specific protocol over EtherCAT (VoE) enables implementation of a custom user-specific protocol, so that the internal mailbox can be used for a special, newly defined data transport. Unlike standardized EtherCAT services [CoE, FoE, SoE], VoE allows vendors to define custom protocols tailored to their specific requirements, providing flexibility for proprietary communication patterns and data exchange mechanisms. VoE facilitates direct communication between EtherCAT MainDevice and SubDevice over the EtherCAT mailbox, allowing vendors to implement custom application-specific protocols without being limited by standard EtherCAT service specifications.

This page briefly describes the sample custom application-specific protocol implemented with VoE. The motivation of the code snippets is to provide a better understanding of how to handle the VoE application-specific protocol data. For a detailed overview please refer to the example code.

Key Benefits

• Custom Protocol Support : Define vendor-specific or application-specific communication protocols.
• Mailbox-Based Transport : Leverages EtherCAT mailbox infrastructure for reliable data exchange.
• Flexible Data Handling : Support for arbitrary data formats and structures.
• State-Independent Operation: Can operate in various EtherCAT SubDevice states (Pre-Op, Safe-Op, Op).

VoE Protocol Structure

The Sample user-specific protocol is designed to have 6 bytes of protocol header and (0 to n) bytes of data payload, where 'n' depends on the protocol. The below diagram represents the Sample user-specific protocol frame structure.

Sample user-specific protocol header consist of:

• OpCode : Operation code to be processed.
• Command : Command to be executed.
• Data Length : Length of data payload following the protocol header.

The below tables summarize the implemented OpCode.

OpCode	Description
0x0001	Read Request
0x0002	Write Request
0x0003	Acknowledgement
0x0004	Error

The below tables summarize the implemented Command.

Command	Description
0x0001	Product Code
0x0002	Explicit ID

VoE frames consist of:

• EtherCAT Mailbox Header: Standard mailbox frame header of size 6 bytes.
• VoE Header : User-specific protocol header of size 6 bytes. Size is based on protocol design.
• Data Payload : User-specific protocol frame.

The below diagram represents the VoE protocol frame structure.

VoE Protocol Data Exchange Flow

Request-Response Pattern

The sequence of the data exchange between the MainDevice and SubDevice is as follows.

1. EtherCAT MainDevice sends a VoE request by writing a VoE mailbox message into SyncManager 0.
2. EtherCAT SubDevice receives a VoE request and processes it in VoE receive function EC_SLV_APP_VoE_SS_receiveHandlerVoE() and prepares the response.
3. EtherCAT SubDevice sends a VoE response by writing a VoE mailbox message into SyncManager 1.
4. EtherCAT MainDevice receives a VoE response from SyncManager 1.

Sample User-specific Protocol Data Exchange Flow

The below diagram describes the data exchange between the EtherCAT MainDevice and SubDevice using the Sample user-specific protocol.

Sample User-specific Protocol Data Payload Length

The maximum Sample User-specific protocol data payload size over VoE depends on the configured mailbox size:

VoE_MAX_DATA_SIZE = 'Configured Mailbox Size' - 'EtherCAT Mailbox Header'(6 bytes) - 'User-specific protocol Header'(6 bytes)

For example, with a mailbox size of 1024 bytes:

VoE_MAX_DATA_SIZE = (1024 - 6 - 6) bytes

‍⚠️ Incorrect mailbox size configuration can lead to frame truncation and communication failures. Ensure mailbox sizes are properly configured in both SyncManager0 (receive) and SyncManager1 (transmit).

VoE Implementation

VoE implementation is done in such a way that the custom user-specific protocol can be handled in the application side. During the application init, the following functions are attached.

• The VoE init callback function EC_SLV_APP_VoE_SS_init() is attached using EC_API_SLV_VoE_cbRegisterInitHandler().

EC_API_SLV_VoE_cbRegisterInitHandler(
            pAppInstance_p->ptEcSlvApi,
            EC_SLV_APP_VoE_SS_init,
            pAppInstance_p->ptEcSlvApi);

• The VoE manual inject test callback function EC_SLV_APP_VoE_SS_manualInjectTest() is attached using EC_API_SLV_VoE_cbRegisterManualTestHandler().

EC_API_SLV_VoE_cbRegisterManualTestHandler(
            pAppInstance_p->ptEcSlvApi,
            EC_SLV_APP_VoE_SS_manualInjectTest,
            pAppInstance_p->ptEcSlvApi);

• The VoE receive callback function EC_SLV_APP_VoE_SS_receiveHandler() is attached using EC_API_SLV_VoE_cbRegisterReceiveHandler().

EC_API_SLV_VoE_cbRegisterReceiveHandler(
        pAppInstance_p->ptEcSlvApi,
        EC_SLV_APP_VoE_SS_receiveHandler,
        pAppInstance_p->ptEcSlvApi);

A Sample user-specific protocol frame processing is done inside the function EC_SLV_APP_VoE_SS_receiveHandler(), which gets the pointer to the buffer containing the complete Sample user-specific protocol frame received and the length of this frame as input parameters. This function should prepare and overwrite the response in the same buffer which is sent back to the EtherCAT MainDevice.

uint8_t EC_SLV_APP_VoE_SS_receiveHandler(void *pContext, uint16_t *pData, uint16_t *pSize)
{
    uint8_t                     result      = 0;
    uint16_t                    opCode      = 0;
    uint16_t                    command     = 0;
 
    /* Check of the NULL pointers and trigger error */
 
    /* Check of the valid frame size and trigger error */
 
    /* Read OpCode and Command */
 
    if(result == 0)
    {
        switch(opCode)
        {
            case ECAT_VOE_OPCODE_RRQ:
                /* process read requests */
                break;
            
            case ECAT_VOE_OPCODE_WRQ:
                /* process write requests */
                break;
 
            case ECAT_VOE_OPCODE_ACK:
                /* process ACK responses */
                break;
 
            case ECAT_VOE_OPCODE_ERR:
                /* process Error ACK responses */
                break;
 
            default:
                /* unknown Opcode - send error response*/
                break;   
        }
    }
   return result;
}

VoE Testing

It is not possible to test the vendor-specific protocols over EtherCAT in standard tools such as EtherCAT Conformance Test Tool (CTT). To facilitate the testing of Sample user-specific protocol implementation over VoE, a manual inject test function is created to simulate the VoE mailbox requests from the EtherCAT MainDevice. This manual test function pushes the predefined VoE mailbox message into receive mailbox buffer queue at each call. This test function is triggered cyclically, with a period defined by VOE_MANUAL_INJECT_TEST_TRIGGER_PERIOD.

The VoE manual inject test function is activated for VoE and can be deactivated using the macro VOE_MANUAL_INJECT_TEST in ecat_def.h file.

The VoE manual inject test is activated by default in the 'Debug' build. In 'Release' build, it can be enabled by assigning a non zero value to the variable 'voeTestRunCount' in EC_SLV_APP_VoE_SS_manualInjectTest().

The below screenshot shows the VoE debug messages over UART.

The response VoE mailbox message from the EtherCAT SubDevice can be observed using Wireshark.