EtherCAT realtime interface

---

Detailed Description

EtherCAT interface for realtime modules.

This interface is designed for realtime modules that want to use EtherCAT. There are functions to request a master, to map process data, to communicate with slaves via CoE and to configure and activate the bus.

Functions
int	ecrt_slave_sdo_read (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint8_t *target, size_t *size)
	Reads a CANopen SDO in normal mode.
int	ecrt_slave_sdo_read_exp8 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint8_t *target)
	Reads an 8-bit SDO in expedited mode.
int	ecrt_slave_sdo_read_exp16 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint16_t *target)
	Reads a 16-bit SDO in expedited mode.
int	ecrt_slave_sdo_read_exp32 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint32_t *target)
	Reads a 32-bit SDO in expedited mode.
int	ecrt_slave_sdo_write_exp8 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint8_t value)
	Writes an 8-bit SDO in expedited mode.
int	ecrt_slave_sdo_write_exp16 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint16_t value)
	Writes a 16-bit SDO in expedited mode.
int	ecrt_slave_sdo_write_exp32 (ec_slave_t *slave, uint16_t sdo_index, uint8_t sdo_subindex, uint32_t value)
	Writes a 32-bit SDO in expedited mode.
ec_slave_t *	ecrt_domain_register_field (ec_domain_t *domain, const char *address, const char *vendor_name, const char *product_name, void **data_ptr, const char *field_name, unsigned int field_index, unsigned int field_count)
	Registers a data field in a domain.
int	ecrt_domain_register_field_list (ec_domain_t *domain, const ec_field_init_t *fields)
	Registeres a bunch of data fields.
void	ecrt_domain_queue (ec_domain_t *domain)
	Places all process data datagrams in the masters datagram queue.
void	ecrt_domain_process (ec_domain_t *domain)
	Processes received process data.
int	ecrt_domain_state (ec_domain_t *domain)
	Returns the state of a domain.
ec_domain_t *	ecrt_master_create_domain (ec_master_t *master)
	Creates a domain.
int	ecrt_master_activate (ec_master_t *master)
	Configures all slaves and leads them to the OP state.
void	ecrt_master_deactivate (ec_master_t *master)
	Resets all slaves to INIT state.
int	ecrt_master_fetch_sdo_lists (ec_master_t *master)
	Fetches the SDO dictionaries of all slaves.
void	ecrt_master_sync_io (ec_master_t *master)
	Sends queued datagrams and waits for their reception.
void	ecrt_master_async_send (ec_master_t *master)
	Asynchronous sending of datagrams.
void	ecrt_master_async_receive (ec_master_t *master)
	Asynchronous receiving of datagrams.
void	ecrt_master_prepare_async_io (ec_master_t *master)
	Prepares synchronous IO.
void	ecrt_master_run (ec_master_t *master)
	Does all cyclic master work.
ec_slave_t *	ecrt_master_get_slave (const ec_master_t *master, const char *address)
	Translates an ASCII coded bus-address to a slave pointer.
void	ecrt_master_callbacks (ec_master_t *master, int(*request_cb)(void *), void(*release_cb)(void *), void *cb_data)
	Sets the locking callbacks.
int	ecrt_master_start_eoe (ec_master_t *master)
	Starts Ethernet-over-EtherCAT processing for all EoE-capable slaves.
void	ecrt_master_debug (ec_master_t *master, int level)
	Sets the debug level of the master.
void	ecrt_master_print (const ec_master_t *master, unsigned int verbosity)
	Outputs all master information.
ec_master_t *	ecrt_request_master (unsigned int master_index)
	Reserves an EtherCAT master for realtime operation.
void	ecrt_release_master (ec_master_t *master)
	Releases a reserved EtherCAT master.
int	ecrt_slave_write_alias (ec_slave_t *slave, uint16_t alias)
	Writes the "configured station alias" to the slave's EEPROM.
int	ecrt_slave_field_size (ec_slave_t *slave, const char *field_name, unsigned int field_index, size_t size)

---

Function Documentation

int ecrt_slave_sdo_read (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint8_t *  target, size_t *  size )

Reads a CANopen SDO in normal mode. Returns: 0 in case of success, else < 0 Todo: Make size non-pointer. Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex target  memory for value size  target memory size Definition at line 191 of file canopen.c.

int ecrt_slave_sdo_read_exp8 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint8_t *  target )

Reads an 8-bit SDO in expedited mode. See ec_slave_sdo_read_exp() Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex target  memory for read value Definition at line 603 of file canopen.c.

int ecrt_slave_sdo_read_exp16 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint16_t *  target )

Reads a 16-bit SDO in expedited mode. See ec_slave_sdo_read_exp() Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex target  memory for read value Definition at line 624 of file canopen.c.

int ecrt_slave_sdo_read_exp32 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint32_t *  target )

Reads a 32-bit SDO in expedited mode. See ec_slave_sdo_read_exp() Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex target  memory for read value Definition at line 645 of file canopen.c.

int ecrt_slave_sdo_write_exp8 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint8_t  value )

Writes an 8-bit SDO in expedited mode. Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex value  new value Definition at line 665 of file canopen.c.

int ecrt_slave_sdo_write_exp16 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint16_t  value )

Writes a 16-bit SDO in expedited mode. Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex value  new value Definition at line 682 of file canopen.c.

int ecrt_slave_sdo_write_exp32 (  ec_slave_t *  slave, uint16_t  sdo_index, uint8_t  sdo_subindex, uint32_t  value )

Writes a 32-bit SDO in expedited mode. Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave sdo_index  SDO index sdo_subindex  SDO subindex value  new value Definition at line 701 of file canopen.c.

ec_slave_t* ecrt_domain_register_field (  ec_domain_t *  domain, const char *  address, const char *  vendor_name, const char *  product_name, void **  data_ptr, const char *  field_name, unsigned int  field_index, unsigned int  field_count )

Registers a data field in a domain. If data_ptr is NULL, the slave is only checked against its type. If field_count is 0, it is assumed that one data field is to be registered. If field_count is greater then 1, it is assumed that data_ptr is an array of the respective size. Returns: pointer to the slave on success, else NULL Parameters: domain  EtherCAT domain address  ASCII address of the slave, see ecrt_master_get_slave() vendor_name  vendor name product_name  product name data_ptr  address of the process data pointer field_name  data field name field_index  offset of data fields with field_type field_count  number of data fields (with the same type) to register Definition at line 370 of file domain.c.

int ecrt_domain_register_field_list (  ec_domain_t *  domain, const ec_field_init_t *  fields )

Registeres a bunch of data fields. Caution! The list has to be terminated with a NULL structure ({})! Returns: 0 in case of success, else < 0 Parameters: domain  EtherCAT domain fields  array of data field registrations Definition at line 462 of file domain.c.

void ecrt_domain_queue (  ec_domain_t *  domain  )

Places all process data datagrams in the masters datagram queue. Parameters: domain  EtherCAT domain Definition at line 488 of file domain.c.

void ecrt_domain_process (  ec_domain_t *  domain  )

Processes received process data. Parameters: domain  EtherCAT domain Definition at line 504 of file domain.c.

int ecrt_domain_state (  ec_domain_t *  domain  )

Returns the state of a domain. Returns: 0 if all datagrams were received, else -1. Parameters: domain  EtherCAT domain Definition at line 528 of file domain.c.

ec_domain_t* ecrt_master_create_domain (  ec_master_t *  master  )

Creates a domain. Returns: pointer to new domain on success, else NULL Parameters: master  master Definition at line 1070 of file master.c.

int ecrt_master_activate (  ec_master_t *  master  )

Configures all slaves and leads them to the OP state. Does the complete configuration and activation for all slaves. Sets sync managers and FMMUs, and does the appropriate transitions, until the slave is operational. Returns: 0 in case of success, else < 0 Parameters: master  EtherCAT master Definition at line 1116 of file master.c.

void ecrt_master_deactivate (  ec_master_t *  master  )

Resets all slaves to INIT state. Parameters: master  EtherCAT master Definition at line 1294 of file master.c.

int ecrt_master_fetch_sdo_lists (  ec_master_t *  master  )

Fetches the SDO dictionaries of all slaves. Slaves that do not support the CoE protocol are left out. Returns: 0 in case of success, else < 0 Parameters: master  EtherCAT master Definition at line 1314 of file master.c.

void ecrt_master_sync_io (  ec_master_t *  master  )

Sends queued datagrams and waits for their reception. Parameters: master  EtherCAT master Definition at line 1338 of file master.c.

void ecrt_master_async_send (  ec_master_t *  master  )

Asynchronous sending of datagrams. Parameters: master  EtherCAT master Definition at line 1394 of file master.c.

void ecrt_master_async_receive (  ec_master_t *  master  )

Asynchronous receiving of datagrams. Parameters: master  EtherCAT master Definition at line 1421 of file master.c.

void ecrt_master_prepare_async_io (  ec_master_t *  master  )

Prepares synchronous IO. Queues all domain datagrams and sends them. Then waits a certain time, so that ecrt_master_sasync_receive() can be called securely. Parameters: master  EtherCAT master Definition at line 1463 of file master.c.

void ecrt_master_run (  ec_master_t *  master  )

Does all cyclic master work. Parameters: master  EtherCAT master Definition at line 1491 of file master.c.

ec_slave_t* ecrt_master_get_slave (  const ec_master_t *  master, const char *  address )

Translates an ASCII coded bus-address to a slave pointer. These are the valid addressing schemes: "X" = the X. slave on the bus, "X:Y" = the Y. slave after the X. branch (bus coupler), "#X" = the slave with alias X, "#X:Y" = the Y. slave after the branch (bus coupler) with alias X. X and Y are zero-based indices and may be provided in hexadecimal or octal notation (with respective prefix). Returns: pointer to the slave on success, else NULL Parameters: master  Master address  address string Definition at line 1515 of file master.c.

void ecrt_master_callbacks (  ec_master_t *  master, int(*)(void *)  request_cb, void(*)(void *)  release_cb, void *  cb_data )

Sets the locking callbacks. The request_cb function must return zero, to allow another instance (the EoE process for example) to access the master. Non-zero means, that access is forbidden at this time. Parameters: master  EtherCAT master request_cb  request lock CB release_cb  release lock CB cb_data  data parameter Definition at line 1618 of file master.c.

int ecrt_master_start_eoe (  ec_master_t *  master  )

Starts Ethernet-over-EtherCAT processing for all EoE-capable slaves. Parameters: master  EtherCAT master Definition at line 1636 of file master.c.

void ecrt_master_debug (  ec_master_t *  master, int  level )

Sets the debug level of the master. The following levels are valid: 1: only output positions marks and basic data 2: additional frame data output Parameters: master  EtherCAT master level  debug level Definition at line 1657 of file master.c.

void ecrt_master_print (  const ec_master_t *  master, unsigned int  verbosity )

Outputs all master information. Verbosity: 0: Only slave types and positions 1: with EEPROM contents >1: with SDO dictionaries Parameters: master  EtherCAT master verbosity  verbosity level Definition at line 1678 of file master.c.

ec_master_t* ecrt_request_master (  unsigned int  master_index  )

Reserves an EtherCAT master for realtime operation. Returns: pointer to reserved master, or NULL on error Parameters: master_index  master index Definition at line 401 of file module.c.

void ecrt_release_master (  ec_master_t *  master  )

Releases a reserved EtherCAT master. Parameters: master  EtherCAT master Definition at line 459 of file module.c.

int ecrt_slave_write_alias (  ec_slave_t *  slave, uint16_t  alias )

Writes the "configured station alias" to the slave's EEPROM. Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave alias  new alias Definition at line 1540 of file slave.c.

int ecrt_slave_field_size (  ec_slave_t *  slave, const char *  field_name, unsigned int  field_index, size_t  size )

Returns: 0 in case of success, else < 0 Parameters: slave  EtherCAT slave field_name  data field name field_index  data field index size  new data field size Definition at line 1554 of file slave.c.

---