Home » EtherCAT

EtherCAT MainDevice/Master

Robert Burger

Open-Source EtherCAT MainDevice (fka master) library

Katze

EtherCAT is a high determinisic industrial fieldbus protocol developed by Beckhoff Automation GmbH. An EtherCAT MainDevice (fka master) enables configuration and cyclic/realtime communication with connected SubDevices (fka slaves) library. This library is used to build a deterministic fieldbus network with EtherCAT components.

Legal notices

This software was developed and made available to the public by the Institute of Robotics and Mechatronics of the German Aerospace Center (DLR).

Please note that the use of the EtherCAT technology, the EtherCAT brand name and the EtherCAT logo is only permitted if the property rights of Beckhoff Automation GmbH are observed. For further information please contact Beckhoff Automation GmbH & Co. KG, Hülshorstweg 20, D-33415 Verl, Germany (www.beckhoff.com) or the EtherCAT Technology Group, Ostendstraße 196, D-90482 Nuremberg, Germany (ETG, www.ethercat.org).

Source code

The source code is available at GitHub and released under LGPL-v3. You will find releases and build instructions there. Head over to libethercat on GitHub

Creating an example master program

First step would be to create a task for cyclic process data exchange. This should be run with an high enough priority on a realtime-opering-system of your choice (e.g. Linux PREEMPT-RT).

static osal_void_t* cyclic_task(osal_void_t* param) {
    ec_t *pec = (ec_t *)param;
    osal_uint64_t abs_timeout = osal_timer_gettime_nsec();

    while (1) {
        abs_timeout += cycle_rate;
        (void)osal_sleep_until_nsec(abs_timeout);

        // execute one EtherCAT cycle
        ec_send_distributed_clocks_sync(pec);
        ec_send_process_data(pec);

        // transmit cyclic packets (and also acyclic if there are any)
        hw_tx(&pec->hw);
    }
}

Create an EtherCAT master like this.

int main(int argc, char **argv) {
    int ret = ec_open(&ec, "eth1", 60, 0x8, 1);
    if (ret != EC_OK) {
        return -1;
    }

    ec_set_state(&ec, EC_STATE_INIT);
    ec_set_state(&ec, EC_STATE_PREOP);

    osal_task_t cyclic_task_hdl;
    osal_task_attr_t cyclic_task_attr = { "cyclic_task", OSAL_SCHED_POLICY_FIFO, 60, 0x08 };
    osal_task_create(&cyclic_task_hdl, &cyclic_task_attr, cyclic_task, &ec);

    ec_set_state(&ec, EC_STATE_SAFEOP);
    ec_set_state(&ec, EC_STATE_OP);

    while (1) { /* do your stuff here */ }

    return 0;
}

Efficient frame scheduling

With the principle of an efficient frame scheduling libethercat ensures that different kind of EtherCAT can be mixed together without disturbing the realtime requirement.

In the above example the only program to call hw_tx is the cyclic_task. This will first send all high priority cyclic frames/datagrams and appends other low priority frames/datagrams (e.g. mailbox traffic) afterwards. Additional low priority frames/datagrams may also be scheduled in the gap between two high priority cyclic frames.

Mailbox

libethercat supports all standard mailbox protocol defined by the ETG. A program may call all mailbox protocol functions at any time. They are usually called asynchronously in any EtherCAT subdevice state (except INIT) and will not disturb the cyclic/realtime exchange of the process data.

CANOpen-Over-EtherCAT (CoE)

libethercat fully supports the CoE mailbox protocol. The CoE mailbox is mostly used to configure subdevices with an CANOpen compliant dictionary. The elements in that dictionary are called Service-Data-Objects (SDOs). SDOs are identified by an index and if it contains more than one entry by an additional subindex.

  • SDO read » Reading values stored in one SDO.
  • SDO write » Writing a value to one SDO.
  • SDO desc read » Retreave the description of a SDO.
  • SDO entry desc read » Retreaves the description of an entry (subindex) of a SDO.
  • SDO odlist read » Reads out all supported objects (indices) of the CoE dictionary.
  • Emergencies » Subdevices may signal an emergency to the maindevice. The emergency is automatically retreaved and stored in an internally emergency queue.

File-Over-EtherCAT (FoE)

FoE is a TFTP like file transfer mechanism. This is usually used to update the firmware of subdevices or to retreave debug data from devics. libethercat supports reading and writing files.

Ethernet-Over-EtherCAT (EoE)

Standard ethernet can also be tunnelled through EtherCAT. Therefore the subdevices will get an IP-address and the master will open a virtual network device in the operating system (currently only linux, tap device). EoE traffic is then automatically scheduled.

Servodrive-Over-EtherCAT (SoE)

Servodrive (fka SERCOS-1/2) is also supported. This can be used (and is tested with) e.g. Beckhoff AX5xxx motor amplifiers.

Distributed Clocks

libethercat supports distributed clock with diffent reference clock modes. All subdevices will synchronize to that reference clock.

  • ref_clock » Use first subdevice supporing distributed clocks as reference clock.
  • master_as_ref_clok » Use EtherCAT master’s clock as reference clock.

Network device access

  • raw socket » The most common way sending ethernet frames in Linux is opening a raw network socket (SOCK_RAW). Therefor the program must either be run as root or with the capability flag CAP_NET_RAW
  • raw_socket_mmaped » Like above but don’t use read/write to provide frame buffers to kernel and use mmaped buffers directly from kernel.
  • file » Most performant/determinstic interface to send/receive frames with network hardware. Requires hacked linux network driver. Can also be used without interrupts to avoid context switches.
  • pikeos » Special pikeos hardware access.

Links