Skip to content

Update readme #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PastorD merged 3 commits into from
Mar 31, 2026
Merged

Update readme #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
869cea5
fix readme paths and outdated content
PastorD Mar 19, 2026
8daff35
update supported devices table
PastorD Mar 20, 2026
3650515
add device catalog table
PastorD Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 32 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
Just 'SOEM' Drivers - C drivers for Simple Open Ethercat Master(SOEM) devices

# Prerequisites
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.
JSD has only be tested only on Ubuntu 16.04, 18.04, 20.04, 22.04, 24.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.

Required:

Expand Down Expand Up @@ -57,22 +57,24 @@ most useful devices. The following table represents the latest state of the JSD
| EL3208 | 1 | 1.0.0 |
| EL3602 | 1 | 1.0.0 |
| Elmo Gold Drives | 1 | 1.0.0 |
| Elmo Platinum Drives | 1 | TBD |
| Elmo Platinum Drives | 1 | 2.2.0 |
| 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 |
| EL3162 | 2 | 1.6.0 |
| EL3318 | 2 | 1.5.0 |
| EL3202 | 2 | TBD |
| EL3314 | 2 | 3.1.4 |
| EL3104 | 2 | 1.5.0 |
| EL2624 | 3 | By Request Only |
| EL4102 | 2 | 1.6.0 |
| ILD1900 | 2 | 1.8.0 |
| EL2798 | 3 | 3.1.5 |
| 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 |
| EL2828 | 3 | 3.1.5 |
| EL5042 | 3 | 3.1.5 |

For a detailed list of supported devices and their features, see the [Supported Devices](docs/device-catalog.md) page.

# Using JSD in your Project
For the software package to utilize JSD, an alternate way is to fetch JSD while building using FetchContent.
Expand All @@ -82,21 +84,12 @@ 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
GIT_TAG v3.1.6
)
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`).

### Semantic Versioning
It is always recommend you specify your jsd dependency to a tagged release (`GIT_TAG v3.1.6`) 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.

# JSD Utilities

Expand All @@ -107,14 +100,14 @@ A slave introspection tool is provided by JSD. This tool is offered in a version
The most useful invocation is shown here.

```
$ sudo ./build/jsd_slaveinfo <NIC_Device_Name> -map
$ sudo ./build/bin/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
$ sudo ./build/bin/jsd_slaveinfo eth9 -map

jsd (Simple Open EtherCAT Master)
Slaveinfo
Expand Down Expand Up @@ -172,18 +165,18 @@ Elmo Application Studio (EAS) TTY to help reduce dependence on Windows computers
The utility uses the FSF Readline library to parse user inputs. This library can be installed with the following:

```bash
# Tested on Ubuntu 16.04
# Tested on Ubuntu 24.04
$ sudo apt install libreadline-dev
```
If this system library cannot be found, the build will ignore this program and continue making the jsd library.

```bash
$ sudo ./bin/jsd_egd_tlc_tty
$ sudo ./build/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
$ sudo ./build/bin/jsd_egd_tlc_tty eth0 6

...

Expand Down Expand Up @@ -224,13 +217,13 @@ Either way, these programs serve as a minimum working example and allow driver d
For example, The EL3602 test can be queried and called according to the following commands:

```bash
$ ./jsd_el3602_test -h
$ ./test/device/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 2000
$ sudo ./test/device/jsd_el3602_test eth9 5 2000
```

# Documentation
Expand All @@ -240,15 +233,13 @@ The 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.

```bash
# Install dependencies for Ubuntu 14.04, 16.04, and 18.04
# Install dependencies for Ubuntu 22.04 and 24.04
$ sudo apt install doxygen graphviz

# use the build system to generate the code for you!
$ cd build
$ make doc
```

# Contributing
## Contributing

* Do all development on a new branch prefixed with <your-username>-* branched from "master" e.g. ("USER-my-widget")
* All enums, structs, and functions should be prefixed with `jsd_` as necessary
Expand All @@ -267,12 +258,19 @@ $ make doc
* 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


## Semantic Versioning

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.

# Code Format
## Code Format

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.
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
```
Expand Down
35 changes: 35 additions & 0 deletions docs/device-catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Device Catalog

Generated by `tools/check_supported_devices.py` from device type headers, shared driver metadata, and online manufacturer references.

| Driver | Full name | Manufacturer | Vendor ID | Product code(s) | Channels / capacity | I/O kind | Direction | Accepted voltage | Details | Official source |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| ATI_FTS | ATI Force-Torque Sensor | ATI Industrial Automation | `JSD_ATI_VENDOR_ID=0x00000732` | `JSD_ATI_FTS_PRODUCT_CODE=0x26483052` | 6-axis wrench (Fx, Fy, Fz, Tx, Ty, Tz) | force-torque sensing | input | 20-48 V DC, or IEEE 802.3af Mode A PoE | Calibration-selectable force/torque sensor with integrated signal conditioning, status code, and sample counter. | https://www.ati-ia.com/app_content/documents/9620-05-EtherCAT.pdf |
| EGD | Elmo Gold Drive | Elmo Motion Control | `JSD_ELMO_VENDOR_ID=0x0000009A` | `JSD_EGD_PRODUCT_CODE=0x00030924` | 6 digital in / 6 digital out | servo drive and discrete I/O | bidirectional | Varies by Gold model; official Gold pages show 12-95 VDC low-voltage variants and 23-195 VDC higher-voltage variants. | Gold Line EtherCAT servo-drive family with DS-402 motion modes, analog input, and digital I/O. | https://www.elmomc.com/product/gold-cello/ |
| EL1008 | Beckhoff EL1008 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL1008_PRODUCT_CODE=0x03f03052` | 8 | digital input | input | 24 V DC nominal (-15%/+20%); logic 0: -3 to +5 V, logic 1: 11 to 30 V. | 8-channel digital input terminal. | https://www.beckhoff.com/de-de/produkte/i-o/ethercat-klemmen/el-ed1xxx-digital-eingang/el1008.html |
| EL2124 | Beckhoff EL2124 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL2124_PRODUCT_CODE=0x084c3052` | 4 | digital output | output | 5 V DC nominal output. | 4-channel CMOS push-pull digital output terminal. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed2xxx-digital-output/el2124.html |
| EL2798 | Beckhoff EL2798 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL2798_PRODUCT_CODE=0x0AEE3052` | 8 | digital output | output | 0-30 V AC/DC nominal; up to 48 V DC for ohmic loads. | 8-channel solid-state relay output with potential-free make contacts. | https://www.beckhoff.com/pl-pl/products/i-o/ethercat-terminals/el-ed2xxx-digital-output/el2798.html |
| EL2809 | Beckhoff EL2809 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL2809_PRODUCT_CODE=0x0af93052` | 16 | digital output | output | 24 V DC nominal (-15%/+20%). | 16-channel positive-switching digital output terminal. | https://www.beckhoff.com/ms-my/products/i-o/ethercat-terminals/el2xxx-digital-output/el2809.html |
| EL2828 | Beckhoff EL2828 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL2828_PRODUCT_CODE=0x0B0C3052` | 8 | digital output | output | 24 V DC nominal; 20.4-28.8 V DC technical range. | 8-channel digital output terminal for resistive, inductive, and capacitive loads. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed2xxx-digital-output/ed2828.html |
| EL3104 | Beckhoff EL3104 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3104_PRODUCT_CODE=0x0c203052` | 4 | analog voltage input | input | -10 to +10 V signal range. | 4-channel differential analog voltage input with filter, limit, and sync-error reporting. | https://www.beckhoff.com/de-de/produkte/i-o/ethercat-klemmen/el-ed3xxx-analog-eingang/el3104.html |
| EL3162 | Beckhoff EL3162 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3162_PRODUCT_CODE=0x0c5a3052` | 2 | analog voltage input | input | 0 to 10 V signal range; dielectric strength max 30 V. | 2-channel single-ended analog voltage input with underrange, overrange, and error flags. | https://www.beckhoff.com/de-de/produkte/i-o/ethercat-klemmen/el-ed3xxx-analog-eingang/el3162.html |
| EL3202 | Beckhoff EL3202-0010 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3202_PRODUCT_CODE=0x0c823052` | 2 | RTD / resistance input | input | Not a voltage-input terminal; supports RTD/resistance sensors with measuring current < 0.5 mA. | 2-channel RTD/resistance input with configurable sensor type and connection technology. | https://www.beckhoff.com/en-en/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3202-0010.html |
| EL3208 | Beckhoff EL3208 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3208_PRODUCT_CODE=0x0c883052` | 8 | RTD / resistance input | input | Not a voltage-input terminal; supports RTD/resistance sensors with measuring current < 0.5 mA. | 8-channel RTD/resistance input with configurable sensor type, wiring, filters, and presentation mode. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3208.html |
| EL3314 | Beckhoff EL3314 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3314_PRODUCT_CODE=0x0cf23052` | 4 | thermocouple input | input | Thermocouple / voltage measurement ranges of +/-30, +/-60, or +/-75 mV. | 4-channel thermocouple input with multiple TC types, wire-break detection, and cold-junction handling. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3314.html |
| EL3318 | Beckhoff EL3318 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3318_PRODUCT_CODE=0x0cf63052` | 8 | thermocouple input | input | Thermocouple / voltage measurement ranges of +/-30, +/-60, or +/-75 mV. | 8-channel thermocouple input with multiple TC types, wire-break detection, and cold-junction handling. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3318.html |
| EL3356 | Beckhoff EL3356 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3356_PRODUCT_CODE=0x0D1C3052` | 1 weighing / strain-gauge value | load cell / strain gauge input | input | Bridge reference nominal +/-12 V; technically usable to about +/-13.8 V. Beckhoff recommends 10 V or 12 V depending on sensor. | Load-cell / full-bridge input with tare support, scaling, auto-calibration, and steady-state status. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el3xxx-analog-input/el3356.html |
| EL3602 | Beckhoff EL3602 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL3602_PRODUCT_CODE=0x0e123052` | 2 | high-resolution analog voltage input | input | Main EL3602 supports +/-10, +/-5, +/-2.5, and +/-1.25 V; related variants support +/-75 mV and +/-200 mV. | 2-channel differential high-resolution analog voltage input with filters and limit monitoring. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3602.html ; https://www.beckhoff.com/de-ch/produkte/i-o/ethercat-klemmen/el3xxx-analog-eingang/el3602-0010.html ; https://www.beckhoff.com/en-en/products/i-o/ethercat-terminals/el-ed3xxx-analog-input/el3602-0002.html |
| EL4102 | Beckhoff EL4102 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL4102_PRODUCT_CODE=0x10063052` | 2 | analog voltage output | output | 0 to 10 V output range. | 2-channel analog voltage output terminal. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed4xxx-analog-output/el4102.html |
| EL5042 | Beckhoff EL5042 | Beckhoff | `JSD_BECKHOFF_VENDOR_ID=0x00000002` | `JSD_EL5042_PRODUCT_CODE=0x13b23052` | 2 | BiSS-C / SSI position input | input | Encoder supply selectable between 5 V DC and 9 V DC; electronics supplied from 24 V DC power contacts. | 2-channel BiSS-C / SSI encoder interface with configurable clocking, coding, and encoder bit layout. | https://www.beckhoff.com/en-us/products/i-o/ethercat-terminals/el-ed5xxx-position-measurement/el5042.html |
| EPD_NOMINAL | Elmo Platinum Drive (Nominal Mode) | Elmo Motion Control | `JSD_ELMO_VENDOR_ID=0x0000009A` | `JSD_EPD_PRODUCT_CODE_STD_FW=0x00100002, JSD_EPD_PRODUCT_CODE_SAFETY_FW=0x01100002` | 16 digital in / 6 digital out (+ 2 analog inputs) | servo drive and mixed I/O | bidirectional | Varies by Platinum model; official Platinum pages show 10-95 VDC low-voltage variants, while high-voltage models use roughly 50-780 VDC bus supplies and 22-52 VDC control supplies. | Platinum EtherCAT servo-drive family in nominal mode, with DS-402 motion modes, 2 analog inputs, and discrete I/O. | https://www.elmomc.com/product/platinum-quartet/ ; https://www.elmomc.com/product/platinum-jori/ |
| EPD_SIL | Elmo Platinum Drive (SIL Mode) | Elmo Motion Control | `JSD_ELMO_VENDOR_ID=0x0000009A` | `JSD_EPD_PRODUCT_CODE_STD_FW=0x00100002, JSD_EPD_PRODUCT_CODE_SAFETY_FW=0x01100002` | up to 32 R1 vars / 16 R2 vars | servo drive with SIL user mappings | bidirectional | Varies by Platinum model; official Platinum pages show 10-95 VDC low-voltage variants, while high-voltage models use roughly 50-780 VDC bus supplies and 22-52 VDC control supplies. | Platinum EtherCAT servo-drive family in SIL mode, with configurable R1/R2 mapped variables and user PO2SO callback support. | https://www.elmomc.com/product/platinum-quartet/ ; https://www.elmomc.com/product/platinum-jori/ |
| ILD1900 | Micro-Epsilon optoNCDT ILD1900 | Micro-Epsilon | `JSD_MICROEPSILON_VENDOR_ID=0x00000607` | `JSD_ILD1900_PRODUCT_CODE=0x60CB01F6` | 1 displacement measurement | laser displacement input | input | 24 V DC nominal, 11-30 V DC operating range; PoE is also supported on EtherCAT variants. | Laser displacement sensor with configurable model, exposure mode, peak selection, averaging, and measurement rate. | https://www.micro-epsilon.com/fileadmin/download/manuals/man--optoNCDT-1900-IE-EtherCAT--en.pdf |
| JED0101 | JPL EtherCAT Device 0101 | NASA JPL | `JSD_JPL_VENDOR_ID=0x00000C53` | `JSD_JED0101_PRODUCT_CODE=0x00009252` | quaternion telemetry + command word | custom telemetry / command interface | bidirectional | No public online documentation found. | Custom JPL EtherCAT device exposing IMU quaternion data and a command register. | No public source found |
| JED0200 | JPL EtherCAT Device 0200 | NASA JPL | `JSD_JPL_VENDOR_ID=0x00000C53` | `JSD_JED0200_PRODUCT_CODE=0x00001001` | power, environment, brake telemetry + command word | custom telemetry / command interface | bidirectional | No public online documentation found. | Custom JPL EtherCAT device exposing voltages, temperatures, humidity, pressure, and brake telemetry. | No public source found |

## Scope Notes

- `Product code(s)` and vendor IDs are parsed from the type headers and shared device-type headers.
- `Channels / capacity` uses `JSD_*_NUM_CHANNELS` where available. For drives and custom devices, it uses the most relevant capacity macros or a driver-specific summary.
- `Accepted voltage` and `Official source` are based on vendor product pages, manuals, or technical reference pages checked online.
- `Details` are intentionally concise and combine the code-facing view of the device with the vendor descriptions.
Loading
Loading