SOEM/doc/soem.dox

226 lines
9.2 KiB
Plaintext
Raw Normal View History

2014-11-25 16:10:29 +01:00
/**
* \mainpage Simple Open EtherCAT Master or SOEM
*
* \section start Tutorial
* For a tutorial on SOEM See tutorial.txt
*
* \section overview Overview
* SOEM is an EtherCAT master library written in c. Its purpose is to learn and
* to use. All users are invited to study the source to get an understanding
* how an EtherCAT master functions and how it interacts with EtherCAT slaves.
*
* As all applications are different SOEM tries to not impose any design architecture.
* Under Linux it can be used in generic user mode, PREEMPT_RT or Xenomai. under Windows
* it can be used as user mode program.
*
* Preconditions Linux:
* - Linux 2.6 kernel.
* - GCC compiler (others might work, just not tested).
* - One (or two if in redundant mode) 100Mb/s NIC that can connect to a RAW socket.
* - Application must run as root / kernel.
*
* Preconditions Windows:
* - Windows2000 - Windows 7 (8 not tested, might work).
* - VC compiler (others might work, just not tested).
* - One (or two if in redundant mode) 100Mb/s NIC that can connect to a RAW socket.
* - WinPcap installed.
*
* Features as of 1.1.2 :
* - Connects to a standard RAW socket.
* - Full redundancy support.
* - Recovery of "out-of-order" frames.
* - Low level functions, BRD, BWR, APRMW, FPRD, LRW....
* - Blocking or non blocking transfers.
* - Automatic configuration of slaves.
* - Use of internal configuration table (quick).
* - Use of slave internal data in EEprom and/or CoE.
* - Setting and reading of slave state.
* - Automatic generation of processdata mapping.
* - Mailbox link layer support with resend toggle.
* - CoE, SDO read / write.
* - CoE, Complete Access support.
* - CoE, Segmented transfer support.
* - CoE, Object Description list
* - CoE, Emergency and abort SDO support.
* - Distributed Clock (DC) support.
* - Automatic configuration of DC slaves.
* - Automatic sync of clocks with process data exchange.
* - Flexible settting of sync0 and sync1 firing per slave.
* - Access to slave functions through one slave structure.
* - EEPROM read / write.
* - Local cache for EEPROM access with automatic 4/8 byte reading.
* - SII parsing.
* - Portable code, only standard c, usable for embedded applications.
* - All buffers are static so can be memory locked.
* - Support for Little and Big endian targets.
*
* Features as of 1.1.3 :
* - CoE, TxPDO and RxPDO, master is client (beta).
* - FoE, Read and Write file (beta).
*
* Features as of 1.1.4 :
* - FMMU allocation is floating instead of fixed. If needed more than 2 FMMUs are used.
* - SYNC1 generation supported.
*
* Features as of 1.2.0 :
* - Changed license to GPLv2 only. Adresses leagal concerns about master licensing.
* - Slave init and process data mapping is split in two functions. This allows
* dynamic user reconfiguration of PDO mapping.
* - Eeprom transfer to and from PDI
* - Eeprom is released to PDI when going to SAFEOP.
*
* Features as of 1.2.2 :
* - Redesign of topology and delay measurement. 4 port slaves are fully supported now.
* - Delay measurement of slaves that are reverse connected work too.
* - New ethercatprint unit to display errors in readable text.
*
* Features as of 1.2.4 :
* - SoE, servo over EtherCAT support.
* - SoE read request and write request.
* - SoE segmented transfers.
* - SoE error response.
* - Added SoE errors to print module.
* - Auto config of SoE process data.
*
* Features as of 1.2.5 :
* - Added eepromtool, it can read and write the ESC eeprom of a designated slave.
* - Rewrite of eeprom read/write functions.
* - Added infrastructure change to allow slave groups.
* - Added recovery and reconfiguration of slaves after connection loss.
* - Improved CoE PDO assignment read from slaves, no longer assume assign indexes
* as functionally fixed.
*
* Features as of 1.2.8 :
* - Changed directory structure.
* - Changed make file.
* - Moved hardware / OS dependend part in separate directories.
* - Added firm_update tool to upload firmware to slaves in Boot state, use with care.
* - Added DC for LRD/LWR case.
* - Separated expectedWKC to inputsWKC and outputsWKC.
* - Added PreOP->SafeOP hooks in configuration functions.
* - With CoE use expedited download if mailbox size is very small and object <= 4 bytes.
* - Added mailbox error handling.
* - Rewrite of ec_recover_slave() and ec_reconfigure_slave()
* - Added -map option in slaveinfo, shows SOEM IO mapping of all slaves found.
*
* Features as of 1.3.0 :
* - Added win32 target.
* - Added rtk target.
* - Compiles under gcc / visual-c / borland-c.
* - Multiple port support. One master can run concurrent stacks on multiple network ports.
* - All global vars are encapsulated in context struct.
* - All timing abstracted in osal.c.
* - Linux timing converted to get_clock(CLOCK_MONOTONIC).
* - Error messages updated to latest ETG1020 document.
* - FoE transfers now support busy response.
*
* \section start Getting started
*
* For Linux
* - go to project directory
* - source ./setup.sh linux
* - make all
*
* For examples see simple_test.c in ~/test/linux/simple_test.
* First try (assume EtherCAT on eth0): sudo ./simple_test eth0
* As SOEM uses RAW sockets it will need to run as root.
*
* For Windows
* - have winpcap installed (included with WireShark)
* - go to project directory
* - for VC, run vcvarsall.bat
* f.e. : C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\vcvarsall.bat x86
* - run make_test_win32_all.bat
*
* \section bugs Squashed bugs
* Version 1.1.3
* - Added missing Big-Endian conversion in ethercatconfig.c
* - Fixed bug in segmented SDO transfers in ethercatcoe.c
*
* Version 1.1.4
* - Changed FMMU algorithm of allocation during configuration. EL4732 supported now.
* - Changed the ec_slave structure around SM en FMMU storage.
* - Fixed bug in FoE write in ethercatfoe.c
*
* Version 1.2.0
* - Fixed bug in type definition of int32 and uint32 for 64bit OS.
* - Fixed bug in maximum dataframe size calculation.
*
* Version 1.2.2
* - Fixed bugs in ec_adddatagram.
* - Fixed several bugs in CoE object dictionary read functions.
* - Fixed bug in PDO mapping read function.
* - Changed ec_slave structure around topology and delay variables.
* - Added several constants in ethercattype.c
*
* Version 1.2.3
* - Clear SM enable if size is 0, even if enable is set in SII.
* - Fixed bug in DC propagation delay calculation. Branches with only non DC slaves
* now correctly close root port.
* - Fixed bug in ec_receive_processdata(), wkc now checks for EC_NOFRAME instead of 0.
* - Fixed bug in makefile.
*
* Version 1.2.5
* - Fixed bugs in ec_config_map().
* - Added EC_STATE_BOOT constant.
* - Fixed mailbox size bug, In and Out mailbox can now be of different size.
* - Fixed SM type bug.
* - Fixed FoE bugs.
* - Fixed siigetbyte() unaligned copy.
* - Fixed bug in nicdrv.c, socket handles are 0 included.
* - Fixed bug in ethercatconfig.c causing memory corruption.
*
* Version 1.2.8
* - Fixed NetX mailbox configuration behaviour.
* - Fixed FoE write bug.
* - Fixed SII string read bug.
* - Fixed bug in table lookup for printing
*
* Version 1.3.0
* - Fixed NetX100 configuration behaviour.
* - Fixed linux gettimeofday() to get_clock().
* - Fixed eeprom cache flush on reinit.
* - Fixed make for new gcc linker version.
*
2015-03-24 18:19:27 +01:00
* Version 1.3.1
2015-03-11 21:45:16 +01:00
* - Added intime target.
* - Added rtk\fec target.
* - Compiles under gcc / visual-c / intime / borland-c .
* - Added multi-threaded configuration for parallel configurations of slaves
*
2014-11-25 16:10:29 +01:00
* \section legal Legal notice
2015-03-11 21:45:16 +01:00
* Copyright© 2005-2015 Speciaal Machinefabriek Ketels v.o.f. \n
* Copyright© 2005-2015 Arthur Ketels \n
2014-11-25 16:10:29 +01:00
* Copyright© 2008-2010 TU/e Technische Universiteit Eindhoven \n
2015-03-11 21:45:16 +01:00
* Copyright© 2012-2015 RT-labs AB \n
2014-11-25 16:10:29 +01:00
*
* SOEM is free software; you can redistribute it and/or modify it under
* the terms of the GNU General Public License version 2 as published by the Free
* Software Foundation.
*
* SOEM is distributed in the hope that it will be useful, but WITHOUT ANY
* WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* for more details.
*
* As a special exception, if other files instantiate templates or use macros
* or inline functions from this file, or you compile this file and link it
* with other works to produce a work based on this file, this file does not
* by itself cause the resulting work to be covered by the GNU General Public
* License. However the source code for this file must still be made available
* in accordance with section (3) of the GNU General Public License.
*
* This exception does not invalidate any other reasons why a work based on
* this file might be covered by the GNU General Public License.
*
* The EtherCAT Technology, the trade name and logo "EtherCAT" are the intellectual
* property of, and protected by Beckhoff Automation GmbH. You can use SOEM for
* the sole purpose of creating, using and/or selling or otherwise distributing
* an EtherCAT network master provided that an EtherCAT Master License is obtained
* from Beckhoff Automation GmbH.
*
* In case you did not receive a copy of the EtherCAT Master License along with
* SOEM write to Beckhoff Automation GmbH, Eiserstrasse 5, D-33415 Verl, Germany
* (www.beckhoff.com).
*/