[etherlab-dev] EtherCAT Mailbox Gateway Server patch

Graeme Foot Graeme.Foot at touchcut.com
Wed Sep 4 01:39:22 CEST 2019

Hi Gavin,

I have attached an updated patch for the Mailbox Gateway Server.

This fixes a problem where EoE communications get incorrectly gobbled by the Mailbox Gateway handler.  This occurred with an EL6614 EoE module which doesn't fill in the Mailbox Header station address when retrieving EoE mailbox data.


From: etherlab-dev <etherlab-dev-bounces at etherlab.org> On Behalf Of Graeme Foot
Sent: Saturday, 20 July 2019 12:58 AM
To: Gavin Lambert <gavin.lambert at tomra.com>; etherlab-dev at etherlab.org
Subject: Re: [etherlab-dev] EtherCAT Mailbox Gateway Server patch

Hi Gavin,

Thanks for the feedback.  I've updated the gap subindex's to return 0x08000020 (Data cannot be read or stored).

I've updated 0x8nnn:04 to ask the slave it's modular device profile from 0x1000:00 if the slave supports CoE protocol.  If it does not it will now return 0.  Looking at my comments I did find the 0x1000:00 value, but then forgot about it.

Have attached the updated patch.



From: Gavin Lambert <gavin.lambert at tomra.com<mailto:gavin.lambert at tomra.com>>
Sent: Friday, 19 July 2019 18:34
To: Graeme Foot; etherlab-dev at etherlab.org<mailto:etherlab-dev at etherlab.org>
Subject: RE: EtherCAT Mailbox Gateway Server patch

Sounds interesting.

To address one of your questions, standard slave behaviour is to report "subindex not existing" (0x11) only if the requested subindex is higher than the maximum subindex that exists.  When accessing a "gap" subindex for which no data is available, it reports "data cannot be read or stored" (0x18) instead.  (There's a few other variations of errors for cases where data is written when read-only, or can only be read/written in a different AL state, etc.)

Also, a slave's module profile should be readable from SDO 0x1000.  Most general-purpose modular devices will report 0x00001389 here (others will report something else, of course); it's a mandatory object for any slave that supports CoE.

And yes, I'm currently in the process of integrating and updating the patchset.  It's nearly done, but I've hit a bit of a brick wall at present where due to a recent kernel patch (which appears to be in recent versions of 4.4+) the e1000e driver fails to recover from loss of link when using a motherboard-based adapter.  Frustratingly, it's a code change outside of the e1000e driver itself which is affecting its operation - although it does appear to operate correctly when used with ec_generic.  The good news is that the igb driver appears to be unaffected.  I'm hoping to figure out a workaround before release, though if it takes much longer then I might just release it as-is.

Gavin Lambert
Senior Software Developer

[cid:image001.png at 01D56314.FE457C00]

COMPAC SORTING EQUIPMENT LTD | 4 Henderson Pl | Onehunga | Auckland 1061 | New Zealand
Switchboard: +64 96 34 00 88 | tomra.com<http://www.tomra.com>

The information contained in this communication and any attachment is confidential and may be legally privileged. It should only be read by the person(s) to whom it is addressed. If you have received this communication in error, please notify the sender and delete the communication.

From: Graeme Foot <Graeme.Foot at touchcut.com<mailto:Graeme.Foot at touchcut.com>>
Sent: Friday, 19 July 2019 17:57
To: etherlab-dev at etherlab.org<mailto:etherlab-dev at etherlab.org>
Cc: Gavin Lambert <gavin.lambert at tomra.com<mailto:gavin.lambert at tomra.com>>
Subject: EtherCAT Mailbox Gateway Server patch


I have attached a patch to implement an EtherCAT Mailbox Gateway server.  Florian you may be interested in this as it is on the EtherLab TODO list.

The server provides for UDP and up to 16 TCP connections.  The the UDP and TCP connections are not multi-threaded.

It is based on the specification:


It is designed to be used with tools such as:


Note: the TwinSAFE Loader is a new program that allows you to apply TwinSAFE programs to your TwinSAFE modules without having the modules connected to TwinCAT.  You are still required to use TwinCAT to create the safety programs.  Last I looked there was no download link for the TwinSAFE loader as it is new and Beckhoff are still deciding on licensing, but I got a copy from our local rep.

The server is built on top of the GavinL Etherlab master patchset 20171108.  It integrates into the multiple mailbox protocol patches functionality.  Mailbox datagrams from the Mailbox Gateway server are recognized due to the Mailbox Header address not matching the datagram ADP address.

The server is a user space program named "ethercat_mbg" loosly based on the "ethercat" user space tool (MBG stands for Mailbox Gateway).  The program can be run as a foreground or background task depending on whether you want to run it temporarily or as a daemon.  There is no security incorporated into the protocol so the server will give full access to the slave mailboxes while it is running.  The mailbox gateway listens on port 0x88A4 (34980) should you want to firewall the port.

The Mailbox Gateway protocol requires the EtherCAT master to provide a Master Object Dictionary as specified by ETG.5001.3 (Modular Device Profile Part 3: Fieldbus Gateway Profile Specifications), Annex A:


I have implemented all of the optional items, along with A.2.1.3 Diagnosis Data (index 0xAnnn) which is supposed to be optional but seems to be required by the TwinSAFE loader.  I'm not massively happy with the master object dictionary function (ec_master_obj_dict()) as it is handling all of the index:subindex requests in the one function.  However it shouldn't really grow unless someone wants to implement the optional items.

A few things to note:

1) Items 0x8nnn:02 and 0x8nnn:03 of the master object dictionary return 16 and 32 character fixed length strings (respectively) with the extra characters nulled out.  In theory you should be able to return the exact length of the string (as is done by slaves) but the TwinSAFE Loader program seems to require null terminated strings.  The 16 and 32 characters come from matching the returned data from TwinCAT.

2) Item 0x8nnn:04 should return the slave Modular Device Profile.  This information is not available in the slaves SII or from any of the standard SDO indexes (should the slave support SDO access).  It only seems to be available from the slaves ESI xml files which the EtherLab master does not use.  I have hardcoded the standard simple slave Modular Device Profile number of 0x1389 (5001).

3) Item 0x8nnn has a gap in the sub indexes.  At the moment if one of the unspecified sub indexes is requested (9 - 32) I am returning a Subindex does not exist error.  Does anyone know if this is correct, or whether I should return some other value?

I have only tested ethercat_mbg with the TwinSAFE_Loader --list function so far.  It correctly lists an EL6910 TwinSAFE PLC module.  It also sucessfully interacts with slave mailboxes.  I have not done any further testing with the TwinSAFE_Loader yet as I have another project I need to spend some time on.

Gavin, I'm sending this patch now as it looks like you are working on updating your patchset.  I've added this patch as an optional feature (features/mailbox-gateway) with an --enable-mbg build option defaulting to true.  If more people see it as worthwhile it might be worth adding as a base patch.


Graeme Foot

Kinetic Engineering Design Ltd.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 11438 bytes
Desc: image001.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0006.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image002.png
Type: image/png
Size: 1629 bytes
Desc: image002.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0007.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 1750 bytes
Desc: image003.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0008.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image004.png
Type: image/png
Size: 1855 bytes
Desc: image004.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0009.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image005.png
Type: image/png
Size: 1970 bytes
Desc: image005.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0010.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image006.png
Type: image/png
Size: 20278 bytes
Desc: image006.png
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0011.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-mailbox-gateway.patch
Type: application/octet-stream
Size: 136807 bytes
Desc: 0001-mailbox-gateway.patch
URL: <http://lists.etherlab.org/pipermail/etherlab-dev/attachments/20190903/ac3f78c9/attachment-0001.obj>

More information about the etherlab-dev mailing list