IgH EtherCAT Master  1.6.9
README.md
1 FakeEtherCAT Library {#libfakeethercat}
2 ====================
3 
4 Libfakeethercat is a userspace library which has the same API as the EtherCAT
5 master interface library libethercat. Libfakeethercat can be used to spin up
6 your RT application in a dry-run mode, without any master configured or slaves
7 attached. Furthermore, it is possible to emulate EtherCAT slaves on process
8 data level by running two applications back to back.
9 
10 ## Supported features
11 
12 Although the library implements the complete API (to avoid undefined
13 references), most function calls will just do nothing and return no error.
14 However, some methods have a bit of logic implemented to simulate a working
15 master. This is what is possible:
16 
17  - Creating master and domain instances
18  - Activating master, `send()` and `receive()`.
19  - Processing and queuing domains
20  - Configuring PDOs
21  - Configuring SDOs using `ecrt_slave_config_sdo*()`
22 
23 The SDO config does not do anything, but when activating the master the SDO
24 config will be dumped into a JSON file.
25 
26 `ecrt_master_state()` and `ecrt_domain_state()` both return states as if the
27 bus works without errors. So currently, a bus error cannot be simulated.
28 
29 ## How to build
30 
31 [RtIPC](https://gitlab.com/etherlab.org/rtipc) is needed. Simply pass
32 `--enable-fakeuserlib` to your `./configure` call and the library will be
33 built for you.
34 
35 ## How to set up dry run mode
36 
37 ### Redirect library loading
38 
39 To avoid recompiling your application, we will use `LD_LIBRARY_PATH` to load
40 `libfakeethercat` instead of `libethercat`.
41 
42 ```sh
43 # pick a location for an empty directory
44 export MY_LIB_LOCATION=$HOME/fake_lib64
45 # create that directory
46 mkdir -p $MY_LIB_LOCATION
47 # create a symlink to libfakeethercat
48 # assuming SOVERSION is 1
49 # debian users, please use /usr/lib/x86_64-linux-gnu/libfakeethercat.so.1
50 ln -s /usr/lib64/libfakeethercat.so.1 $MY_LIB_LOCATION/libethercat.so.1
51 # use MY_LIB_LOCATION to load libraries first
52 export LD_LIBRARY_PATH=$MY_LIB_LOCATION
53 # check whether everything is done right
54 ldd my_application | grep ethercat
55  libethercat.so.1 => /home/vh/fake_lib64/libethercat.so.1 (0x7fa5c590)
56 ```
57 
58 ### Set up FakeEtherCAT Home
59 
60 RtIPC needs a place to store its configuration. Set `FAKE_EC_HOMEDIR`
61 environment variable to a path to an empty directory, for instance
62 `/tmp/FakeEtherCAT`. `FAKE_EC_NAME` can be set to a useful name of your
63 application, default is `FakeEtherCAT`.
64 
65 ```sh
66 export FAKE_EC_HOMEDIR=/tmp/FakeEtherCAT
67 rm -rf $FAKE_EC_HOMEDIR
68 mkdir -p $FAKE_EC_HOMEDIR
69 ```
70 For each master instance, one subdirectory named by the master id is created.
71 
72 ### Spin up your application
73 
74 Now it's time to simply launch your application.
75 You will notice that the PDO configuration will be dumped at stderr.
76 The path displayed is the path of the RtIPC variable in the following format:
77 `$FAKE_EC_PREFIX/$MASTER_ID/$ALIAS$POSITION/$PDO`.
78 
79 ## How to emulate EtherCAT slaves
80 
81 Let's say you'd like to build virtual EtherCAT slaves to emulate your field.
82 Libfakeethercat makes that possible with the help of RtIPC.
83 
84 ### Building a simulator
85 
86 Your field emulator simply has to swap the sync manager direction setting
87 (EC_DIR_INPUT and EC_DIR_OUTPUT) in ec_sync_info_t.
88 Libfakeethercat instances use shared memory, provided by RtIPC,
89 to exchange process data.
90 The direction setting decides which instance writes and which reads from
91 shared memory.
92 
93 For instance, emulating a digital output works in the following way:
94 Create another real time application with the same slave information
95 as your control application.
96 Then, replace all EC_DIR_INPUT with EC_DIR_OUTPUT and vice versa.
97 Now, remember to read process data instead of writing it, and vice versa.
98 So, your EL2004 digital out will be read by your simulating application
99 and has PDO object 0x1600 ff. configured with Sync Manager 2 as EC_DIR_INPUT.
100 
101 [EtherLab](https://gitlab.com/etherlab.org/etherlab) provides
102 a convenient way to build an entire simulator using SIMULINK since
103 Version 2.4.0.
104 Run `web(etherlab_help_path('swap_io.html'), '-helpbrowser')`
105 in your MATLAB shell to read more about how to set up a
106 Process Data simulator.
107 
108 ### Start your application
109 
110 First, do all the steps explained above to run your
111 control application in dry run mode.
112 Then, in another shell, do the same thing with your simulator,
113 but do not remove the `FAKE_EC_HOMEDIR` directory and
114 pick another `FAKE_EC_NAME`.
115 
116 Carefully watch the PDO configuration on stderr and compare them. All paths
117 configured as output on the control application have to be configured as input
118 on your simulator and vice versa.
119 
120 Finally, your control application needs to be restarted
121 so it can find the RtIPC variables which contains the process data of the
122 simulator.
123 
124 ## Environment variables
125 
126  - FAKE_EC_HOMEDIR: Directory for RtIPC bulletin board and SDO json files
127  - FAKE_EC_NAME: Will be used for naming RtIPC config and SDO json file
128  - FAKE_EC_PREFIX: Prefix for RtIPC variables, useful to run multiple
129  simulators side by side.