## page was renamed from swri-ros-pkg/Tutorials/Simple_EtherCAT_Network_IO
## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links
## note.0=
## descriptive title for the tutorial
## title = Create a simple EtherCAT IO network (Implementation Notes)
## multi-line description to be displayed in search
## description =
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for
## level= AdvancedCategory
## keywords = EtherCAT
####################################
<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

{{{#!wiki caution
Deprecation notice

This tutorial is kept for archival purposes only. Packages mentioned may not be available any more and the procedure outlined below may stop working at any time.
}}}


== Hardware Setup (example) ==
 1. T61 Thinkpad Laptop (built in Ethernet card)
 1. IO rack: EtherCAT Couper, 8 DI, & 8DO (all Beckhoff)

== Beckhoff EtherCAT Drivers ==
 1. Install [[orocos_toolchain|OROCOS toolchain]] for ROS
 1. Install Simple Open !EtherCAT Master (soem) library from source:
 {{{
git clone https://github.com/orocos/rtt_soem.git
}}}
 1. Make soem by running `catkin_make`.
 1. Connect EtherCAT device to ethernet port.  EtherCAT works over standard ethernet cable.  Make a direct connection, I do not think connections through switches work since EtherCAT couplers do not have IP addresses (typcially)
 1. In the `soem_core` package give the `slaveinfo` binary root access to socket commands:
 {{{
 sudo setcap cap_net_raw+ep bin/slaveinfo
}}}
 (you might have to install this utility: `sudo apt-get install libcap2-bin`)
 1. Execute the `slaveinfo` utility:
 {{{
 rosrun soem_core slaveinfo <device, typcially eth0>
}}}
 When the utility successfully executes a list of connected slaves is printed (this list is generated by auto discovery).
 1. '''(This step may not be required on the latest soem version)''' The soem stack has a bug that fails to recognize IO sizes for unknown modules.  The following patch fixes the bug (BUG has been submitted).  Patch the soem stack with the following:
 {{{
 diff --git a/soem_master/soem_master_component.cpp b/soem_master/soem_master_component.cpp
 index e166ad0..dc6b460 100644
 --- a/soem_master/soem_master_component.cpp
 +++ b/soem_master/soem_master_component.cpp
 @@ -79,6 +79,8 @@ bool SoemMasterComponent::configureHook()
              // wait for all slaves to reach PRE_OP state
              ec_statecheck(0, EC_STATE_PRE_OP, EC_TIMEOUTSTATE);

 +          ec_config(FALSE, &m_IOmap);
 +
              for (int i = 1; i <= ec_slavecount; i++)
              {
                  SoemDriver
 @@ -89,6 +91,8 @@ bool SoemMasterComponent::configureHook()
                      m_drivers.push_back(driver);
                      log(Info) << "Created driver for " << ec_slave[i].name
                              << ", with address " << ec_slave[i].configadr
 +                            << ", output bits " << ec_slave[i].Obits
 +                            << ", input bits " << ec_slave[i].Ibits
                              << endlog();
                      //Adding driver's services to master component
                      this->provides()->addService(driver->provides());
}}}

 1. Run `rosmake` from the soem_master directory to compile in the patch
 1. Edit the `test.ops` script to start the master up and map OROCOS messages to ROS topics
 {{{
 import("soem_beckhoff_drivers")
 loadComponent("Master","soem_master::SoemMasterComponent")
 Master.displayAvailableDrivers()

 # Default nic is eth0, set if different. e.g.
 #Master.ifname = "eth1"

 # Crawls the network and identifies attached devices.  Devices are loaded
 # (if a driver exists) and given names "Slave_1***".  The *** appear to be
 # the module order (at least this is the case for a single rack)
 Master.configure()

 # Setting the update period (in seconds).  This determines the rate at which
 # the data is published on the ROS side (setting this value to zero turns
 # off updating
 Master.setPeriod(0.05)

 # This stars the Master "task" running.  It will update at the period set
 # above
 Master.start()

 # This command remaps OROCOS topics to ROS topics
 stream("Master.Slave_1002.bits", ros.topic("DI"))
 stream("Master.Slave_1003.bits", ros.topic("DO"))
}}}
 1. In the ocl package give the `deployer-gnulinux` binary (called by launch file below) root access to socket commands:
 {{{
 sudo setcap cap_net_raw+ep bin/deployer-gnulinux
}}}
 1. From the command line, launch the master:
 {{{
 roslaunch soem_master soem_master_test.launch
}}}
 The launch file launches orocos and loads the `test.ops` script.

Other Notes:

 1. Enabling OROCOS Info Logging: `export ORO_LOGLEVEL=5` (see [[http://www.orocos.org/stable/documentation/rtt/v2.x/doc-xml/orocos-components-manual.html#corelib-logging|The Orocos Component Builder's Manual - Logging]])
 1. Orocos messages to/from ROS messages (see [[rtt_ros_integration_example]]).  Example script call: `stream("Master.Slave_1002.bits", ros.topic("DI_bits"))`

## AUTOGENERATED DO NOT DELETE
## TutorialCategory
## Implementation Notes
## FILL IN THE STACK TUTORIAL CATEGORY HERE