Introduction
Over the last 6 months I've been working on adding Ethercat to our PCBs as the communication protocol between the distributed control system for uBot-7 and the central PC. When I started, I was a little overwhelmed by the size and scope of the documentation provided by Beckhoff (which covers everything in the highest level of detail) and I was unable to find any outside guide that offered a bare bones approach to Ethercat slave development. Since Beckhoff's software only supports windows machines at the moment, information of developing with a Linux based master was extremely sparse. Therefore, I've put together a little resource guide of things I would have liked to have known when I started out. This guide is aimed at getting you through the processes from complete ignorance to finished PCB as quickly as possible.
Since my project involved motor control using a PIC32 this guide is biased towards that application. I've put most links to relevant documentation at the bottom of the guide.
Registration
The first thing you need to do before you start developing with Ethercat is become a member of the ETG group [link] and after that you will need to obtain a vendor ID [link]. Fortunately, both of these are free but will require signing a license agreement. It took me about a week to go through this process, although some part of that is because I had difficulty obtaining a university logo in the file format they requested (you must provide a logo).
SSC
The Slave Stack Code (SSC) tool is a free tool that Beckhoff provides to registered vendors (meaning you have a vendor ID). The tool comes with its own application note documentation and it is critical that you read and understand every parameter before generating the sample code.
A word of warning: don't trust anything inside of SSC to behave properly. As an example, I found a SWAP define which was written as follows:
#define SWAP(x) (x)
So yeah, make sure you check all the methods before relying on them.
ESI FILE
The Ethercat Slave Information file is an XML document that specifices the slave behavior. It is the most important part of your slave and you should start with that before looking at any masters. Beckhoff provides a number of ESI starting examples in the Twincat 3 installation but the SSC will generate an ESI file for you based on the application configuration. Using the CiA402 default will give you an ESI file that already has the CiA402 profile built in if you are doing motor control.
While the file that the SCC generates is almost certainly correct, I would go over it line by line against the ESI documentation file to make sure everything configured is as you expect. Not that the SSC tool does not set the ConfigData tag which expects a hex code that must be computed elsewhere. This tag defines the hardware presets such as the PDI type. Luckily, Beckhoff supplies a nice Excel tool (ET1100 Configuration and Pinout) that will easily generate that part for you. Why this isn't part of the SSC tool is a mystery to me.
I provide my barebones ESI file for the Beckhoff FB1111-0141 here.
Twincat 3
Twincat 3 is Beckhoff's master combined with their development environment which is operated through a Visual Studio extension. Even if you are not planning on using Windows in the final product, I would recommend starting development using Twincat 3 for two main reasons. The first is that while the documentation for Twincat 3 is awful, you can at least call Beckhoff support if you are blocked and I've found them to be helpful. They will not answer any questions that have anything to do with Linux masters (I've tried). The second reason is that the inspection tools that Twincat 3 offers into the slave are the best I've found, including the ability to write the SII binary to the EEPROM directly from the ESI file which I've not discovered in any Linux master.
Linux Masters
There are two Linux masters that I am aware of at the moment.
Etherlab - Complex to setup. Documentation is poor. Highly configurable / flexible. Can run real-time through a kernel module or in user space. More suitable for professional development. Open Source.
SOEM - Simple to setup and get started. Documentation is okay. Simple and straight forward to understand. Can only run in user space. Active development is questionable. Open Source.
Personally, I liked Etherlab a bit more than SOEM. While I found SOEM a much more pleasant experience, Etherlab offers a wider, more developed tool set and gives you more flexibility once you pay the upfront price of deciphering the documentation.
The bare bones Etherlab master file I use with the ESI file above is here.
PCB Development
Along with the Hardware datasheet, Beckhoff supplies a ESC comparison document and a PHY selection guide which can be found as application notes on the download page [link]. I was able to get an example schematic from a Beckhoff representative directly but I do not believe they provide anything like that from their website. The most important thing you will need is the Excel sheet (ET1100 Configuration and Pinout) which will provide the proper pin out for your configuration.
I used the following parts for the Ethercat component of my board:
- ET1100
- Micrel Inc KSZ8081MLXCA [link]
- Rohm Semiconductor BR24T16F-WE2 [link]
- Pulse Electronics Corporation J1026F01PNL [link]
Documentation
All ESC documentation can be found the on the Beckhoff downloads page.
The ESI file documentation is found on the ETG website.
The CiA402 profile specification can be found here.
The Slave Implementation Guide is a kind of unifying document that attempts to put all of the beckhoff documentation together at a high level. It can be found here.