# Listing EtherCAT Slaves and Actuator Roles

`list_ethercat_slaves` is a command line utility, installed on the robot, that lists all the EtherCAT slaves detected on the bus together with their serial numbers. Optionally, it can also show the human-readable **actuator role**, the **actuator type**, the **actuator serial number**, and the **firmware version** of each slave. It is the quickest way to check that all the expected actuators are present on the bus and correctly identified before starting the robot.

## Usage

```console
list_ethercat_slaves [OPTIONS]
```

| Option | Description |
|---|---|
| `-a`, `--all` | Show all available columns (role, type, actuator serial, firmware version) |
| `-r`, `--role` | Include the actuator role in the output |
| `-t`, `--actuator-type` | Include the actuator type in the output |
| `-s`, `--actuator-serial` | Include the actuator serial number in the output |
| `-f`, `--firmware-version` | Include the firmware version in the output |
| `-h`, `--help` | Display the help message |

## Output columns

| Column | Description |
|---|---|
| `Num` | Slave number on the bus |
| `Pos` | Slave position, as `<alias>:<position>` |
| `State` | Current EtherCAT state of the slave (`OP`, `PREOP`, etc.). `PREOP` is expected for devices that are not actuators, such as the EtherCAT junctions |
| `Flag` | Status flag of the slave. `+` means the slave has no error flags set |
| `Device` | Device name reported by the slave (truncated to 20 characters) |
| `Serial` | Slave serial number, read from CoE object `0x1018:4` |
| `Role` | Human-readable actuator role name, read from CoE object `0x10E0:1` (shown with `-r`/`--role`) — see [Actuator roles](#actuator-roles) |
| `Type` | Actuator hardware type code, read from CoE object `0x1019:1` (shown with `-t`/`--actuator-type`) — see [Actuator types](#actuator-types) |
| `Actuator SN` | Actuator serial number, read from CoE object `0x1019:2` (shown with `-s`/`--actuator-serial`) |
| `FW Version` | Firmware version string, read from CoE object `0x100A:0` (shown with `-f`/`--firmware-version`) |

Columns that cannot be read for a given slave (for example, the EtherCAT junctions, which are not actuators) are reported as `N/A`.

## Example

Running the tool with all columns enabled on a Kangaroo without arms and without feet FT sensors gives an output similar to this:

```console
$ list_ethercat_slaves -a
Num   Pos    State  Flag  Device                Serial           Role                            Type   Actuator SN      FW Version
----------------------------------------------------------------------------------------------------------------------------------------
0     0:0    PREOP  +     GX-JC06(IN,X2,X3)     N/A              N/A                             N/A    N/A
1     0:1    OP     +     mc21_f2838x_cm        7097576          leg_right_1_actuator            KA     80               1.22.1-0
2     0:2    OP     +     mc21_f2838x_cm        7097719          leg_right_2_actuator            KA     78               1.22.1-0
3     0:3    OP     +     mc21_f2838x_cm        7097558          leg_right_3_actuator            KA     77               1.22.1-0
4     0:4    OP     +     mc21_f2838x_cm        7097711          leg_right_4_actuator            KA     72               1.22.1-0
5     0:5    OP     +     mc21_f2838x_cm        7097720          leg_right_5_actuator            KA     74               1.22.1-0
6     0:6    OP     +     mc21_f2838x_cm        11496239         leg_right_length_actuator       LL     7                1.22.1-0
7     0:7    OP     +     mc21_f2838x_cm        7121395          leg_left_1_actuator             KA     73               1.22.1-0
8     0:8    OP     +     mc21_f2838x_cm        7097595          leg_left_3_actuator             KA     76               1.22.1-0
9     0:9    OP     +     mc21_f2838x_cm        7097586          leg_left_2_actuator             KA     75               1.22.1-0
10    0:10   OP     +     mc21_f2838x_cm        7097580          leg_left_5_actuator             KA     71               1.22.1-0
11    0:11   OP     +     mc21_f2838x_cm        7121369          leg_left_4_actuator             KA     79               1.22.1-0
12    0:12   OP     +     mc21_f2838x_cm        11496236         leg_left_length_actuator        LL     8                1.22.1-0
13    0:13   PREOP  +     GX-JC06(X4,X5,X6)     N/A              N/A                             N/A    N/A
14    0:14   OP     +     mc21_f2838x_cm        6758610          pelvis_1_actuator               S+     991              1.22.1-0
15    0:15   OP     +     mc21_f2838x_cm        8577867          pelvis_2_actuator               S+     1006             1.22.1-0
```

Slaves 0 and 13 are the two EtherCAT junctions (Omron GX-JC06) that create the star topology described in the [Electronics Overview](../kangaroo_robot/electronics_overview.md#ethercat-and-kinematic-topology) — they are not actuators, so they stay in `PREOP` state and report `N/A` for every actuator-specific column. All other slaves are `mc21_f2838x_cm` motor control boards, one per actuator, correctly identified by their role.

## Actuator roles

The role of a slave is a configuration value stored on the actuator itself (CoE object `0x10E0:1`) and read out as a human-readable name by `list_ethercat_slaves -r`. It identifies the name of the actuators, independently of its EtherCAT slave position, which makes it possible to spot a wrongly cabled or a swapped actuator immediately. A slave that does not implement the role object (for example, the EtherCAT junctions) is reported as `N/A`.

## Actuator types

The `Type` column decodes the last two bytes of CoE object `0x1019:1` as ASCII, and identifies which of the three [actuator module variants](../kangaroo_robot/electronics_overview.md) is mounted on that slave:

| Type code | Actuator module |
|---|---|
| `KA` | Linear Actuator Module (hip and ankle joints) |
| `LL` | Leg Length Actuator Module (leg extension actuator) |
| `S+` / `S-` | SEA Rotary Actuator Module (pelvis and arm joints) |

## See Also

- [Electronics Overview](../kangaroo_robot/electronics_overview.md) — EtherCAT topology and actuator module hardware
- [Firmware Update for Motor Control Drives](../robot_usage_guide/motor_drives_firmware.md) — updating the firmware of a single slave identified through `list_ethercat_slaves`