Just 'SOEM' Drivers - C drivers for Simple Open Ethercat Master(SOEM) devices
JSD has only be tested only on Ubuntu 16.04, 18.04, 20.04 and Raspberry Pi. The use of PThreads invalidates JSD on some platforms that SOEM can support. The JSD maintainers do not have non-posix platforms in-scope for JSD, but feel free to open an issue and let your voice be heard.
Required:
- SOEM
- CMake 3.11 or later
- Posix threads
Optional:
$ sudo apt install libreadline-dev # only used for test programsTo build jsd from source:
$ git clone git@github.com:nasa-jpl/jsd.git
$ cd jsd
$ mkdir build
$ cd build
$ cmake ..
$ makeThe following commands will execute the unit tests:
$ cd build
$ cmake -DBUILD_JSD_TESTS=ON ..
$ make
$ make test
$ make memcheck # note valgrind is required to perform memory checkingSee the TROUBLESHOOTING.md file for a soon-to-be growing list of tips and tricks to help you through common issues. Feel free to open an issue with you problem description.
Many devices have been used over the years within JPL, some more useful than others or fallen out of favor over time. Three tiers of devices are defined to focus JSD development, prioritizing the most useful devices. The following table represents the latest state of the JSD library:
| Device | Tier | Minimum JSD Version Required |
|---|---|---|
| EL2124 | 1 | 1.0.0 |
| EL3208 | 1 | 1.0.0 |
| EL3602 | 1 | 1.0.0 |
| Elmo Gold Drives | 1 | 1.0.0 |
| Elmo Platinum Drives | 1 | TBD |
| EL3356 | 2 | 1.1.0 |
| JED (JPL EtherCat Device) | 2 | 1.2.0 |
| ATI Force-Torque Sensor | 2 | 1.4.0 |
| EL1008 | 2 | 2.3.4 |
| EL3202-0010 | 2 | 1.5.0 |
| EL3255 | 2 | TBD |
| EL3318 | 2 | 1.5.0 |
| EL3202 | 2 | TBD |
| EL3104 | 2 | 1.5.0 |
| EL2624 | 3 | By Request Only |
| EL2809 | 3 | By Request Only |
| EL3008 | 3 | By Request Only |
| EL3058 | 3 | By Request Only |
| EL5101 | 3 | By Request Only |
| EL6001 | 3 | By Request Only |
For the software package to utilize JSD, an alternate way is to fetch JSD while building using FetchContent. For the case, include the following to your CMakeLists.txt
include(FetchContent)
FetchContent_Declare(jsd
GIT_REPOSITORY git@github.com:nasa-jpl/jsd.git
GIT_TAG v1.4.0
)
FetchContent_MakeAvailable(jsd)It is always recommend you specify your jsd dependency to a tagged release (GIT_TAG v1.4.0) so updates to master cannot break your build (NOT GIT_TAG master).
JSD uses Semantic versioning to help applications reason about the software as updates are continuously rolled out. Tailored to JSD, the Semver rules are as follows:
- Major Versions will denote changes to the API, which may break some user applications.
- Minor Versions will denote new features or driver additions that do not break user applications.
- Patch Versions will denote bug fixes or minor improvements and will not break user applications.
Violations of these rules will be considered errors and should be patched immediately. Please open an issue if you find a violation.
A slave introspection tool is provided by JSD. This tool is offered in a version of SOEM but we are leveraging a mode of SOEM that avoids global definitions so this tool was migrated to JSD.
The most useful invocation is shown here.
$ sudo ./build/jsd_slaveinfo <NIC_Device_Name> -map
The -map option lists the PDO mapping active on the device. When ELMO Gold Drives are powered on they have the default PDO mapping. The following example simply has a single ELMO device on the EtherCAT bus.
$ sudo ./build/jsd_slaveinfo eth9 -map
jsd (Simple Open EtherCAT Master)
Slaveinfo
Starting slaveinfo
ec_init on eth9 succeeded.
ec_config_init 0
1 slaves found and configured.
...
Slave:1
Name:? M:0000009a I:00030924
Output size: 64bits
Input size: 0bits
State: 4
Delay: 0[ns]
Has DC: 1
DCParentport:0
Activeports:1.0.0.0
Configured address: 1001
Man: 0000009a ID: 00030924 Rev: 00010400
SM0 A:1800 L: 140 F:00010026 Type:1
SM1 A:1900 L: 140 F:00010022 Type:2
SM2 A:1100 L: 8 F:00010064 Type:3
SM3 A:1180 L: 32 F:00010020 Type:0
FMMU0 Ls:00000000 Ll: 8 Lsb:0 Leb:7 Ps:1100 Psb:0 Ty:02 Act:01
FMMUfunc 0:1 1:2 2:0 3:0
MBX length wr: 140 rd: 140 MBX protocols : 0e
CoE details: 3f FoE details: 01 EoE details: 01 SoE details: 00
Ebus current: 0[mA]
only LRD/LWR:0
PDO mapping according to CoE :
SM2 outputs
addr b index: sub bitl data_type name
[0x0000.0] 0x607A:0x00 0x20 INTEGER32 Target position
[0x0004.0] 0x60FE:0x01 0x20 UNSIGNED32 Physical outputs
[0x0008.0] 0x6040:0x00 0x10 UNSIGNED16 Controlword
SM3 inputs
addr b index: sub bitl data_type name
[0xFF1C6338.0] 0x6064:0x00 0x20 INTEGER32 Position actual value
[0xFF1C633C.0] 0x60FD:0x00 0x20 UNSIGNED32 Digital inputs
[0xFF1C6340.0] 0x6041:0x00 0x10 UNSIGNED16 Statusword
End slaveinfo, close socket
[DEBUG] (/home/dev/src/jsd/src/jsd.c:190) Closing SOEM socket connection...
End program
The Elmo Gold Drive Two-Letter Command TTY is a simple terminal application that performs SDO read and writes through the Elmo Command Reference parameters. This is meant to mimic the function of the Elmo Application Studio (EAS) TTY to help reduce dependence on Windows computers running EAS.
The utility uses the FSF Readline library to parse user inputs. This library can be installed with the following:
# Tested on Ubuntu 16.04
$ sudo apt install libreadline-devIf this system library cannot be found, the build will ignore this program and continue making the jsd library.
$ sudo ./bin/jsd_egd_tlc_tty
[ ERROR ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:112) Expecting exactly 2 arguments
[ INFO ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:113) Usage: jsd_egd_tlc_tty <ifname> <egd_slave_index>
[ INFO ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:114) Example: $ jsd_egd_tlc_tty eth0 2
$ sudo ./bin/jsd_egd_tlc_tty eth0 6
...
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:37) user input is:
[ WARN ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:96) Could not parse user input, n_parsed: -1
[ INFO ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:97) Please input commands of the form: float CL[2] = 1.5
[ INFO ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:98) Or query current parameters using the form: float CL[2]
[ INFO ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:99) type q or quit (or ctrl+c) to end program
>> float PL[2] = 2.22
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:37) user input is: float PL[2] = 2.22
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:71) parsed val_type: float
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:72) parsed tlc: PL
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:73) parsed subindex: 2
[ DEBUG ](/home/dev/src/jsd/tools/jsd_egd_tlc_tty.c:74) parsed val_str: 2.22
[ DEBUG ](/home/dev/src/jsd/src/jsd_egd.c:443) Converted TLC: PL to index 0x3191
>> [ INFO ](/home/dev/src/jsd/src/jsd_sdo.c:115) Slave[6] Write 0x3191:2 (F32) = 2.220000
Single device test programs are provided with JSD, used for isolated driver development. Test programs are built by default but they can be excluded from the build using the BUILD_JSD_TESTS CMake option.
# in the build directory
$ cmake .. -DBUILD_JSD_TESTS=OFF
$ make
...Single device tests are created for each of the supported devices mainly for driver development on dedicated 'playground' electronics. Each program is created to stress test different parts of the driver so it is not recommended you run these tests on arbitrary hardware but only on test articles. Typically, pure input sensing devices tests should be safe to run but output devices (like EL2124 and EGDs) will output voltages and command actuators in a potentially unsafe way.
Either way, these programs serve as a minimum working example and allow driver developers to test features and fix bugs.
For example, The EL3602 test can be queried and called according to the following commands:
$ ./jsd_el3602_test -h
[ERROR] (/home/dev/src/jsd/test/device/jsd_el3602_test.c:63) Expecting exactly 3 arguments
[INFO] (/home/dev/src/jsd/test/device/jsd_el3602_test.c:64) Usage: jsd_el3602_test <ifname> <el3602_slave_index> <loop_freq_hz>
[INFO] (/home/dev/src/jsd/test/device/jsd_el3602_test.c:65) Example: $ jsd_el3602_test eth0 2 1000
$ sudo ./jsd_el3602_test eth9 5 2000The API documentation can be built using the source code locally using doxygen.
The .doxygen.in file is converted to .doxygen during build to ensure semantic versioning number of the documentation is accurate. The output documentation is created in the directory 'doxygen_html' and can be opened by any web browser from the root index.html webpage.
# Install dependencies for Ubuntu 14.04, 16.04, and 18.04
$ sudo apt install doxygen graphviz
# use the build system to generate the code for you!
$ cd build
$ make doc- Do all development on a new branch prefixed with -* branched from "master" e.g. ("USER-my-widget")
- All enums, structs, and functions should be prefixed with
jsd_as necessary - Abstract the details of your driver to help users of JSD
- Expose as little as possible in device_pub.h public API
- Hide as much as you can in the private device.h header
- Document your work
- DO write DOXYGEN preambles to functions, structs, and enums
- DO Explaining the enums and fixed values used by your driver
- DO Include references to manufacturer provided documents
- DON'T write excessively long inline comments in functions (target single line if possible)
- Consider refactoring if you find yourself wanting to write paragraphs
- Strive for brevity after all, "comments aren't compiled"
- run clang-format before you submit a pull request
- All enums, structs, and functions should be prefixed with
- Once you have completed your work, Create a pull request to the "master" branch.
- The "master" branch will be occasionally be given a tagged release as required
- semantic versioning will updated to "master" and the git commit will be tagged
before applying a commit, please run clang-format on all files using the default Google style. This can be achieved by running make format in the build directory that uses a CMake command to invoke the shell script from the project root directory. This is the prefered over the shell script since it ensures the working directory is properly set.
$ make format
It is highly recommended you integrate clang-format into your text editor of choice. Clang Format Integration