EtherCAT Slave Library

EtherCAT is a real-time open communication protocol based on Ethernet networks. The standardization process is coordinated by the EtherCAT Technology Group.

This library (lib_ethercat ) allows an abstract access to the application layer of the EtherCAT communication stack. The underlying device access and data transfer is handled without the interaction of the device user application.

The EtherCAT access is implemented using a single thread. All communication is done by interfaces. The PDOs are stored transparently for quick access.

The library supports the following protocols:

  • PDO transfer
  • CAN over EtherCAT (CoE) with CiA402
  • File over EtherCAT (FoE)

How to Use

One design goal for this library was easy usability to make the EtherCAT communication as simple as possible.

There is the main header :ethercat_service.h: with the essential function:

ethercat_service():
 start the EtherCAT communication and serve the data via interfaces

After the call to ethercat_service() the library is operational.

If the firmware also want to use the device object dictionary than the header files :dictionary.h: (for the object dictionary itself) and :canod.h: for a more comfortable access are required.

PDO Communication

The process data object (PDO) are exchanged with the interface i_pdo_communication. There are two interface calls defined:

  • get_pdos_value() to receive the current set of PDO values
  • set_pdos_value() to set the values of the outgoing PDOs, these are sent to the master in the next cycle.

The exchange of the PDO values is done with the module_pdo_handler from the EtherCAT Drive repository. It is recommendet to use this module.

CoE Communication

To access the object dictionary the CoE interface i_coe_communication needs to be used. The object dictionary contains all necessary drive configuration which may be needed to configure the drive for proper operation.

The CoE interface provides the following calls:

  • get_object_value(index, subindex) get the value of the object specified by index and subindex
  • set_object_value(index, subindex, value) set the value of the object specified by index and subindex to value value
  • slave void configuration_ready() this notification is send when the ethercat drive is set to operational mode (OP-MODE) This notification signals the motorcontrol that the current values in the object dictionary are up to date and can be read to configure the drive.
  • void configuration_done(void) the client of the interface has to clear the notification with this call

FoE Communication

The File over EtherCAT (FoE) is primary used to transfer the firmware update from the master to the slave. Technically you have to set the slave to BOOT mode and then initiate the FoE transfer of the data. The new firmware is received by the reboot service and stored in flash. It will be booted next time the device starts.

To transfer data from the master to the slave the interface i_foe_communication provides the following calls:

  • {size_t, uint32_t, enum eFoeStat} read_data(int8_t data[]) - access data of the current FoE transfere (max size = 512 as defined by the FoE spec)
  • [[clears_notification]] int get_notification_type(void)
  • void result(uint32_t packet_number, int error) - the consumer sets the FoE result, 0 for success != for Error
  • [[notification]] slave void data_ready(void) - this signals the consumer that a new data chunk is ready for reading

API

The main user API for the lib_ethercat component is found in ethercat_service.h.

Symbolic constants

DATA_REQUEST

Control word to request PDO data.

Interface for PDO send and request

interface i_pdo_communication

Communication class for PDO communications.

size_t get_pdos_value(unsigned char pdo_value[])
void set_pdos_value(unsigned char pdo_value[], size_t byte_count)

Interface Commands for CAN Object Dictionary requests

interface i_coe_communication

Communication class for CoE communication.

uint32_t get_object_value(uint16_t index, uint8_t subindex)
void set_object_value(uint16_t index, uint8_t subindex, uint32_t value)
[[clears_notification]] int in_op_state(void)
[[clears_notification]] void configuration_done(void)
[[notification]] slave void operational_state_change(void)

Interface Commands for FoE transfer

interface i_foe_communication

Communication class for FoE communication.

Interface calls: read_data() - access data of the current FoE transfere (max size = 512 as defined by the FoE spec) result() - the consumer sets the FoE result, 0 for success != for Error data_ready() - this signals the consumer that a new data chunk is ready for reading

[[guarded]] enum eFoeStat read_data(int8_t data[])
[[guarded]] void result(uint32_t packet_number, int error)

Types

EthercatPorts

Structure containing resources required for interfing the EtherCAT chip.

This structure contains resources required for interfing the EtherCAT chip. It consists of 8 ports.

Structure Members:

out port p_ecatRST
in port p_ecatIRQ
in port p_ecatBUSY
out port p_ecatWR
out port p_ecatRD
out port p_ecatCS
port p_ecatData
out port p_ecatAddress

Functions

void ethercat_service(client interface EtherCATRebootInterface ?i_ecat_reboot, server interface i_coe_communication i_coecomm, server interface i_eoe_communication ?i_eoecom, server interface i_foe_communication i_foe, server interface i_pdo_communication i_pdo, EthercatPorts &ethercat_interface)

Main EtherCAT handler function.

This function should run in a separate thread on the XMOS core controlling the I/O pins for EtherCAT communication.

For every packet send or received from or to this EtherCAT handler, the first word transmitted indicates the number of words to follow (the packet itself).

Parameters:
  • i_ecat_reboot – access the reboot service
  • i_coe_communication – send, receive and signal for CoE
  • i_eoe_communication – class for EoE data exchange
  • i_foe_communication – send, receive and signal for FoE
  • i_pdo_communication – read and write PDO values
  • ethercat_class – ports for interfacing EtherCAT chip.