Simple EtherCAT SubDevice

Scope

This example demonstrates the steps to configure the hardware, create the basic EtherCAT SubDevice information as well as the Object Dictionary and the Process Data configuration.

Related Files

EtherCAT_SubDevice_Simple.c

Basic Setup

The example starts by initializing operating system (OSAL) and hardware abstraction layers (HWAL). The EtherCAT functionality itself is implemented within the Appl_LoopTask that is started from the main application entry point, both are implemented in EtherCAT_SubDevice_Simple.c.

Initialization of Stack, PRU, and Example Application

Before entering the main stack loop, the example application itself is initialized in EC_SLV_APP_SS_applicationInit. This function creates a new EtherCAT SubDevice instance, registers a board status LED callback, sets vendor ID, product code and name, revision number, etc.

Initialization of the EtherCAT SubDevice

Manufacturer Specific Objects

Next various objects are created in the Object Dictionary of the EtherCAT SubDevice. These objects are used to display information related to the device or used to map them as Process Data. These objects are declared in the Manufacturer Specific Area, whereas the CoE Communication Area objects are created automatically by the SDK RXPDO configuration

static EC_API_EError_t EC_SLV_APP_populateOutObjects(EC_SLV_APP_Sapplication_t* pApplicationInstance)
{
    EC_API_EError_t         error   = EC_API_eERR_INVALID;
    EC_API_SLV_SHandle_t*   ptSubDevice;
 
    ...
 
    // Create an Object of type RECORD
    error = (EC_API_EError_t)EC_API_SLV_CoE_odAddRecord(ptSubDevice, 0x2000, "Out Object Record"
                                                       ,NULL, NULL, NULL, NULL, &pApplicationInstance->ptRecObjOut);
    if (error != EC_API_eERR_NONE)
    {
        OSAL_printf("Object 0x2000 Record Error code: 0x%08x\n", error);
        goto Exit;
    }
 
    // Create a subindex 1 of the RECORD
    error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(ptSubDevice, pApplicationInstance->ptRecObjOut
                                                                ,1, "SubIndex 1", DEFTYPE_UNSIGNED32, 32
                                                                ,ACCESS_READWRITE | OBJACCESS_RXPDOMAPPING);
    if (error != EC_API_eERR_NONE)
    {
        OSAL_printf("Object 0x2000 SubIndex 1 Error code: 0x%08x\n", error);
        goto Exit;
    }
 
    ...
}

TXPDO configuration

static EC_API_EError_t EC_SLV_APP_populateInOutObjects(EC_SLV_APP_Sapplication_t* pApplicationInstance)
{
    EC_API_EError_t         error   = EC_API_eERR_INVALID;
    EC_API_SLV_SHandle_t*   ptSubDevice;
 
    ...
 
    // Create an Object of type RECORD
    error = (EC_API_EError_t)EC_API_SLV_CoE_odAddRecord(ptSubDevice, 0x2002, "Test Record"
                                                       ,NULL, NULL, NULL, NULL
                                                       ,&pApplicationInstance->pt2002RecObj);
    if (error != EC_API_eERR_NONE)
    {
        OSAL_printf("Object Record Error code: 0x%08x\n", error);
        goto Exit;
    }
 
    // Create a subindex 1 of the RECORD
    error = (EC_API_EError_t)EC_API_SLV_CoE_configRecordSubIndex(ptSubDevice, pApplicationInstance->pt2002RecObj
                                                                ,1, "SubIndex 1", DEFTYPE_UNSIGNED32, 32
                                                                ,ACCESS_READ | OBJACCESS_TXPDOMAPPING);
    if (error != EC_API_eERR_NONE)
    {
        OSAL_printf("Object 0x2002 SubIndex 1 Error code: 0x%08x\n", error);
        goto Exit;
    }
 
    ...
}

Objects 0x200C and 0x200E are used to demonstrate CoE callback functions. These callbacks, sendEoEFrame and sendEmergencyMsg are deactivated by default in order to pass the EtherCAT Conformance Tests, however, these may be used as write parameter of the stated objects. Using these callback functions, the example application sends an EoE frame or a CoE emergency message with the data written to them. See the code snippet below:

// Create an Object and provide a function to send an emergency message when the object is written
 
i32uErr = (EC_API_ERR_T)EC_API_SLV_CoE_odAddVariable(ptSubDevice, 0x200C, "Emergency message", DEFTYPE_UNSIGNED32, 32, ACCESS_READWRITE, NULL, &sendEmergencyMsg);
if (i32uErr != eECERR_NONE)
{
    osal_Printf("Object 0x200C Error code: 0x%08x\n", i32uErr);
    goto Exit;
}
 
// Send an EoE message when the Object is written
 
i32uErr = (EC_API_ERR_T)EC_API_SLV_CoE_odAddVariable(ptSubDevice, 0x200E, "EoE Send Frame", DEFTYPE_UNSIGNED32, 32, ACCESS_READWRITE, NULL, &sendEoEFrame);
if (i32uErr != eECERR_NONE)
{
    osal_Printf("Object 0x200E Error code: 0x%08x\n", i32uErr);
    goto Exit;
}

Process Data Object Configuration

Once the Object Dictionary is configured, Process Data are defined. The function EC_SLV_APP_populateRxPDO() is used to generate the output PDOs and EC_SLV_APP_populateTxPDO() to generate the input PDOs. By default, the SDK sets the PDO assignment fixed, meaning that a PDO generated by the application is attached to a SyncManager and this configuration cannot be changed. However, it allows by default to modify the PDO entry content. To change these behaviours refer to EC_API_SLV_PDO_setFixedMapping() and EC_API_SLV_PDO_setAssignment() functions.

Initialization and starting the Stacks

The EC_API_SLV_init() function initializes the SDK Stack and validates whether the user defined configuration is valid or not. If the EtherCAT configuration is valid, then object content can be written and finally, the EC_API_SLV_run() function starts the Beckhoff Stack.

Hardware Setup

Appl_LoopTask starts with the initialization of the GPIO driver and the configuration of the PHY and LED pins in the function EC_SLAVE_APP_initBoardFunctions in ecSubDeviceSimple.c. Next PHY parameters, such as address, polarity and RX link are configured in EC_SLAVE_APP_registerStacklessBoardFunctions.

Program flow of the EtherCAT SubDevice Example Application

ICSSG0 Instance

On EVMs supported by TI (AM64X-EVM, AM243X-EVM), it is not possible to use PRU_ICSSG0, as the PRG0_RGMII1 and PRG0_RGMII0 pins are not connected to Ethernet PHYs. This example requires a dedicated custom board to use the PRU_ICSSG0 instance of the ICSSG peripheral. With a custom board, the example is compatible for PRU_ICSSG0 and it provides full support out of the box.

See Ethernet PRU_ICSSG instance-0 (PRU_ICSSG0) Usage Guide for more details