libethercat - an embeddable realtime EtherCAT-master library
Communicate with EtherCAT slaves attached to a Network interface.
Loading...
Searching...
No Matches
EC Master

Data Structures

struct  ec_pd_group
 process data group structure More...
 
struct  ec
 ethercat master structure More...
 

Macros

#define EC_SHORT_TIMEOUT_MBX   (10000000)
 Short timeout value in [ns].
 
#define EC_DEFAULT_TIMEOUT_MBX   (1000000000)
 Default timeout value in [ns].
 
#define EC_DEFAULT_DELAY   (2000000)
 Default delay in [ns].
 
#define ec_log(lvl, pre, format, ...)    _ec_log(pec, (lvl), (pre), (format), ##__VA_ARGS__)
 
#define ec_group_will_be_sent(pec, group)   (int)((((pec)->pd_groups[(group)].divisor_cnt+1) % (pec)->pd_groups[(group)].divisor) == 0)
 Group datagram will be send on next time step.
 
#define ec_group_was_sent(pec, group)   (int)((pec)->pd_groups[(group)].divisor_cnt == 0)
 Group datagram was sent.
 
#define ec_to_adr(ado, adp)    ((osal_uint32_t)(adp) << 16u) | ((ado) & 0xFFFFu)
 Macro for EtherCAT address generation.
 
#define ec_brd(pec, ado, data, datalen, wkc)
 Perform a broadcast read (BRD).
 
#define ec_bwr(pec, ado, data, datalen, wkc)
 Perform a broadcast write (BWR).
 
#define ec_brw(pec, ado, data, datalen, wkc)
 Perform a broadcast read/write (BRW).
 
#define ec_aprd(pec, adp, ado, data, datalen, wkc)
 Perform a positional physical read (APRD)
 
#define ec_apwr(pec, adp, ado, data, datalen, wkc)
 Perform a positional physical write (APWR)
 
#define ec_aprw(pec, adp, ado, data, datalen, wkc)
 Perform a positional physical read/write (APRW)
 
#define ec_fprd(pec, adp, ado, data, datalen, wkc)
 Perform a configured-address physical read (FPRD)
 
#define ec_fpwr(pec, adp, ado, data, datalen, wkc)
 Perform a configured-address physical write (FPWR)
 
#define ec_fprw(pec, adp, ado, data, datalen, wkc)
 Perform a configured-address physical read/write (FPRW)
 
#define ec_frmw(pec, adp, ado, data, datalen, wkc)
 Perform a configured-address physical read/multiple-write (FPMW)
 
#define check_ret(fcn, ...)
 Macro that checks return value and prints message in error case.
 
#define check_ec_bwr(...)   check_ret(ec_bwr, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_brd(...)   check_ret(ec_brd, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_brw(...)   check_ret(ec_brw, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_apwr(...)   check_ret(ec_apwr, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_aprd(...)   check_ret(ec_aprd, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_aprw(...)   check_ret(ec_aprw, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_fpwr(...)   check_ret(ec_fpwr, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_fprd(...)   check_ret(ec_fprd, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_fprw(...)   check_ret(ec_fprw, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 
#define check_ec_frmw(...)   check_ret(ec_frmw, __VA_ARGS__)
 Macro that checks return value and prints message in error case.
 

Typedefs

typedef struct ec_slave ec_slave_t
 
typedef struct ec_pd_group ec_pd_group_t
 process data group structure
 
typedef struct ec ec_t
 ethercat master structure
 

Functions

void _ec_log (ec_t *pec, int lvl, const osal_char_t *pre, const osal_char_t *format,...)
 EtherCAT logging function.
 
int ec_open (ec_t *pec, struct hw_common *phw, int eeprom_log)
 Open ethercat master.
 
int ec_close (ec_t *pec)
 Closes ethercat master.
 
int ec_configure_tun (ec_t *pec, osal_uint8_t ip_address[4])
 Configures tun device of EtherCAT master, used for EoE slaves.
 
void ec_configure_dc (ec_t *pec, osal_uint64_t timer, ec_dc_mode_t mode, void(*user_cb)(void *arg, int num), void *user_cb_arg)
 Configures distributed clocks settings on EtherCAT master.
 
int ec_create_pd_groups (ec_t *pec, osal_uint32_t pd_group_cnt)
 Create process data groups.
 
void ec_configure_pd_group (ec_t *pec, osal_uint16_t group, int clock_divisor, void(*user_cb)(void *arg, int num), void *user_cb_arg)
 Configure process data group settings.
 
int ec_destroy_pd_groups (ec_t *pec)
 Destroy process data groups.
 
int ec_transceive (ec_t *pec, osal_uint8_t cmd, osal_uint32_t adr, osal_uint8_t *data, osal_size_t datalen, osal_uint16_t *wkc)
 Syncronous ethercat read/write.
 
int ec_transmit_no_reply (ec_t *pec, osal_uint8_t cmd, osal_uint32_t adr, osal_uint8_t *data, osal_size_t datalen)
 Asyncronous ethercat read/write, answer don't care.
 
int ec_set_state (ec_t *pec, ec_state_t state)
 Set state on ethercat bus.
 
int ec_send_process_data (ec_t *pec)
 send process data with logical commands
 
int ec_send_distributed_clocks_sync (ec_t *pec)
 Send distributed clocks sync datagram.
 
int ec_send_distributed_clocks_sync_with_rtc (ec_t *pec, osal_uint64_t act_rtc_time)
 Send distributed clock sync datagram.
 
int ec_send_brd_ec_state (ec_t *pec)
 Send broadcast read to ec state.
 
int ec_get_slave_count (ec_t *pec)
 Return current slave count.
 

Detailed Description

This modules contains main EtherCAT master functions.

Macro Definition Documentation

◆ check_ret

#define check_ret (   fcn,
  ... 
)
Value:
{ \
if (fcn(__VA_ARGS__) != EC_OK) { \
ec_log(1, __func__, "" #fcn "(" #__VA_ARGS__ ") failed!\n"); \
} }
#define EC_OK
All OK.
Definition error_codes.h:54

Macro that checks return value and prints message in error case.

◆ ec_aprd

#define ec_aprd (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_APRD, ((osal_uint32_t)(ado) << 16u) | \
(*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
int ec_transceive(ec_t *pec, osal_uint8_t cmd, osal_uint32_t adr, osal_uint8_t *data, osal_size_t datalen, osal_uint16_t *wkc)
Syncronous ethercat read/write.
@ EC_CMD_APRD
auto increment read
Definition regs.h:57

Perform a positional physical read (APRD)

◆ ec_aprw

#define ec_aprw (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_APRW, ((osal_uint32_t)(ado) << 16u) | \
(*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_APRW
auto increment read write
Definition regs.h:59

Perform a positional physical read/write (APRW)

◆ ec_apwr

#define ec_apwr (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_APWR, ((osal_uint32_t)(ado) << 16u) | \
(*(osal_uint16_t *)&(adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_APWR
auto increment write
Definition regs.h:58

Perform a positional physical write (APWR)

◆ ec_brd

#define ec_brd (   pec,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_BRD, ((osal_uint32_t)(ado) << 16u), \
(osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_BRD
broadcast read
Definition regs.h:63

Perform a broadcast read (BRD).

◆ ec_brw

#define ec_brw (   pec,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_BRW, ((osal_uint32_t)(ado) << 16u), \
(osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_BRW
broadcast read write
Definition regs.h:65

Perform a broadcast read/write (BRW).

◆ ec_bwr

#define ec_bwr (   pec,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_BWR, ((osal_uint32_t)(ado) << 16u), \
(osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_BWR
broaddcast write
Definition regs.h:64

Perform a broadcast write (BWR).

◆ ec_fprd

#define ec_fprd (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_FPRD, ((osal_uint32_t)(ado) << 16lu) | \
(osal_uint32_t)((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_FPRD
configured address read
Definition regs.h:60

Perform a configured-address physical read (FPRD)

◆ ec_fprw

#define ec_fprw (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_FPRW, ((osal_uint32_t)(ado) << 16u) | \
((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_FPRW
configured address read write
Definition regs.h:62

Perform a configured-address physical read/write (FPRW)

◆ ec_fpwr

#define ec_fpwr (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_FPWR, ((osal_uint32_t)(ado) << 16u) | \
((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_FPWR
configured address write
Definition regs.h:61

Perform a configured-address physical write (FPWR)

◆ ec_frmw

#define ec_frmw (   pec,
  adp,
  ado,
  data,
  datalen,
  wkc 
)
Value:
ec_transceive((pec), EC_CMD_FRMW, ((osal_uint32_t)(ado) << 16u) | \
((adp) & 0xFFFFu), (osal_uint8_t *)(data), (datalen), (wkc))
@ EC_CMD_FRMW
configured read mulitple write
Definition regs.h:70

Perform a configured-address physical read/multiple-write (FPMW)

Function Documentation

◆ _ec_log()

void _ec_log ( ec_t pec,
int  lvl,
const osal_char_t *  pre,
const osal_char_t *  format,
  ... 
)

EtherCAT logging function.

This function does all EtherCAT logging.

Parameters
[in]lvlLog level of message.
[in]preString prepended to message.
[in]formatString format.
[in]...String format arguments.

◆ ec_close()

int ec_close ( ec_t pec)

Closes ethercat master.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
Returns
0 on success

◆ ec_configure_dc()

void ec_configure_dc ( ec_t pec,
osal_uint64_t  timer,
ec_dc_mode_t  mode,
void(*)(void *arg, int num)  user_cb,
void *  user_cb_arg 
)

Configures distributed clocks settings on EtherCAT master.

Parameters
[in]pecPointer to EtherCAT master structure.
[in]timerFixed expected cyclic timer value.
[in]modeDistributed clock operating mode.
[in]user_cbCallback when DC datagram returned, maybe NULL.
[in]user_cb_argArgument passed to 'user_cb', maybe NULL.

◆ ec_configure_pd_group()

void ec_configure_pd_group ( ec_t pec,
osal_uint16_t  group,
int  clock_divisor,
void(*)(void *arg, int num)  user_cb,
void *  user_cb_arg 
)

Configure process data group settings.

Parameters
[in]pecPointer to EtherCAT master structure.
[in]groupNumber of group to configure.
[in]clock_divisorSend group datagram every 'clock_divisor' ticks.
[in]user_cbCallback when group datagram returned, maybe NULL.
[in]user_cb_argArgument passed to 'user_cb', maybe NULL.

◆ ec_configure_tun()

int ec_configure_tun ( ec_t pec,
osal_uint8_t  ip_address[4] 
)

Configures tun device of EtherCAT master, used for EoE slaves.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
[in]ip_addressIP address to be set for tun device.
Returns
0 on success

◆ ec_create_pd_groups()

int ec_create_pd_groups ( ec_t pec,
osal_uint32_t  pd_group_cnt 
)

Create process data groups.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
[in]pd_group_cntNumber of groups to create.
Returns
0 on success

◆ ec_destroy_pd_groups()

int ec_destroy_pd_groups ( ec_t pec)

Destroy process data groups.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
Returns
0 on success

◆ ec_get_slave_count()

int ec_get_slave_count ( ec_t pec)

Return current slave count.

Parameters
[in]pecPointer to ethercat master structure.
Returns
cnt current slave count.

◆ ec_open()

int ec_open ( ec_t pec,
struct hw_common phw,
int  eeprom_log 
)

Open ethercat master.

This function is used as initial call to create the EtherCAT master instance. It configures all needed options with default values. A packet receive thread is spawned with given priority (prio) and affinity (affinity). Ensure that they meet your realtime requirements.

After the successfull completion a switch to EC_STATE_INIT will perform a initial scan of the bus.

Parameters
[out]pecEthercat master instance pointer.
[in]phwEthercat master network device access.
[in]eeprom_logLog eeprom to stdout.
Returns
0 on succes, otherwise error code

◆ ec_send_brd_ec_state()

int ec_send_brd_ec_state ( ec_t pec)

Send broadcast read to ec state.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
Returns
0 on success

◆ ec_send_distributed_clocks_sync()

int ec_send_distributed_clocks_sync ( ec_t pec)

Send distributed clocks sync datagram.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
Returns
0 on success

◆ ec_send_distributed_clocks_sync_with_rtc()

int ec_send_distributed_clocks_sync_with_rtc ( ec_t pec,
osal_uint64_t  act_rtc_time 
)

Send distributed clock sync datagram.

Parameters
pecPointer to ethercat master structure, which you got from ec_open.
act_rtc_timeCurrent real-time clock value. If 0, the time of osal_timer_gettime_nsec() will be used. Otherwise the supplied time is used.
Returns
0 on success

◆ ec_send_process_data()

int ec_send_process_data ( ec_t pec)

send process data with logical commands

Parameters
[in]pecPointer to EtherCAT master struct.
Returns
EC_OK on success

◆ ec_set_state()

int ec_set_state ( ec_t pec,
ec_state_t  state 
)

Set state on ethercat bus.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
[in]stateNew ethercat state.
Returns
Reached master state.

◆ ec_transceive()

int ec_transceive ( ec_t pec,
osal_uint8_t  cmd,
osal_uint32_t  adr,
osal_uint8_t *  data,
osal_size_t  datalen,
osal_uint16_t *  wkc 
)

Syncronous ethercat read/write.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
[in]cmdEtherCAT command.
[in]adr32-bit address of slave.
[in]dataData buffer to read/write .
[in]datalenLength of data.
[out]wkcReturn value for working counter.
Returns
0 on succes, otherwise error code

◆ ec_transmit_no_reply()

int ec_transmit_no_reply ( ec_t pec,
osal_uint8_t  cmd,
osal_uint32_t  adr,
osal_uint8_t *  data,
osal_size_t  datalen 
)

Asyncronous ethercat read/write, answer don't care.

Parameters
[in]pecPointer to ethercat master structure, which you got from ec_open.
[in]cmdEthercat command.
[in]adr32-bit address of slave.
[in]dataData buffer to read/write.
[in]datalenLength of data.
Returns
0 on succes, otherwise error code