IgH EtherCAT Master  1.5.3
EtherCAT Application Interface

EtherCAT interface for realtime applications. More...

Data Structures

struct  ec_master_state_t
 Master state. More...
 
struct  ec_master_link_state_t
 Redundant link state. More...
 
struct  ec_slave_config_state_t
 Slave configuration state. More...
 
struct  ec_master_info_t
 Master information. More...
 
struct  ec_slave_port_link_t
 EtherCAT slave port information. More...
 
struct  ec_slave_info_t
 Slave information. More...
 
struct  ec_domain_state_t
 Domain state. More...
 
struct  ec_pdo_entry_info_t
 PDO entry configuration information. More...
 
struct  ec_pdo_info_t
 PDO configuration information. More...
 
struct  ec_sync_info_t
 Sync manager configuration information. More...
 
struct  ec_pdo_entry_reg_t
 List record type for PDO entry mass-registration. More...
 

Macros

#define ECRT_VER_MAJOR   1
 EtherCAT realtime interface major version number.
 
#define ECRT_VER_MINOR   5
 EtherCAT realtime interface minor version number.
 
#define ECRT_VERSION(a, b)   (((a) << 8) + (b))
 EtherCAT realtime interface version word generator.
 
#define ECRT_VERSION_MAGIC   ECRT_VERSION(ECRT_VER_MAJOR, ECRT_VER_MINOR)
 EtherCAT realtime interface version word.
 
#define EC_HAVE_REDUNDANCY
 Defined, if the redundancy features are available. More...
 
#define EC_HAVE_EMERGENCY
 Defined, if the CoE emergency ring feature is available. More...
 
#define EC_HAVE_REG_ACCESS
 Defined, if the register access interface is available. More...
 
#define EC_HAVE_SELECT_REF_CLOCK
 Defined if the method ecrt_master_select_reference_clock() is available.
 
#define EC_HAVE_REF_CLOCK_TIME
 Defined if the method ecrt_master_reference_clock_time() is available.
 
#define EC_HAVE_REG_BY_POS
 Defined if the method ecrt_slave_config_reg_pdo_entry_pos() is available.
 
#define EC_HAVE_SYNC_TO
 Defined if the method ecrt_master_sync_reference_clock_to() is available.
 
#define EC_HAVE_FLAGS
 Defined if the method ecrt_slave_config_flag() is available.
 
#define EC_HAVE_SOE_REQUESTS
 Defined if the methods ecrt_slave_config_create_soe_request(), ecrt_soe_request_object(), ecrt_soe_request_timeout(), ecrt_soe_request_data(), ecrt_soe_request_data_size(), ecrt_soe_request_state(), ecrt_soe_request_write() and ecrt_soe_request_read() and the datatype ec_soe_request_t are available.
 
#define EC_END   ~0U
 End of list marker. More...
 
#define EC_MAX_SYNC_MANAGERS   16
 Maximum number of sync managers per slave.
 
#define EC_MAX_STRING_LENGTH   64
 Maximum string length. More...
 
#define EC_MAX_PORTS   4
 Maximum number of slave ports. More...
 
#define EC_TIMEVAL2NANO(TV)   (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)
 Timeval to nanoseconds conversion. More...
 
#define EC_COE_EMERGENCY_MSG_SIZE   8
 Size of a CoE emergency message in byte. More...
 
#define EC_READ_BIT(DATA, POS)   ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)
 Read a certain bit of an EtherCAT data byte. More...
 
#define EC_WRITE_BIT(DATA, POS, VAL)
 Write a certain bit of an EtherCAT data byte. More...
 
#define EC_READ_U8(DATA)   ((uint8_t) *((uint8_t *) (DATA)))
 Read an 8-bit unsigned value from EtherCAT data. More...
 
#define EC_READ_S8(DATA)   ((int8_t) *((uint8_t *) (DATA)))
 Read an 8-bit signed value from EtherCAT data. More...
 
#define EC_READ_U16(DATA)   ((uint16_t) le16_to_cpup((void *) (DATA)))
 Read a 16-bit unsigned value from EtherCAT data. More...
 
#define EC_READ_S16(DATA)   ((int16_t) le16_to_cpup((void *) (DATA)))
 Read a 16-bit signed value from EtherCAT data. More...
 
#define EC_READ_U32(DATA)   ((uint32_t) le32_to_cpup((void *) (DATA)))
 Read a 32-bit unsigned value from EtherCAT data. More...
 
#define EC_READ_S32(DATA)   ((int32_t) le32_to_cpup((void *) (DATA)))
 Read a 32-bit signed value from EtherCAT data. More...
 
#define EC_READ_U64(DATA)   ((uint64_t) le64_to_cpup((void *) (DATA)))
 Read a 64-bit unsigned value from EtherCAT data. More...
 
#define EC_READ_S64(DATA)   ((int64_t) le64_to_cpup((void *) (DATA)))
 Read a 64-bit signed value from EtherCAT data. More...
 
#define EC_WRITE_U8(DATA, VAL)
 Write an 8-bit unsigned value to EtherCAT data. More...
 
#define EC_WRITE_S8(DATA, VAL)   EC_WRITE_U8(DATA, VAL)
 Write an 8-bit signed value to EtherCAT data. More...
 
#define EC_WRITE_U16(DATA, VAL)
 Write a 16-bit unsigned value to EtherCAT data. More...
 
#define EC_WRITE_S16(DATA, VAL)   EC_WRITE_U16(DATA, VAL)
 Write a 16-bit signed value to EtherCAT data. More...
 
#define EC_WRITE_U32(DATA, VAL)
 Write a 32-bit unsigned value to EtherCAT data. More...
 
#define EC_WRITE_S32(DATA, VAL)   EC_WRITE_U32(DATA, VAL)
 Write a 32-bit signed value to EtherCAT data. More...
 
#define EC_WRITE_U64(DATA, VAL)
 Write a 64-bit unsigned value to EtherCAT data. More...
 
#define EC_WRITE_S64(DATA, VAL)   EC_WRITE_U64(DATA, VAL)
 Write a 64-bit signed value to EtherCAT data. More...
 

Typedefs

typedef struct ec_master ec_master_t
 
typedef struct ec_slave_config ec_slave_config_t
 
typedef struct ec_domain ec_domain_t
 
typedef struct ec_sdo_request ec_sdo_request_t
 
typedef struct ec_soe_request ec_soe_request_t
 
typedef struct ec_voe_handler ec_voe_handler_t
 
typedef struct ec_reg_request ec_reg_request_t
 

Enumerations

enum  ec_slave_port_desc_t { EC_PORT_NOT_IMPLEMENTED, EC_PORT_NOT_CONFIGURED, EC_PORT_EBUS, EC_PORT_MII }
 EtherCAT slave port descriptor. More...
 
enum  ec_wc_state_t { EC_WC_ZERO = 0, EC_WC_INCOMPLETE, EC_WC_COMPLETE }
 Domain working counter interpretation. More...
 
enum  ec_direction_t { EC_DIR_INVALID, EC_DIR_OUTPUT, EC_DIR_INPUT, EC_DIR_COUNT }
 Direction type for PDO assignment functions. More...
 
enum  ec_watchdog_mode_t { EC_WD_DEFAULT, EC_WD_ENABLE, EC_WD_DISABLE }
 Watchdog mode for sync manager configuration. More...
 
enum  ec_request_state_t { EC_REQUEST_UNUSED, EC_REQUEST_BUSY, EC_REQUEST_SUCCESS, EC_REQUEST_ERROR }
 Request state. More...
 
enum  ec_al_state_t { EC_AL_STATE_INIT = 1, EC_AL_STATE_PREOP = 2, EC_AL_STATE_SAFEOP = 4, EC_AL_STATE_OP = 8 }
 Application-layer state. More...
 

Functions

unsigned int ecrt_version_magic (void)
 Returns the version magic of the realtime interface. More...
 
ec_master_tecrt_request_master (unsigned int master_index)
 Requests an EtherCAT master for realtime operation. More...
 
void ecrt_release_master (ec_master_t *master)
 Releases a requested EtherCAT master. More...
 
void ecrt_master_callbacks (ec_master_t *master, void(*send_cb)(void *), void(*receive_cb)(void *), void *cb_data)
 Sets the locking callbacks. More...
 
ec_domain_tecrt_master_create_domain (ec_master_t *master)
 Creates a new process data domain. More...
 
ec_slave_config_tecrt_master_slave_config (ec_master_t *master, uint16_t alias, uint16_t position, uint32_t vendor_id, uint32_t product_code)
 Obtains a slave configuration. More...
 
int ecrt_master_select_reference_clock (ec_master_t *master, ec_slave_config_t *sc)
 Selects the reference clock for distributed clocks. More...
 
int ecrt_master (ec_master_t *master, ec_master_info_t *master_info)
 Obtains master information. More...
 
int ecrt_master_get_slave (ec_master_t *master, uint16_t slave_position, ec_slave_info_t *slave_info)
 Obtains slave information. More...
 
int ecrt_master_sdo_download (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t subindex, uint8_t *data, size_t data_size, uint32_t *abort_code)
 Executes an SDO download request to write data to a slave. More...
 
int ecrt_master_sdo_download_complete (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t *data, size_t data_size, uint32_t *abort_code)
 Executes an SDO download request to write data to a slave via complete access. More...
 
int ecrt_master_sdo_upload (ec_master_t *master, uint16_t slave_position, uint16_t index, uint8_t subindex, uint8_t *target, size_t target_size, size_t *result_size, uint32_t *abort_code)
 Executes an SDO upload request to read data from a slave. More...
 
int ecrt_master_write_idn (ec_master_t *master, uint16_t slave_position, uint8_t drive_no, uint16_t idn, uint8_t *data, size_t data_size, uint16_t *error_code)
 Executes an SoE write request. More...
 
int ecrt_master_read_idn (ec_master_t *master, uint16_t slave_position, uint8_t drive_no, uint16_t idn, uint8_t *target, size_t target_size, size_t *result_size, uint16_t *error_code)
 Executes an SoE read request. More...
 
int ecrt_master_activate (ec_master_t *master)
 Finishes the configuration phase and prepares for cyclic operation. More...
 
void ecrt_master_deactivate (ec_master_t *master)
 Deactivates the master. More...
 
int ecrt_master_set_send_interval (ec_master_t *master, size_t send_interval)
 Set interval between calls to ecrt_master_send(). More...
 
void ecrt_master_send (ec_master_t *master)
 Sends all datagrams in the queue. More...
 
void ecrt_master_receive (ec_master_t *master)
 Fetches received frames from the hardware and processes the datagrams. More...
 
void ecrt_master_send_ext (ec_master_t *master)
 Sends non-application datagrams. More...
 
void ecrt_master_state (const ec_master_t *master, ec_master_state_t *state)
 Reads the current master state. More...
 
int ecrt_master_link_state (const ec_master_t *master, unsigned int dev_idx, ec_master_link_state_t *state)
 Reads the current state of a redundant link. More...
 
void ecrt_master_application_time (ec_master_t *master, uint64_t app_time)
 Sets the application time. More...
 
void ecrt_master_sync_reference_clock (ec_master_t *master)
 Queues the DC reference clock drift compensation datagram for sending. More...
 
void ecrt_master_sync_reference_clock_to (ec_master_t *master, uint64_t sync_time)
 Queues the DC reference clock drift compensation datagram for sending. More...
 
void ecrt_master_sync_slave_clocks (ec_master_t *master)
 Queues the DC clock drift compensation datagram for sending. More...
 
int ecrt_master_reference_clock_time (ec_master_t *master, uint32_t *time)
 Get the lower 32 bit of the reference clock system time. More...
 
void ecrt_master_sync_monitor_queue (ec_master_t *master)
 Queues the DC synchrony monitoring datagram for sending. More...
 
uint32_t ecrt_master_sync_monitor_process (ec_master_t *master)
 Processes the DC synchrony monitoring datagram. More...
 
void ecrt_master_reset (ec_master_t *master)
 Retry configuring slaves. More...
 
int ecrt_slave_config_sync_manager (ec_slave_config_t *sc, uint8_t sync_index, ec_direction_t direction, ec_watchdog_mode_t watchdog_mode)
 Configure a sync manager. More...
 
void ecrt_slave_config_watchdog (ec_slave_config_t *sc, uint16_t watchdog_divider, uint16_t watchdog_intervals)
 Configure a slave's watchdog times. More...
 
int ecrt_slave_config_pdo_assign_add (ec_slave_config_t *sc, uint8_t sync_index, uint16_t index)
 Add a PDO to a sync manager's PDO assignment. More...
 
void ecrt_slave_config_pdo_assign_clear (ec_slave_config_t *sc, uint8_t sync_index)
 Clear a sync manager's PDO assignment. More...
 
int ecrt_slave_config_pdo_mapping_add (ec_slave_config_t *sc, uint16_t pdo_index, uint16_t entry_index, uint8_t entry_subindex, uint8_t entry_bit_length)
 Add a PDO entry to the given PDO's mapping. More...
 
void ecrt_slave_config_pdo_mapping_clear (ec_slave_config_t *sc, uint16_t pdo_index)
 Clear the mapping of a given PDO. More...
 
int ecrt_slave_config_pdos (ec_slave_config_t *sc, unsigned int n_syncs, const ec_sync_info_t syncs[])
 Specify a complete PDO configuration. More...
 
int ecrt_slave_config_reg_pdo_entry (ec_slave_config_t *sc, uint16_t entry_index, uint8_t entry_subindex, ec_domain_t *domain, unsigned int *bit_position)
 Registers a PDO entry for process data exchange in a domain. More...
 
int ecrt_slave_config_reg_pdo_entry_pos (ec_slave_config_t *sc, uint8_t sync_index, unsigned int pdo_pos, unsigned int entry_pos, ec_domain_t *domain, unsigned int *bit_position)
 Registers a PDO entry using its position. More...
 
void ecrt_slave_config_dc (ec_slave_config_t *sc, uint16_t assign_activate, uint32_t sync0_cycle, int32_t sync0_shift, uint32_t sync1_cycle, int32_t sync1_shift)
 Configure distributed clocks. More...
 
int ecrt_slave_config_sdo (ec_slave_config_t *sc, uint16_t index, uint8_t subindex, const uint8_t *data, size_t size)
 Add an SDO configuration. More...
 
int ecrt_slave_config_sdo8 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint8_t value)
 Add a configuration value for an 8-bit SDO. More...
 
int ecrt_slave_config_sdo16 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint16_t value)
 Add a configuration value for a 16-bit SDO. More...
 
int ecrt_slave_config_sdo32 (ec_slave_config_t *sc, uint16_t sdo_index, uint8_t sdo_subindex, uint32_t value)
 Add a configuration value for a 32-bit SDO. More...
 
int ecrt_slave_config_complete_sdo (ec_slave_config_t *sc, uint16_t index, const uint8_t *data, size_t size)
 Add configuration data for a complete SDO. More...
 
int ecrt_slave_config_emerg_size (ec_slave_config_t *sc, size_t elements)
 Set the size of the CoE emergency ring buffer. More...
 
int ecrt_slave_config_emerg_pop (ec_slave_config_t *sc, uint8_t *target)
 Read and remove one record from the CoE emergency ring buffer. More...
 
int ecrt_slave_config_emerg_clear (ec_slave_config_t *sc)
 Clears CoE emergency ring buffer and the overrun counter. More...
 
int ecrt_slave_config_emerg_overruns (ec_slave_config_t *sc)
 Read the number of CoE emergency overruns. More...
 
ec_sdo_request_tecrt_slave_config_create_sdo_request (ec_slave_config_t *sc, uint16_t index, uint8_t subindex, size_t size)
 Create an SDO request to exchange SDOs during realtime operation. More...
 
ec_soe_request_tecrt_slave_config_create_soe_request (ec_slave_config_t *sc, uint8_t drive_no, uint16_t idn, size_t size)
 Create an SoE request to exchange SoE IDNs during realtime operation. More...
 
ec_voe_handler_tecrt_slave_config_create_voe_handler (ec_slave_config_t *sc, size_t size)
 Create an VoE handler to exchange vendor-specific data during realtime operation. More...
 
ec_reg_request_tecrt_slave_config_create_reg_request (ec_slave_config_t *sc, size_t size)
 Create a register request to exchange EtherCAT register contents during realtime operation. More...
 
void ecrt_slave_config_state (const ec_slave_config_t *sc, ec_slave_config_state_t *state)
 Outputs the state of the slave configuration. More...
 
int ecrt_slave_config_idn (ec_slave_config_t *sc, uint8_t drive_no, uint16_t idn, ec_al_state_t state, const uint8_t *data, size_t size)
 Add an SoE IDN configuration. More...
 
int ecrt_slave_config_flag (ec_slave_config_t *sc, const char *key, int32_t value)
 Adds a feature flag to a slave configuration. More...
 
int ecrt_domain_reg_pdo_entry_list (ec_domain_t *domain, const ec_pdo_entry_reg_t *pdo_entry_regs)
 Registers a bunch of PDO entries for a domain. More...
 
size_t ecrt_domain_size (const ec_domain_t *domain)
 Returns the current size of the domain's process data. More...
 
void ecrt_domain_external_memory (ec_domain_t *domain, uint8_t *memory)
 Provide external memory to store the domain's process data. More...
 
uint8_t * ecrt_domain_data (ec_domain_t *domain)
 Returns the domain's process data. More...
 
void ecrt_domain_process (ec_domain_t *domain)
 Determines the states of the domain's datagrams. More...
 
void ecrt_domain_queue (ec_domain_t *domain)
 (Re-)queues all domain datagrams in the master's datagram queue. More...
 
void ecrt_domain_state (const ec_domain_t *domain, ec_domain_state_t *state)
 Reads the state of a domain. More...
 
void ecrt_sdo_request_index (ec_sdo_request_t *req, uint16_t index, uint8_t subindex)
 Set the SDO index and subindex. More...
 
void ecrt_sdo_request_timeout (ec_sdo_request_t *req, uint32_t timeout)
 Set the timeout for an SDO request. More...
 
uint8_t * ecrt_sdo_request_data (ec_sdo_request_t *req)
 Access to the SDO request's data. More...
 
size_t ecrt_sdo_request_data_size (const ec_sdo_request_t *req)
 Returns the current SDO data size. More...
 
ec_request_state_t ecrt_sdo_request_state (const ec_sdo_request_t *req)
 Get the current state of the SDO request. More...
 
void ecrt_sdo_request_write (ec_sdo_request_t *req)
 Schedule an SDO write operation. More...
 
void ecrt_sdo_request_read (ec_sdo_request_t *req)
 Schedule an SDO read operation. More...
 
void ecrt_soe_request_idn (ec_soe_request_t *req, uint8_t drive_no, uint16_t idn)
 Set the request's drive and Sercos ID numbers. More...
 
void ecrt_soe_request_timeout (ec_soe_request_t *req, uint32_t timeout)
 Set the timeout for an SoE request. More...
 
uint8_t * ecrt_soe_request_data (ec_soe_request_t *req)
 Access to the SoE request's data. More...
 
size_t ecrt_soe_request_data_size (const ec_soe_request_t *req)
 Returns the current IDN data size. More...
 
ec_request_state_t ecrt_soe_request_state (ec_soe_request_t *req)
 Get the current state of the SoE request. More...
 
void ecrt_soe_request_write (ec_soe_request_t *req)
 Schedule an SoE IDN write operation. More...
 
void ecrt_soe_request_read (ec_soe_request_t *req)
 Schedule an SoE IDN read operation. More...
 
void ecrt_voe_handler_send_header (ec_voe_handler_t *voe, uint32_t vendor_id, uint16_t vendor_type)
 Sets the VoE header for future send operations. More...
 
void ecrt_voe_handler_received_header (const ec_voe_handler_t *voe, uint32_t *vendor_id, uint16_t *vendor_type)
 Reads the header data of a received VoE message. More...
 
uint8_t * ecrt_voe_handler_data (ec_voe_handler_t *voe)
 Access to the VoE handler's data. More...
 
size_t ecrt_voe_handler_data_size (const ec_voe_handler_t *voe)
 Returns the current data size. More...
 
void ecrt_voe_handler_write (ec_voe_handler_t *voe, size_t size)
 Start a VoE write operation. More...
 
void ecrt_voe_handler_read (ec_voe_handler_t *voe)
 Start a VoE read operation. More...
 
void ecrt_voe_handler_read_nosync (ec_voe_handler_t *voe)
 Start a VoE read operation without querying the sync manager status. More...
 
ec_request_state_t ecrt_voe_handler_execute (ec_voe_handler_t *voe)
 Execute the handler. More...
 
uint8_t * ecrt_reg_request_data (ec_reg_request_t *req)
 Access to the register request's data. More...
 
ec_request_state_t ecrt_reg_request_state (const ec_reg_request_t *req)
 Get the current state of the register request. More...
 
void ecrt_reg_request_write (ec_reg_request_t *req, uint16_t address, size_t size)
 Schedule an register write operation. More...
 
void ecrt_reg_request_read (ec_reg_request_t *req, uint16_t address, size_t size)
 Schedule a register read operation. More...
 

Detailed Description

EtherCAT interface for realtime applications.

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.

Changes in version 1.5.3:

Changes in version 1.5.2:

Changes in version 1.5:

Macro Definition Documentation

◆ EC_HAVE_REDUNDANCY

#define EC_HAVE_REDUNDANCY

Defined, if the redundancy features are available.

I. e. if the redundancy_active flag in ec_domain_state_t and the ecrt_master_link_state() method are available.

Definition at line 172 of file ecrt.h.

◆ EC_HAVE_EMERGENCY

#define EC_HAVE_EMERGENCY

Defined, if the CoE emergency ring feature is available.

I. e. if the ecrt_slave_config_emerg_*() methods are available.

Definition at line 178 of file ecrt.h.

◆ EC_HAVE_REG_ACCESS

#define EC_HAVE_REG_ACCESS

Defined, if the register access interface is available.

I. e. if the methods ecrt_slave_config_create_reg_request(), ecrt_reg_request_data(), ecrt_reg_request_state(), ecrt_reg_request_write() and ecrt_reg_request_read() are available.

Definition at line 186 of file ecrt.h.

◆ EC_END

#define EC_END   ~0U

End of list marker.

This can be used with ecrt_slave_config_pdos().

Definition at line 222 of file ecrt.h.

◆ EC_MAX_STRING_LENGTH

#define EC_MAX_STRING_LENGTH   64

Maximum string length.

Used in ec_slave_info_t.

Definition at line 232 of file ecrt.h.

◆ EC_MAX_PORTS

#define EC_MAX_PORTS   4

Maximum number of slave ports.

Definition at line 235 of file ecrt.h.

◆ EC_TIMEVAL2NANO

#define EC_TIMEVAL2NANO (   TV)    (((TV).tv_sec - 946684800ULL) * 1000000000ULL + (TV).tv_usec * 1000ULL)

Timeval to nanoseconds conversion.

This macro converts a Unix epoch time to EtherCAT DC time.

See also
void ecrt_master_application_time()
Parameters
TVstruct timeval containing epoch time.

Definition at line 245 of file ecrt.h.

◆ EC_COE_EMERGENCY_MSG_SIZE

#define EC_COE_EMERGENCY_MSG_SIZE   8

Size of a CoE emergency message in byte.

See also
ecrt_slave_config_emerg_pop().

Definition at line 252 of file ecrt.h.

◆ EC_READ_BIT

#define EC_READ_BIT (   DATA,
  POS 
)    ((*((uint8_t *) (DATA)) >> (POS)) & 0x01)

Read a certain bit of an EtherCAT data byte.

Parameters
DATAEtherCAT data pointer
POSbit position

Definition at line 2220 of file ecrt.h.

◆ EC_WRITE_BIT

#define EC_WRITE_BIT (   DATA,
  POS,
  VAL 
)
Value:
do { \
if (VAL) *((uint8_t *) (DATA)) |= (1 << (POS)); \
else *((uint8_t *) (DATA)) &= ~(1 << (POS)); \
} while (0)

Write a certain bit of an EtherCAT data byte.

Parameters
DATAEtherCAT data pointer
POSbit position
VALnew bit value

Definition at line 2228 of file ecrt.h.

◆ EC_READ_U8

#define EC_READ_U8 (   DATA)    ((uint8_t) *((uint8_t *) (DATA)))

Read an 8-bit unsigned value from EtherCAT data.

Returns
EtherCAT data value

Definition at line 2297 of file ecrt.h.

◆ EC_READ_S8

#define EC_READ_S8 (   DATA)    ((int8_t) *((uint8_t *) (DATA)))

Read an 8-bit signed value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2305 of file ecrt.h.

◆ EC_READ_U16

#define EC_READ_U16 (   DATA)    ((uint16_t) le16_to_cpup((void *) (DATA)))

Read a 16-bit unsigned value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2313 of file ecrt.h.

◆ EC_READ_S16

#define EC_READ_S16 (   DATA)    ((int16_t) le16_to_cpup((void *) (DATA)))

Read a 16-bit signed value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2321 of file ecrt.h.

◆ EC_READ_U32

#define EC_READ_U32 (   DATA)    ((uint32_t) le32_to_cpup((void *) (DATA)))

Read a 32-bit unsigned value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2329 of file ecrt.h.

◆ EC_READ_S32

#define EC_READ_S32 (   DATA)    ((int32_t) le32_to_cpup((void *) (DATA)))

Read a 32-bit signed value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2337 of file ecrt.h.

◆ EC_READ_U64

#define EC_READ_U64 (   DATA)    ((uint64_t) le64_to_cpup((void *) (DATA)))

Read a 64-bit unsigned value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2345 of file ecrt.h.

◆ EC_READ_S64

#define EC_READ_S64 (   DATA)    ((int64_t) le64_to_cpup((void *) (DATA)))

Read a 64-bit signed value from EtherCAT data.

Parameters
DATAEtherCAT data pointer
Returns
EtherCAT data value

Definition at line 2353 of file ecrt.h.

◆ EC_WRITE_U8

#define EC_WRITE_U8 (   DATA,
  VAL 
)
Value:
do { \
*((uint8_t *)(DATA)) = ((uint8_t) (VAL)); \
} while (0)

Write an 8-bit unsigned value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2401 of file ecrt.h.

◆ EC_WRITE_S8

#define EC_WRITE_S8 (   DATA,
  VAL 
)    EC_WRITE_U8(DATA, VAL)

Write an 8-bit signed value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2411 of file ecrt.h.

◆ EC_WRITE_U16

#define EC_WRITE_U16 (   DATA,
  VAL 
)
Value:
do { \
*((uint16_t *) (DATA)) = cpu_to_le16((uint16_t) (VAL)); \
} while (0)

Write a 16-bit unsigned value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2418 of file ecrt.h.

◆ EC_WRITE_S16

#define EC_WRITE_S16 (   DATA,
  VAL 
)    EC_WRITE_U16(DATA, VAL)

Write a 16-bit signed value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2428 of file ecrt.h.

◆ EC_WRITE_U32

#define EC_WRITE_U32 (   DATA,
  VAL 
)
Value:
do { \
*((uint32_t *) (DATA)) = cpu_to_le32((uint32_t) (VAL)); \
} while (0)

Write a 32-bit unsigned value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2435 of file ecrt.h.

◆ EC_WRITE_S32

#define EC_WRITE_S32 (   DATA,
  VAL 
)    EC_WRITE_U32(DATA, VAL)

Write a 32-bit signed value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2445 of file ecrt.h.

◆ EC_WRITE_U64

#define EC_WRITE_U64 (   DATA,
  VAL 
)
Value:
do { \
*((uint64_t *) (DATA)) = cpu_to_le64((uint64_t) (VAL)); \
} while (0)

Write a 64-bit unsigned value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2452 of file ecrt.h.

◆ EC_WRITE_S64

#define EC_WRITE_S64 (   DATA,
  VAL 
)    EC_WRITE_U64(DATA, VAL)

Write a 64-bit signed value to EtherCAT data.

Parameters
DATAEtherCAT data pointer
VALnew value

Definition at line 2462 of file ecrt.h.

Typedef Documentation

◆ ec_master_t

typedef struct ec_master ec_master_t
See also
ec_master

Definition at line 259 of file ecrt.h.

◆ ec_slave_config_t

See also
ec_slave_config

Definition at line 262 of file ecrt.h.

◆ ec_domain_t

typedef struct ec_domain ec_domain_t
See also
ec_domain

Definition at line 265 of file ecrt.h.

◆ ec_sdo_request_t

See also
ec_sdo_request.

Definition at line 268 of file ecrt.h.

◆ ec_soe_request_t

See also
ec_soe_request.

Definition at line 271 of file ecrt.h.

◆ ec_voe_handler_t

See also
ec_voe_handler.

Definition at line 274 of file ecrt.h.

◆ ec_reg_request_t

See also
ec_reg_request.

Definition at line 277 of file ecrt.h.

Enumeration Type Documentation

◆ ec_slave_port_desc_t

EtherCAT slave port descriptor.

Enumerator
EC_PORT_NOT_IMPLEMENTED 

Port is not implemented.

EC_PORT_NOT_CONFIGURED 

Port is not configured.

EC_PORT_EBUS 

Port is an E-Bus.

EC_PORT_MII 

Port is a MII.

Definition at line 368 of file ecrt.h.

◆ ec_wc_state_t

Domain working counter interpretation.

This is used in ec_domain_state_t.

Enumerator
EC_WC_ZERO 

No registered process data were exchanged.

EC_WC_INCOMPLETE 

Some of the registered process data were exchanged.

EC_WC_COMPLETE 

All registered process data were exchanged.

Definition at line 423 of file ecrt.h.

◆ ec_direction_t

Direction type for PDO assignment functions.

Enumerator
EC_DIR_INVALID 

Invalid direction.

Do not use this value.

EC_DIR_OUTPUT 

Values written by the master.

EC_DIR_INPUT 

Values read by the master.

EC_DIR_COUNT 

Number of directions.

For internal use only.

Definition at line 446 of file ecrt.h.

◆ ec_watchdog_mode_t

Watchdog mode for sync manager configuration.

Used to specify, if a sync manager's watchdog is to be enabled.

Enumerator
EC_WD_DEFAULT 

Use the default setting of the sync manager.

EC_WD_ENABLE 

Enable the watchdog.

EC_WD_DISABLE 

Disable the watchdog.

Definition at line 459 of file ecrt.h.

◆ ec_request_state_t

Request state.

This is used as return type for ecrt_sdo_request_state() and ecrt_voe_handler_state().

Enumerator
EC_REQUEST_UNUSED 

Not requested.

EC_REQUEST_BUSY 

Request is being processed.

EC_REQUEST_SUCCESS 

Request was processed successfully.

EC_REQUEST_ERROR 

Request processing failed.

Definition at line 546 of file ecrt.h.

◆ ec_al_state_t

Application-layer state.

Enumerator
EC_AL_STATE_INIT 

Init.

EC_AL_STATE_PREOP 

Pre-operational.

EC_AL_STATE_SAFEOP 

Safe-operational.

EC_AL_STATE_OP 

Operational.

Definition at line 557 of file ecrt.h.

Function Documentation

◆ ecrt_version_magic()

unsigned int ecrt_version_magic ( void  )

Returns the version magic of the realtime interface.

Returns
Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time.

Definition at line 651 of file module.c.

◆ ecrt_request_master()

ec_master_t* ecrt_request_master ( unsigned int  master_index)

Requests an EtherCAT master for realtime operation.

Before an application can access an EtherCAT master, it has to reserve one for exclusive use.

In userspace, this is a convenience function for ecrt_open_master() and ecrt_master_reserve().

This function has to be the first function an application has to call to use EtherCAT. The function takes the index of the master as its argument. The first master has index 0, the n-th master has index n - 1. The number of masters has to be specified when loading the master module.

Returns
Pointer to the reserved master, otherwise NULL.
Parameters
master_indexIndex of the master to request.

Definition at line 617 of file module.c.

◆ ecrt_release_master()

void ecrt_release_master ( ec_master_t master)

Releases a requested EtherCAT master.

After use, a master it has to be released to make it available for other applications.

This method frees all created data structures. It should not be called in realtime context.

If the master was activated, ecrt_master_deactivate() is called internally.

Parameters
masterEtherCAT master

Definition at line 625 of file module.c.

◆ ecrt_master_callbacks()

void ecrt_master_callbacks ( ec_master_t master,
void(*)(void *)  send_cb,
void(*)(void *)  receive_cb,
void *  cb_data 
)

Sets the locking callbacks.

For concurrent master access, i. e. if other instances than the application want to send and receive datagrams on the bus, the application has to provide a callback mechanism. This method takes two function pointers as its parameters. Asynchronous master access (like EoE processing) is only possible if the callbacks have been set.

The task of the send callback (send_cb) is to decide, if the bus is currently accessible and whether or not to call the ecrt_master_send_ext() method.

The task of the receive callback (receive_cb) is to decide, if a call to ecrt_master_receive() is allowed and to execute it respectively.

Attention
This method has to be called before ecrt_master_activate().
Parameters
masterEtherCAT master
send_cbDatagram sending callback.
receive_cbReceive callback.
cb_dataArbitrary pointer passed to the callback functions.

Definition at line 2743 of file master.c.

◆ ecrt_master_create_domain()

ec_domain_t* ecrt_master_create_domain ( ec_master_t master)

Creates a new process data domain.

For process data exchange, at least one process data domain is needed. This method creates a new process data domain and returns a pointer to the new domain object. This object can be used for registering PDOs and exchanging them in cyclic operation.

This method allocates memory and should be called in non-realtime context before ecrt_master_activate().

Returns
Pointer to the new domain on success, else NULL.
Parameters
masterEtherCAT master.

Definition at line 2311 of file master.c.

◆ ecrt_master_slave_config()

ec_slave_config_t* ecrt_master_slave_config ( ec_master_t master,
uint16_t  alias,
uint16_t  position,
uint32_t  vendor_id,
uint32_t  product_code 
)

Obtains a slave configuration.

Creates a slave configuration object for the given alias and position tuple and returns it. If a configuration with the same alias and position already exists, it will be re-used. In the latter case, the given vendor ID and product code are compared to the stored ones. On mismatch, an error message is raised and the function returns NULL.

Slaves are addressed with the alias and position parameters.

  • If alias is zero, position is interpreted as the desired slave's ring position.
  • If alias is non-zero, it matches a slave with the given alias. In this case, position is interpreted as ring offset, starting from the aliased slave, so a position of zero means the aliased slave itself and a positive value matches the n-th slave behind the aliased one.

If the slave with the given address is found during the bus configuration, its vendor ID and product code are matched against the given value. On mismatch, the slave is not configured and an error message is raised.

If different slave configurations are pointing to the same slave during bus configuration, a warning is raised and only the first configuration is applied.

This method allocates memory and should be called in non-realtime context before ecrt_master_activate().

Return values
>0Pointer to the slave configuration structure.
NULLin the error case.
Parameters
masterEtherCAT master
aliasSlave alias.
positionSlave position.
vendor_idExpected vendor ID.
product_codeExpected product code.

Definition at line 2636 of file master.c.

◆ ecrt_master_select_reference_clock()

int ecrt_master_select_reference_clock ( ec_master_t master,
ec_slave_config_t sc 
)

Selects the reference clock for distributed clocks.

If this method is not called for a certain master, or if the slave configuration pointer is NULL, then the first slave with DC functionality will provide the reference clock.

Returns
0 on success, otherwise negative error code.
Parameters
masterEtherCAT master.
scSlave config of the slave to use as the reference slave (or NULL).

Definition at line 2647 of file master.c.

◆ ecrt_master()

int ecrt_master ( ec_master_t master,
ec_master_info_t master_info 
)

Obtains master information.

No memory is allocated on the heap in this function.

Attention
The pointer to this structure must point to a valid variable.
Returns
0 in case of success, else < 0
Parameters
masterEtherCAT master
master_infoStructure that will output the information

Definition at line 2667 of file master.c.

◆ ecrt_master_get_slave()

int ecrt_master_get_slave ( ec_master_t master,
uint16_t  slave_position,
ec_slave_info_t slave_info 
)

Obtains slave information.

Tries to find the slave with the given ring position. The obtained information is stored in a structure. No memory is allocated on the heap in this function.

Attention
The pointer to this structure must point to a valid variable.
Returns
0 in case of success, else < 0
Parameters
masterEtherCAT master
slave_positionSlave position.
slave_infoStructure that will output the information

Definition at line 2681 of file master.c.

◆ ecrt_master_sdo_download()

int ecrt_master_sdo_download ( ec_master_t master,
uint16_t  slave_position,
uint16_t  index,
uint8_t  subindex,
uint8_t *  data,
size_t  data_size,
uint32_t *  abort_code 
)

Executes an SDO download request to write data to a slave.

This request is processed by the master state machine. This method blocks, until the request has been processed and may not be called in realtime context.

Return values
0Success.
<0Error code.
Parameters
masterEtherCAT master.
slave_positionSlave position.
indexIndex of the SDO.
subindexSubindex of the SDO.
dataData buffer to download.
data_sizeSize of the data buffer.
abort_codeAbort code of the SDO download.

Definition at line 2878 of file master.c.

◆ ecrt_master_sdo_download_complete()

int ecrt_master_sdo_download_complete ( ec_master_t master,
uint16_t  slave_position,
uint16_t  index,
uint8_t *  data,
size_t  data_size,
uint32_t *  abort_code 
)

Executes an SDO download request to write data to a slave via complete access.

This request is processed by the master state machine. This method blocks, until the request has been processed and may not be called in realtime context.

Return values
0Success.
<0Error code.
Parameters
masterEtherCAT master.
slave_positionSlave position.
indexIndex of the SDO.
dataData buffer to download.
data_sizeSize of the data buffer.
abort_codeAbort code of the SDO download.

Definition at line 2957 of file master.c.

◆ ecrt_master_sdo_upload()

int ecrt_master_sdo_upload ( ec_master_t master,
uint16_t  slave_position,
uint16_t  index,
uint8_t  subindex,
uint8_t *  target,
size_t  target_size,
size_t *  result_size,
uint32_t *  abort_code 
)

Executes an SDO upload request to read data from a slave.

This request is processed by the master state machine. This method blocks, until the request has been processed and may not be called in realtime context.

Return values
0Success.
<0Error code.
Parameters
masterEtherCAT master.
slave_positionSlave position.
indexIndex of the SDO.
subindexSubindex of the SDO.
targetTarget buffer for the upload.
target_sizeSize of the target buffer.
result_sizeUploaded data size.
abort_codeAbort code of the SDO upload.

Definition at line 3038 of file master.c.

◆ ecrt_master_write_idn()

int ecrt_master_write_idn ( ec_master_t master,
uint16_t  slave_position,
uint8_t  drive_no,
uint16_t  idn,
uint8_t *  data,
size_t  data_size,
uint16_t *  error_code 
)

Executes an SoE write request.

Starts writing an IDN and blocks until the request was processed, or an error occurred.

Return values
0Success.
<0Error code.
Parameters
masterEtherCAT master.
slave_positionSlave position.
drive_noDrive number.
idnSoE IDN (see ecrt_slave_config_idn()).
dataPointer to data to write.
data_sizeSize of data to write.
error_codePointer to variable, where an SoE error code can be stored.

Definition at line 3121 of file master.c.

◆ ecrt_master_read_idn()

int ecrt_master_read_idn ( ec_master_t master,
uint16_t  slave_position,
uint8_t  drive_no,
uint16_t  idn,
uint8_t *  target,
size_t  target_size,
size_t *  result_size,
uint16_t *  error_code 
)

Executes an SoE read request.

Starts reading an IDN and blocks until the request was processed, or an error occurred.

Return values
0Success.
<0Error code.
Parameters
masterEtherCAT master.
slave_positionSlave position.
drive_noDrive number.
idnSoE IDN (see ecrt_slave_config_idn()).
targetPointer to memory where the read data can be stored.
target_sizeSize of the memory target points to.
result_sizeActual size of the received data.
error_codePointer to variable, where an SoE error code can be stored.

Definition at line 3197 of file master.c.

◆ ecrt_master_activate()

int ecrt_master_activate ( ec_master_t master)

Finishes the configuration phase and prepares for cyclic operation.

This function tells the master that the configuration phase is finished and the realtime operation will begin. The function allocates internal memory for the domains and calculates the logical FMMU addresses for domain members. It tells the master state machine that the bus configuration is now to be applied.

Attention
After this function has been called, the realtime application is in charge of cyclically calling ecrt_master_send() and ecrt_master_receive() to ensure bus communication. Before calling this function, the master thread is responsible for that, so these functions may not be called! The method itself allocates memory and should not be called in realtime context.
Returns
0 in case of success, else < 0
Parameters
masterEtherCAT master.

Definition at line 2321 of file master.c.

◆ ecrt_master_deactivate()

void ecrt_master_deactivate ( ec_master_t master)

Deactivates the master.

Removes the bus configuration. All objects created by ecrt_master_create_domain(), ecrt_master_slave_config(), ecrt_domain_data() ecrt_slave_config_create_sdo_request() and ecrt_slave_config_create_voe_handler() are freed, so pointers to them become invalid.

This method should not be called in realtime context.

Parameters
masterEtherCAT master.

Definition at line 2395 of file master.c.

◆ ecrt_master_set_send_interval()

int ecrt_master_set_send_interval ( ec_master_t master,
size_t  send_interval 
)

Set interval between calls to ecrt_master_send().

This information helps the master to decide, how much data can be appended to a frame by the master state machine. When the master is configured with –enable-hrtimers, this is used to calculate the scheduling of the master thread.

Return values
0on success.
<0Error code.
Parameters
masterEtherCAT master.
send_intervalSend interval in us

◆ ecrt_master_send()

void ecrt_master_send ( ec_master_t master)

Sends all datagrams in the queue.

This method takes all datagrams, that have been queued for transmission, puts them into frames, and passes them to the Ethernet device for sending.

Has to be called cyclically by the application after ecrt_master_activate() has returned.

Parameters
masterEtherCAT master.

Definition at line 2465 of file master.c.

◆ ecrt_master_receive()

void ecrt_master_receive ( ec_master_t master)

Fetches received frames from the hardware and processes the datagrams.

Queries the network device for received frames by calling the interrupt service routine. Extracts received datagrams and dispatches the results to the datagram objects in the queue. Received datagrams, and the ones that timed out, will be marked, and dequeued.

Has to be called cyclically by the realtime application after ecrt_master_activate() has returned.

Parameters
masterEtherCAT master.

Definition at line 2509 of file master.c.

◆ ecrt_master_send_ext()

void ecrt_master_send_ext ( ec_master_t master)

Sends non-application datagrams.

This method has to be called in the send callback function passed via ecrt_master_callbacks() to allow the sending of non-application datagrams.

Parameters
masterEtherCAT master.

Definition at line 2561 of file master.c.

◆ ecrt_master_state()

void ecrt_master_state ( const ec_master_t master,
ec_master_state_t state 
)

Reads the current master state.

Stores the master state information in the given state structure.

This method returns a global state. For the link-specific states in a redundant bus topology, use the ecrt_master_link_state() method.

Parameters
masterEtherCAT master.
stateStructure to store the information.

Definition at line 2757 of file master.c.

◆ ecrt_master_link_state()

int ecrt_master_link_state ( const ec_master_t master,
unsigned int  dev_idx,
ec_master_link_state_t state 
)

Reads the current state of a redundant link.

Stores the link state information in the given state structure.

Returns
Zero on success, otherwise negative error code.
Parameters
masterEtherCAT master.
dev_idxIndex of the device (0 = main device, 1 = first backup device, ...).
stateStructure to store the information.

Definition at line 2780 of file master.c.

◆ ecrt_master_application_time()

void ecrt_master_application_time ( ec_master_t master,
uint64_t  app_time 
)

Sets the application time.

The master has to know the application's time when operating slaves with distributed clocks. The time is not incremented by the master itself, so this method has to be called cyclically.

Attention
The time passed to this method is used to calculate the phase of the slaves' SYNC0/1 interrupts. It should be called constantly at the same point of the realtime cycle. So it is recommended to call it at the start of the calculations to avoid deviancies due to changing execution times.

The time is used when setting the slaves' System Time Offset and Cyclic Operation Start Time registers and when synchronizing the DC reference clock to the application time via ecrt_master_sync_reference_clock().

The time is defined as nanoseconds from 2000-01-01 00:00. Converting an epoch time can be done with the EC_TIMEVAL2NANO() macro, but is not necessary, since the absolute value is not of any interest.

Parameters
masterEtherCAT master.
app_timeApplication time.

Definition at line 2796 of file master.c.

◆ ecrt_master_sync_reference_clock()

void ecrt_master_sync_reference_clock ( ec_master_t master)

Queues the DC reference clock drift compensation datagram for sending.

The reference clock will by synchronized to the application time provided by the last call off ecrt_master_application_time().

Parameters
masterEtherCAT master.

Definition at line 2826 of file master.c.

◆ ecrt_master_sync_reference_clock_to()

void ecrt_master_sync_reference_clock_to ( ec_master_t master,
uint64_t  sync_time 
)

Queues the DC reference clock drift compensation datagram for sending.

The reference clock will by synchronized to the time passed in the sync_time parameter.

Parameters
masterEtherCAT master.
sync_timeSync reference clock to this time.

Definition at line 2836 of file master.c.

◆ ecrt_master_sync_slave_clocks()

void ecrt_master_sync_slave_clocks ( ec_master_t master)

Queues the DC clock drift compensation datagram for sending.

All slave clocks synchronized to the reference clock.

Parameters
masterEtherCAT master.

Definition at line 2849 of file master.c.

◆ ecrt_master_reference_clock_time()

int ecrt_master_reference_clock_time ( ec_master_t master,
uint32_t *  time 
)

Get the lower 32 bit of the reference clock system time.

This method can be used to synchronize the master to the reference clock.

The reference clock system time is queried via the ecrt_master_sync_slave_clocks() method, that reads the system time of the reference clock and writes it to the slave clocks (so be sure to call it cyclically to get valid data).

Attention
The returned time is the system time of the reference clock minus the transmission delay of the reference clock.
Return values
0success, system time was written into time.
-ENXIONo reference clock found.
-EIOSlave synchronization datagram was not received.
Parameters
masterEtherCAT master.
timePointer to store the queried system time.

Definition at line 2807 of file master.c.

◆ ecrt_master_sync_monitor_queue()

void ecrt_master_sync_monitor_queue ( ec_master_t master)

Queues the DC synchrony monitoring datagram for sending.

The datagram broadcast-reads all "System time difference" registers (0x092c) to get an upper estimation of the DC synchrony. The result can be checked with the ecrt_master_sync_monitor_process() method.

Parameters
masterEtherCAT master.

Definition at line 2859 of file master.c.

◆ ecrt_master_sync_monitor_process()

uint32_t ecrt_master_sync_monitor_process ( ec_master_t master)

Processes the DC synchrony monitoring datagram.

If the sync monitoring datagram was sent before with ecrt_master_sync_monitor_queue(), the result can be queried with this method.

Returns
Upper estimation of the maximum time difference in ns.
Parameters
masterEtherCAT master.

Definition at line 2867 of file master.c.

◆ ecrt_master_reset()

void ecrt_master_reset ( ec_master_t master)

Retry configuring slaves.

Via this method, the application can tell the master to bring all slaves to OP state. In general, this is not necessary, because it is automatically done by the master. But with special slaves, that can be reconfigured by the vendor during runtime, it can be useful.

Parameters
masterEtherCAT master.

Definition at line 3281 of file master.c.

◆ ecrt_slave_config_sync_manager()

int ecrt_slave_config_sync_manager ( ec_slave_config_t sc,
uint8_t  sync_index,
ec_direction_t  direction,
ec_watchdog_mode_t  watchdog_mode 
)

Configure a sync manager.

Sets the direction of a sync manager. This overrides the direction bits from the default control register from SII.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
zero on success, else non-zero
Parameters
scSlave configuration.
sync_indexSync manager index. Must be less than EC_MAX_SYNC_MANAGERS.
directionInput/Output.
watchdog_modeWatchdog mode.

Definition at line 629 of file slave_config.c.

◆ ecrt_slave_config_watchdog()

void ecrt_slave_config_watchdog ( ec_slave_config_t sc,
uint16_t  watchdog_divider,
uint16_t  watchdog_intervals 
)

Configure a slave's watchdog times.

This method has to be called in non-realtime context before ecrt_master_activate().

Parameters
scSlave configuration.
watchdog_dividerNumber of 40 ns intervals (register 0x0400). Used as a base unit for all slave watchdogs^. If set to zero, the value is not written, so the default is used.
watchdog_intervalsNumber of base intervals for sync manager watchdog (register 0x0420). If set to zero, the value is not written, so the default is used.

Definition at line 656 of file slave_config.c.

◆ ecrt_slave_config_pdo_assign_add()

int ecrt_slave_config_pdo_assign_add ( ec_slave_config_t sc,
uint8_t  sync_index,
uint16_t  index 
)

Add a PDO to a sync manager's PDO assignment.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_pdos()
Returns
zero on success, else non-zero
Parameters
scSlave configuration.
sync_indexSync manager index. Must be less than EC_MAX_SYNC_MANAGERS.
indexIndex of the PDO to assign.

Definition at line 668 of file slave_config.c.

◆ ecrt_slave_config_pdo_assign_clear()

void ecrt_slave_config_pdo_assign_clear ( ec_slave_config_t sc,
uint8_t  sync_index 
)

Clear a sync manager's PDO assignment.

This can be called before assigning PDOs via ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a sync manager.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_pdos()
Parameters
scSlave configuration.
sync_indexSync manager index. Must be less than EC_MAX_SYNC_MANAGERS.

Definition at line 698 of file slave_config.c.

◆ ecrt_slave_config_pdo_mapping_add()

int ecrt_slave_config_pdo_mapping_add ( ec_slave_config_t sc,
uint16_t  pdo_index,
uint16_t  entry_index,
uint8_t  entry_subindex,
uint8_t  entry_bit_length 
)

Add a PDO entry to the given PDO's mapping.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_pdos()
Returns
zero on success, else non-zero
Parameters
scSlave configuration.
pdo_indexIndex of the PDO.
entry_indexIndex of the PDO entry to add to the PDO's mapping.
entry_subindexSubindex of the PDO entry to add to the PDO's mapping.
entry_bit_lengthSize of the PDO entry in bit.

Definition at line 716 of file slave_config.c.

◆ ecrt_slave_config_pdo_mapping_clear()

void ecrt_slave_config_pdo_mapping_clear ( ec_slave_config_t sc,
uint16_t  pdo_index 
)

Clear the mapping of a given PDO.

This can be called before mapping PDO entries via ecrt_slave_config_pdo_mapping_add(), to clear the default mapping.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_pdos()
Parameters
scSlave configuration.
pdo_indexIndex of the PDO.

Definition at line 753 of file slave_config.c.

◆ ecrt_slave_config_pdos()

int ecrt_slave_config_pdos ( ec_slave_config_t sc,
unsigned int  n_syncs,
const ec_sync_info_t  syncs[] 
)

Specify a complete PDO configuration.

This function is a convenience wrapper for the functions ecrt_slave_config_sync_manager(), ecrt_slave_config_pdo_assign_clear(), ecrt_slave_config_pdo_assign_add(), ecrt_slave_config_pdo_mapping_clear() and ecrt_slave_config_pdo_mapping_add(), that are better suitable for automatic code generation.

The following example shows, how to specify a complete configuration, including the PDO mappings. With this information, the master is able to reserve the complete process data, even if the slave is not present at configuration time:

ec_pdo_entry_info_t el3162_channel1[] = {
{0x3101, 1, 8}, // status
{0x3101, 2, 16} // value
};
ec_pdo_entry_info_t el3162_channel2[] = {
{0x3102, 1, 8}, // status
{0x3102, 2, 16} // value
};
ec_pdo_info_t el3162_pdos[] = {
{0x1A00, 2, el3162_channel1},
{0x1A01, 2, el3162_channel2}
};
ec_sync_info_t el3162_syncs[] = {
{3, EC_DIR_INPUT, 2, el3162_pdos},
{0xff}
};
if (ecrt_slave_config_pdos(sc_ana_in, EC_END, el3162_syncs)) {
// handle error
}

The next example shows, how to configure the PDO assignment only. The entries for each assigned PDO are taken from the PDO's default mapping. Please note, that PDO entry registration will fail, if the PDO configuration is left empty and the slave is offline.

ec_pdo_info_t pdos[] = {
{0x1600}, // Channel 1
{0x1601} // Channel 2
};
ec_sync_info_t syncs[] = {
{3, EC_DIR_INPUT, 2, pdos},
};
if (ecrt_slave_config_pdos(slave_config_ana_in, 1, syncs)) {
// handle error
}

Processing of syncs will stop, if

  • the number of processed items reaches n_syncs, or
  • the index member of an ec_sync_info_t item is 0xff. In this case, n_syncs should set to a number greater than the number of list items; using EC_END is recommended.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
zero on success, else non-zero
Parameters
scSlave configuration.
n_syncsNumber of sync manager configurations in syncs.
syncsArray of sync manager configurations.

Definition at line 778 of file slave_config.c.

◆ ecrt_slave_config_reg_pdo_entry()

int ecrt_slave_config_reg_pdo_entry ( ec_slave_config_t sc,
uint16_t  entry_index,
uint8_t  entry_subindex,
ec_domain_t domain,
unsigned int *  bit_position 
)

Registers a PDO entry for process data exchange in a domain.

Searches the assigned PDOs for the given PDO entry. An error is raised, if the given entry is not mapped. Otherwise, the corresponding sync manager and FMMU configurations are provided for slave configuration and the respective sync manager's assigned PDOs are appended to the given domain, if not already done. The offset of the requested PDO entry's data inside the domain's process data is returned. Optionally, the PDO entry bit position (0-7) can be retrieved via the bit_position output parameter. This pointer may be NULL, in this case an error is raised if the PDO entry does not byte-align.

This method has to be called in non-realtime context before ecrt_master_activate().

Return values
>=0Success: Offset of the PDO entry's process data.
<0Error code.
Parameters
scSlave configuration.
entry_indexIndex of the PDO entry to register.
entry_subindexSubindex of the PDO entry to register.
domainDomain.
bit_positionOptional address if bit addressing is desired

Definition at line 845 of file slave_config.c.

◆ ecrt_slave_config_reg_pdo_entry_pos()

int ecrt_slave_config_reg_pdo_entry_pos ( ec_slave_config_t sc,
uint8_t  sync_index,
unsigned int  pdo_pos,
unsigned int  entry_pos,
ec_domain_t domain,
unsigned int *  bit_position 
)

Registers a PDO entry using its position.

Similar to ecrt_slave_config_reg_pdo_entry(), but not using PDO indices but offsets in the PDO mapping, because PDO entry indices may not be unique inside a slave's PDO mapping. An error is raised, if one of the given positions is out of range.

This method has to be called in non-realtime context before ecrt_master_activate().

Return values
>=0Success: Offset of the PDO entry's process data.
<0Error code.
Parameters
scSlave configuration.
sync_indexSync manager index.
pdo_posPosition of the PDO inside the SM.
entry_posPosition of the entry inside the PDO.
domainDomain.
bit_positionOptional address if bit addressing is desired

Definition at line 900 of file slave_config.c.

◆ ecrt_slave_config_dc()

void ecrt_slave_config_dc ( ec_slave_config_t sc,
uint16_t  assign_activate,
uint32_t  sync0_cycle,
int32_t  sync0_shift,
uint32_t  sync1_cycle,
int32_t  sync1_shift 
)

Configure distributed clocks.

Sets the AssignActivate word and the cycle and shift times for the sync signals.

The AssignActivate word is vendor-specific and can be taken from the XML device description file (Device -> Dc -> AssignActivate). Set this to zero, if the slave shall be operated without distributed clocks (default).

This method has to be called in non-realtime context before ecrt_master_activate().

Attention
The sync1_shift time is ignored.
Parameters
scSlave configuration.
assign_activateAssignActivate word.
sync0_cycleSYNC0 cycle time [ns].
sync0_shiftSYNC0 shift time [ns].
sync1_cycleSYNC1 cycle time [ns].
sync1_shiftSYNC1 shift time [ns].

Definition at line 965 of file slave_config.c.

◆ ecrt_slave_config_sdo()

int ecrt_slave_config_sdo ( ec_slave_config_t sc,
uint16_t  index,
uint8_t  subindex,
const uint8_t *  data,
size_t  size 
)

Add an SDO configuration.

An SDO configuration is stored in the slave configuration object and is downloaded to the slave whenever the slave is being configured by the master. This usually happens once on master activation, but can be repeated subsequently, for example after the slave's power supply failed.

Attention
The SDOs for PDO assignment (0x1C10 - 0x1C2F) and PDO mapping (0x1600 - 0x17FF and 0x1A00 - 0x1BFF) should not be configured with this function, because they are part of the slave configuration done by the master. Please use ecrt_slave_config_pdos() and friends instead.

This is the generic function for adding an SDO configuration. Please note that the this function does not do any endianness correction. If datatype-specific functions are needed (that automatically correct the endianness), have a look at ecrt_slave_config_sdo8(), ecrt_slave_config_sdo16() and ecrt_slave_config_sdo32().

This method has to be called in non-realtime context before ecrt_master_activate().

Return values
0Success.
<0Error code.
Parameters
scSlave configuration.
indexIndex of the SDO to configure.
subindexSubindex of the SDO to configure.
dataPointer to the data.
sizeSize of the data.

Definition at line 984 of file slave_config.c.

◆ ecrt_slave_config_sdo8()

int ecrt_slave_config_sdo8 ( ec_slave_config_t sc,
uint16_t  sdo_index,
uint8_t  sdo_subindex,
uint8_t  value 
)

Add a configuration value for an 8-bit SDO.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_sdo().
Return values
0Success.
<0Error code.
Parameters
scSlave configuration
sdo_indexIndex of the SDO to configure.
sdo_subindexSubindex of the SDO to configure.
valueValue to set.

Definition at line 1024 of file slave_config.c.

◆ ecrt_slave_config_sdo16()

int ecrt_slave_config_sdo16 ( ec_slave_config_t sc,
uint16_t  sdo_index,
uint8_t  sdo_subindex,
uint16_t  value 
)

Add a configuration value for a 16-bit SDO.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_sdo().
Return values
0Success.
<0Error code.
Parameters
scSlave configuration
sdo_indexIndex of the SDO to configure.
sdo_subindexSubindex of the SDO to configure.
valueValue to set.

Definition at line 1039 of file slave_config.c.

◆ ecrt_slave_config_sdo32()

int ecrt_slave_config_sdo32 ( ec_slave_config_t sc,
uint16_t  sdo_index,
uint8_t  sdo_subindex,
uint32_t  value 
)

Add a configuration value for a 32-bit SDO.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_sdo().
Return values
0Success.
<0Error code.
Parameters
scSlave configuration
sdo_indexIndex of the SDO to configure.
sdo_subindexSubindex of the SDO to configure.
valueValue to set.

Definition at line 1054 of file slave_config.c.

◆ ecrt_slave_config_complete_sdo()

int ecrt_slave_config_complete_sdo ( ec_slave_config_t sc,
uint16_t  index,
const uint8_t *  data,
size_t  size 
)

Add configuration data for a complete SDO.

The SDO data are transferred via CompleteAccess. Data for the first subindex (0) have to be included.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_sdo().
Return values
0Success.
<0Error code.
Parameters
scSlave configuration.
indexIndex of the SDO to configure.
dataPointer to the data.
sizeSize of the data.

Definition at line 1069 of file slave_config.c.

◆ ecrt_slave_config_emerg_size()

int ecrt_slave_config_emerg_size ( ec_slave_config_t sc,
size_t  elements 
)

Set the size of the CoE emergency ring buffer.

The initial size is zero, so all messages will be dropped. This method can be called even after master activation, but it will clear the ring buffer!

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
0 on success, or negative error code.
Parameters
scSlave configuration.
elementsNumber of records of the CoE emergency ring.

Definition at line 1109 of file slave_config.c.

◆ ecrt_slave_config_emerg_pop()

int ecrt_slave_config_emerg_pop ( ec_slave_config_t sc,
uint8_t *  target 
)

Read and remove one record from the CoE emergency ring buffer.

A record consists of 8 bytes:

Byte 0-1: Error code (little endian) Byte 2: Error register Byte 3-7: Data

Returns
0 on success (record popped), or negative error code (i. e. -ENOENT, if ring is empty).
Parameters
scSlave configuration.
targetPointer to target memory (at least EC_COE_EMERGENCY_MSG_SIZE bytes).

Definition at line 1116 of file slave_config.c.

◆ ecrt_slave_config_emerg_clear()

int ecrt_slave_config_emerg_clear ( ec_slave_config_t sc)

Clears CoE emergency ring buffer and the overrun counter.

Returns
0 on success, or negative error code.
Parameters
scSlave configuration.

Definition at line 1123 of file slave_config.c.

◆ ecrt_slave_config_emerg_overruns()

int ecrt_slave_config_emerg_overruns ( ec_slave_config_t sc)

Read the number of CoE emergency overruns.

The overrun counter will be incremented when a CoE emergency message could not be stored in the ring buffer and had to be dropped. Call ecrt_slave_config_emerg_clear() to reset the counter.

Returns
Number of overruns since last clear, or negative error code.
Parameters
scSlave configuration.

Definition at line 1130 of file slave_config.c.

◆ ecrt_slave_config_create_sdo_request()

ec_sdo_request_t* ecrt_slave_config_create_sdo_request ( ec_slave_config_t sc,
uint16_t  index,
uint8_t  subindex,
size_t  size 
)

Create an SDO request to exchange SDOs during realtime operation.

The created SDO request object is freed automatically when the master is released.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
New SDO request, or NULL on error.
Parameters
scSlave configuration.
indexSDO index.
subindexSDO subindex.
sizeData size to reserve.

Definition at line 1179 of file slave_config.c.

◆ ecrt_slave_config_create_soe_request()

ec_soe_request_t* ecrt_slave_config_create_soe_request ( ec_slave_config_t sc,
uint8_t  drive_no,
uint16_t  idn,
size_t  size 
)

Create an SoE request to exchange SoE IDNs during realtime operation.

The created SoE request object is freed automatically when the master is released.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
New SoE request, or NULL on error.
Parameters
scSlave configuration.
drive_noDrive number.
idnSercos ID-Number.
sizeData size to reserve.

Definition at line 1231 of file slave_config.c.

◆ ecrt_slave_config_create_voe_handler()

ec_voe_handler_t* ecrt_slave_config_create_voe_handler ( ec_slave_config_t sc,
size_t  size 
)

Create an VoE handler to exchange vendor-specific data during realtime operation.

The number of VoE handlers per slave configuration is not limited, but usually it is enough to create one for sending and one for receiving, if both can be done simultaneously.

The created VoE handler object is freed automatically when the master is released.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
New VoE handler, or NULL on error.
Parameters
scSlave configuration.
sizeData size to reserve.

Definition at line 1316 of file slave_config.c.

◆ ecrt_slave_config_create_reg_request()

ec_reg_request_t* ecrt_slave_config_create_reg_request ( ec_slave_config_t sc,
size_t  size 
)

Create a register request to exchange EtherCAT register contents during realtime operation.

This interface should not be used to take over master functionality, instead it is intended for debugging and monitoring reasons.

The created register request object is freed automatically when the master is released.

This method has to be called in non-realtime context before ecrt_master_activate().

Returns
New register request, or NULL on error.
Parameters
scSlave configuration.
sizeData size to reserve.

Definition at line 1274 of file slave_config.c.

◆ ecrt_slave_config_state()

void ecrt_slave_config_state ( const ec_slave_config_t sc,
ec_slave_config_state_t state 
)

Outputs the state of the slave configuration.

Stores the state information in the given state structure. The state information is updated by the master state machine, so it may take a few cycles, until it changes.

Attention
If the state of process data exchange shall be monitored in realtime, ecrt_domain_state() should be used.
Parameters
scSlave configuration
stateState object to write to.

Definition at line 1326 of file slave_config.c.

◆ ecrt_slave_config_idn()

int ecrt_slave_config_idn ( ec_slave_config_t sc,
uint8_t  drive_no,
uint16_t  idn,
ec_al_state_t  state,
const uint8_t *  data,
size_t  size 
)

Add an SoE IDN configuration.

A configuration for a Sercos-over-EtherCAT IDN is stored in the slave configuration object and is written to the slave whenever the slave is being configured by the master. This usually happens once on master activation, but can be repeated subsequently, for example after the slave's power supply failed.

The idn parameter can be separated into several sections:

  • Bit 15: Standard data (0) or Product data (1)
  • Bit 14 - 12: Parameter set (0 - 7)
  • Bit 11 - 0: Data block number (0 - 4095)

Please note that the this function does not do any endianness correction. Multi-byte data have to be passed in EtherCAT endianness (little-endian).

This method has to be called in non-realtime context before ecrt_master_activate().

Return values
0Success.
<0Error code.
Parameters
scSlave configuration.
drive_noDrive number.
idnSoE IDN.
stateAL state in which to write the IDN (PREOP or SAFEOP).
dataPointer to the data.
sizeSize of the data.

Definition at line 1343 of file slave_config.c.

◆ ecrt_slave_config_flag()

int ecrt_slave_config_flag ( ec_slave_config_t sc,
const char *  key,
int32_t  value 
)

Adds a feature flag to a slave configuration.

Feature flags are a generic way to configure slave-specific behavior.

Multiple calls with the same slave configuration and key will overwrite the configuration.

The following flags may be available:

  • AssignToPdi: Zero (default) keeps the slave information interface (SII) assigned to EtherCAT (except during transition to PREOP). Non-zero assigns the SII to the slave controller side before going to PREOP and leaves it there until a write command happens.
  • WaitBeforeSAFEOPms: Number of milliseconds to wait before commanding the transition from PREOP to SAFEOP. This can be used as a workaround for slaves that need a little time to initialize.

This method has to be called in non-realtime context before ecrt_master_activate().

Return values
0Success.
<0Error code.
Parameters
scSlave configuration.
keyKey as null-terminated ascii string.
valueValue to store.

Definition at line 1398 of file slave_config.c.

◆ ecrt_domain_reg_pdo_entry_list()

int ecrt_domain_reg_pdo_entry_list ( ec_domain_t domain,
const ec_pdo_entry_reg_t pdo_entry_regs 
)

Registers a bunch of PDO entries for a domain.

This method has to be called in non-realtime context before ecrt_master_activate().

See also
ecrt_slave_config_reg_pdo_entry()
Attention
The registration array has to be terminated with an empty structure, or one with the index field set to zero!
Returns
0 on success, else non-zero.
Parameters
domainDomain.
pdo_entry_regsArray of PDO registrations.

Definition at line 398 of file domain.c.

◆ ecrt_domain_size()

size_t ecrt_domain_size ( const ec_domain_t domain)

Returns the current size of the domain's process data.

Returns
Size of the process data image, or a negative error code.
Parameters
domainDomain.

Definition at line 427 of file domain.c.

◆ ecrt_domain_external_memory()

void ecrt_domain_external_memory ( ec_domain_t domain,
uint8_t *  memory 
)

Provide external memory to store the domain's process data.

Call this after all PDO entries have been registered and before activating the master.

The size of the allocated memory must be at least ecrt_domain_size(), after all PDO entries have been registered.

This method has to be called in non-realtime context before ecrt_master_activate().

Parameters
domainDomain.
memoryAddress of the memory to store the process data in.

Definition at line 434 of file domain.c.

◆ ecrt_domain_data()

uint8_t* ecrt_domain_data ( ec_domain_t domain)

Returns the domain's process data.

  • In kernel context: If external memory was provided with ecrt_domain_external_memory(), the returned pointer will contain the address of that memory. Otherwise it will point to the internally allocated memory. In the latter case, this method may not be called before ecrt_master_activate().
  • In userspace context: This method has to be called after ecrt_master_activate() to get the mapped domain process data memory.
Returns
Pointer to the process data memory.
Parameters
domainDomain.

Definition at line 451 of file domain.c.

◆ ecrt_domain_process()

void ecrt_domain_process ( ec_domain_t domain)

Determines the states of the domain's datagrams.

Evaluates the working counters of the received datagrams and outputs statistics, if necessary. This must be called after ecrt_master_receive() is expected to receive the domain datagrams in order to make ecrt_domain_state() return the result of the last process data exchange.

Parameters
domainDomain.

Definition at line 458 of file domain.c.

◆ ecrt_domain_queue()

void ecrt_domain_queue ( ec_domain_t domain)

(Re-)queues all domain datagrams in the master's datagram queue.

Call this function to mark the domain's datagrams for exchanging at the next call of ecrt_master_send().

Parameters
domainDomain.

Definition at line 648 of file domain.c.

◆ ecrt_domain_state()

void ecrt_domain_state ( const ec_domain_t domain,
ec_domain_state_t state 
)

Reads the state of a domain.

Stores the domain state in the given state structure.

Using this method, the process data exchange can be monitored in realtime.

Parameters
domainDomain.
statePointer to a state object to store the information.

Definition at line 678 of file domain.c.

◆ ecrt_sdo_request_index()

void ecrt_sdo_request_index ( ec_sdo_request_t req,
uint16_t  index,
uint8_t  subindex 
)

Set the SDO index and subindex.

Attention
If the SDO index and/or subindex is changed while ecrt_sdo_request_state() returns EC_REQUEST_BUSY, this may lead to unexpected results.
Parameters
reqSDO request.
indexSDO index.
subindexSDO subindex.

Definition at line 187 of file sdo_request.c.

◆ ecrt_sdo_request_timeout()

void ecrt_sdo_request_timeout ( ec_sdo_request_t req,
uint32_t  timeout 
)

Set the timeout for an SDO request.

If the request cannot be processed in the specified time, if will be marked as failed.

The timeout is permanently stored in the request object and is valid until the next call of this method.

Parameters
reqSDO request.
timeoutTimeout in milliseconds. Zero means no timeout.

Definition at line 196 of file sdo_request.c.

◆ ecrt_sdo_request_data()

uint8_t* ecrt_sdo_request_data ( ec_sdo_request_t req)

Access to the SDO request's data.

This function returns a pointer to the request's internal SDO data memory.

Attention
The return value can be invalid during a read operation, because the internal SDO data memory could be re-allocated if the read SDO data do not fit inside.
Returns
Pointer to the internal SDO data memory.
Parameters
reqSDO request.

Definition at line 203 of file sdo_request.c.

◆ ecrt_sdo_request_data_size()

size_t ecrt_sdo_request_data_size ( const ec_sdo_request_t req)

Returns the current SDO data size.

When the SDO request is created, the data size is set to the size of the reserved memory. After a read operation the size is set to the size of the read data. The size is not modified in any other situation.

Returns
SDO data size in bytes.
Parameters
reqSDO request.

Definition at line 210 of file sdo_request.c.

◆ ecrt_sdo_request_state()

ec_request_state_t ecrt_sdo_request_state ( const ec_sdo_request_t req)

Get the current state of the SDO request.

Returns
Request state.
Parameters
reqSDO request.

Definition at line 217 of file sdo_request.c.

◆ ecrt_sdo_request_write()

void ecrt_sdo_request_write ( ec_sdo_request_t req)

Schedule an SDO write operation.

Attention
This method may not be called while ecrt_sdo_request_state() returns EC_REQUEST_BUSY.
Parameters
reqSDO request.

Definition at line 235 of file sdo_request.c.

◆ ecrt_sdo_request_read()

void ecrt_sdo_request_read ( ec_sdo_request_t req)

Schedule an SDO read operation.

Attention
This method may not be called while ecrt_sdo_request_state() returns EC_REQUEST_BUSY.
After calling this function, the return value of ecrt_sdo_request_data() must be considered as invalid while ecrt_sdo_request_state() returns EC_REQUEST_BUSY.
Parameters
reqSDO request.

Definition at line 224 of file sdo_request.c.

◆ ecrt_soe_request_idn()

void ecrt_soe_request_idn ( ec_soe_request_t req,
uint8_t  drive_no,
uint16_t  idn 
)

Set the request's drive and Sercos ID numbers.

Attention
If the drive number and/or IDN is changed while ecrt_soe_request_state() returns EC_REQUEST_BUSY, this may lead to unexpected results.
Parameters
reqIDN request.
drive_noSDO index.
idnSoE IDN.

Definition at line 272 of file soe_request.c.

◆ ecrt_soe_request_timeout()

void ecrt_soe_request_timeout ( ec_soe_request_t req,
uint32_t  timeout 
)

Set the timeout for an SoE request.

If the request cannot be processed in the specified time, if will be marked as failed.

The timeout is permanently stored in the request object and is valid until the next call of this method.

Parameters
reqSoE request.
timeoutTimeout in milliseconds. Zero means no timeout.

Definition at line 281 of file soe_request.c.

◆ ecrt_soe_request_data()

uint8_t* ecrt_soe_request_data ( ec_soe_request_t req)

Access to the SoE request's data.

This function returns a pointer to the request's internal IDN data memory.

Attention
The return value can be invalidated during a read operation, because the internal IDN data memory could be re-allocated if the read IDN data do not fit inside.
Returns
Pointer to the internal IDN data memory.
Parameters
reqSoE request.

Definition at line 288 of file soe_request.c.

◆ ecrt_soe_request_data_size()

size_t ecrt_soe_request_data_size ( const ec_soe_request_t req)

Returns the current IDN data size.

When the SoE request is created, the data size is set to the size of the reserved memory. After a read operation the size is set to the size of the read data. The size is not modified in any other situation.

Returns
IDN data size in bytes.
Parameters
reqSoE request.

Definition at line 295 of file soe_request.c.

◆ ecrt_soe_request_state()

ec_request_state_t ecrt_soe_request_state ( ec_soe_request_t req)

Get the current state of the SoE request.

Returns
Request state.
Parameters
reqSoE request.

Definition at line 302 of file soe_request.c.

◆ ecrt_soe_request_write()

void ecrt_soe_request_write ( ec_soe_request_t req)

Schedule an SoE IDN write operation.

Attention
This method may not be called while ecrt_soe_request_state() returns EC_REQUEST_BUSY.
Parameters
reqSoE request.

Definition at line 316 of file soe_request.c.

◆ ecrt_soe_request_read()

void ecrt_soe_request_read ( ec_soe_request_t req)

Schedule an SoE IDN read operation.

Attention
This method may not be called while ecrt_soe_request_state() returns EC_REQUEST_BUSY.
After calling this function, the return value of ecrt_soe_request_data() must be considered as invalid while ecrt_soe_request_state() returns EC_REQUEST_BUSY.
Parameters
reqSoE request.

Definition at line 309 of file soe_request.c.

◆ ecrt_voe_handler_send_header()

void ecrt_voe_handler_send_header ( ec_voe_handler_t voe,
uint32_t  vendor_id,
uint16_t  vendor_type 
)

Sets the VoE header for future send operations.

A VoE message shall contain a 4-byte vendor ID, followed by a 2-byte vendor type at as header. These numbers can be set with this function. The values are valid and will be used for future send operations until the next call of this method.

Parameters
voeVoE handler.
vendor_idVendor ID.
vendor_typeVendor-specific type.

Definition at line 123 of file voe_handler.c.

◆ ecrt_voe_handler_received_header()

void ecrt_voe_handler_received_header ( const ec_voe_handler_t voe,
uint32_t *  vendor_id,
uint16_t *  vendor_type 
)

Reads the header data of a received VoE message.

This method can be used to get the received VoE header information after a read operation has succeeded.

The header information is stored at the memory given by the pointer parameters.

Parameters
voeVoE handler.
vendor_idVendor ID.
vendor_typeVendor-specific type.

Definition at line 132 of file voe_handler.c.

◆ ecrt_voe_handler_data()

uint8_t* ecrt_voe_handler_data ( ec_voe_handler_t voe)

Access to the VoE handler's data.

This function returns a pointer to the VoE handler's internal memory, that points to the actual VoE data right after the VoE header (see ecrt_voe_handler_send_header()).

  • After a read operation was successful, the memory contains the received data. The size of the received data can be determined via ecrt_voe_handler_data_size().
  • Before a write operation is triggered, the data have to be written to the internal memory. Be sure, that the data fit into the memory. The reserved memory size is a parameter of ecrt_slave_config_create_voe_handler().
Attention
The returned pointer is not necessarily persistent: After a read operation, the internal memory may have been reallocated. This can be avoided by reserving enough memory via the size parameter of ecrt_slave_config_create_voe_handler().
Returns
Pointer to the internal memory.
Parameters
voeVoE handler.

Definition at line 145 of file voe_handler.c.

◆ ecrt_voe_handler_data_size()

size_t ecrt_voe_handler_data_size ( const ec_voe_handler_t voe)

Returns the current data size.

The data size is the size of the VoE data without the header (see ecrt_voe_handler_send_header()).

When the VoE handler is created, the data size is set to the size of the reserved memory. At a write operation, the data size is set to the number of bytes to write. After a read operation the size is set to the size of the read data. The size is not modified in any other situation.

Returns
Data size in bytes.
Parameters
voeVoE handler.

Definition at line 152 of file voe_handler.c.

◆ ecrt_voe_handler_write()

void ecrt_voe_handler_write ( ec_voe_handler_t voe,
size_t  size 
)

Start a VoE write operation.

After this function has been called, the ecrt_voe_handler_execute() method must be called in every bus cycle as long as it returns EC_REQUEST_BUSY. No other operation may be started while the handler is busy.

Parameters
voeVoE handler.
sizeNumber of bytes to write (without the VoE header).

Definition at line 177 of file voe_handler.c.

◆ ecrt_voe_handler_read()

void ecrt_voe_handler_read ( ec_voe_handler_t voe)

Start a VoE read operation.

After this function has been called, the ecrt_voe_handler_execute() method must be called in every bus cycle as long as it returns EC_REQUEST_BUSY. No other operation may be started while the handler is busy.

The state machine queries the slave's send mailbox for new data to be send to the master. If no data appear within the EC_VOE_RESPONSE_TIMEOUT (defined in master/voe_handler.c), the operation fails.

On success, the size of the read data can be determined via ecrt_voe_handler_data_size(), while the VoE header of the received data can be retrieved with ecrt_voe_handler_received_header().

Parameters
voeVoE handler.

Definition at line 159 of file voe_handler.c.

◆ ecrt_voe_handler_read_nosync()

void ecrt_voe_handler_read_nosync ( ec_voe_handler_t voe)

Start a VoE read operation without querying the sync manager status.

After this function has been called, the ecrt_voe_handler_execute() method must be called in every bus cycle as long as it returns EC_REQUEST_BUSY. No other operation may be started while the handler is busy.

The state machine queries the slave by sending an empty mailbox. The slave fills its data to the master in this mailbox. If no data appear within the EC_VOE_RESPONSE_TIMEOUT (defined in master/voe_handler.c), the operation fails.

On success, the size of the read data can be determined via ecrt_voe_handler_data_size(), while the VoE header of the received data can be retrieved with ecrt_voe_handler_received_header().

Parameters
voeVoE handler.

Definition at line 168 of file voe_handler.c.

◆ ecrt_voe_handler_execute()

ec_request_state_t ecrt_voe_handler_execute ( ec_voe_handler_t voe)

Execute the handler.

This method executes the VoE handler. It has to be called in every bus cycle as long as it returns EC_REQUEST_BUSY.

Returns
Handler state.
Parameters
voeVoE handler.

Definition at line 187 of file voe_handler.c.

◆ ecrt_reg_request_data()

uint8_t* ecrt_reg_request_data ( ec_reg_request_t req)

Access to the register request's data.

This function returns a pointer to the request's internal memory.

  • After a read operation was successful, integer data can be evaluated using the EC_READ_*() macros as usual. Example:
    uint16_t value = EC_READ_U16(ecrt_reg_request_data(reg_request)));
  • If a write operation shall be triggered, the data have to be written to the internal memory. Use the EC_WRITE_*() macros, if you are writing integer data. Be sure, that the data fit into the memory. The memory size is a parameter of ecrt_slave_config_create_reg_request().
    EC_WRITE_U16(ecrt_reg_request_data(reg_request), 0xFFFF);
Returns
Pointer to the internal memory.
Parameters
reqRegister request.

Definition at line 86 of file reg_request.c.

◆ ecrt_reg_request_state()

ec_request_state_t ecrt_reg_request_state ( const ec_reg_request_t req)

Get the current state of the register request.

Returns
Request state.
Parameters
reqRegister request.

Definition at line 93 of file reg_request.c.

◆ ecrt_reg_request_write()

void ecrt_reg_request_write ( ec_reg_request_t req,
uint16_t  address,
size_t  size 
)

Schedule an register write operation.

Attention
This method may not be called while ecrt_reg_request_state() returns EC_REQUEST_BUSY.
The size parameter is truncated to the size given at request creation.
Parameters
reqRegister request.
addressRegister address.
sizeSize to write.

Definition at line 100 of file reg_request.c.

◆ ecrt_reg_request_read()

void ecrt_reg_request_read ( ec_reg_request_t req,
uint16_t  address,
size_t  size 
)

Schedule a register read operation.

Attention
This method may not be called while ecrt_reg_request_state() returns EC_REQUEST_BUSY.
The size parameter is truncated to the size given at request creation.
Parameters
reqRegister request.
addressRegister address.
sizeSize to write.

Definition at line 111 of file reg_request.c.