Merge pull request #87 from nasa-jpl/apb-rename-actuator-classes

Rename actuator classes

Author: alex-brinkman

doc/fastcat_device_config_parameters.md

@@ -4,19 +4,20 @@
 
 For every `JSD Device` there is an `Offline Device` to emulate the behavior of the hardware.
 
-| Name     | Manufacturer | Description                         |
-| -------- | ------------ | ----------------------------------- |
-| Actuator | Elmo         | EGD with extra features             |
-| Egd      | Elmo         | Elmo Gold Drive line of controllers |
-| El3208   | Beckhoff     | 8-channel RTD Input                 |
-| El3162   | Beckhoff     | 2-channel 0-10v SE Analog Input     |
-| El3602   | Beckhoff     | 2-channel +/-10v Diff. Analog Input |
-| El2124   | Beckhoff     | 4-channel 5v Digital Output         |
-| El4102   | Beckhoff     | 2-channel 0-10v Analog Output       |
-| Ild1900  | Micro-Epsilon | Distance Laser Sensor |
-| AtiFts   | ATI          | Force-Torque Sensor                 |
-| JED0101  | JPL          | JPL EtherCAT Device 0101 - EELS     |
-| JED0200  | JPL          | JPL EtherCAT Device 0200 - SAEL     |
+| Name             | Manufacturer  | Description                               |
+| ---------------- | ------------- | ----------------------------------------- |
+| PlatinumActuator | Elmo          | Elmo Platinum derived Actuator controller |
+| GoldActuator     | Elmo          | Elmo Gold derived Actuator controller     |
+| Egd              | Elmo          | Elmo Gold Drive                           |
+| El3208           | Beckhoff      | 8-channel RTD Input                       |
+| El3162           | Beckhoff      | 2-channel 0-10v SE Analog Input           |
+| El3602           | Beckhoff      | 2-channel +/-10v Diff. Analog Input       |
+| El2124           | Beckhoff      | 4-channel 5v Digital Output               |
+| El4102           | Beckhoff      | 2-channel 0-10v Analog Output             |
+| Ild1900          | Micro-Epsilon | Distance Laser Sensor                     |
+| AtiFts           | ATI           | Force-Torque Sensor                       |
+| JED0101          | JPL           | JPL EtherCAT Device 0101 - EELS           |
+| JED0200          | JPL           | JPL EtherCAT Device 0200 - SAEL           |
 
 **Fastcat Devices**
 
@@ -164,7 +165,11 @@ These two parameters, `device_class` and `name`, are not explicitly covered in t
 
 ## JSD and Offline Device Parameters
 
-## Actuator
+## GoldActuator and PlatinumActuator
+
+Care was taken to ensure the Gold and Platinum device configuration parameters are shared between these two device drivers. 
+
+Note: the `egd_` suffix was changed to `elmo_` in `v0.12.0` 
 
 Engineering Units (EU) are radians for revolute actuators and meters for linear actuators.
 
@@ -187,10 +192,10 @@ Engineering Units (EU) are radians for revolute actuators and meters for linear
 | `high_pos_cal_limit_eu`         | Upper Position Limit typically corresponding to a hardstop. Used for Calibration Command |
 | `high_pos_cmd_limit_eu`         | Highest allowable command position value                     |
 | `holding_duration_sec`          | Duration to hold position after reset or after a motion command before re-engaging brakes |
-| `egd_brake_engage_msec`         | How long it takes to re-engage the brakes                    |
-| `egd_brake_disengage_msec`      | How long it takes to disengaged the brakes                   |
-| `egd_crc`                       | CRC of the flashed Elmo parameter set                        |
-| `egd_drive_max_current_limit`   | The Maximum drive current for the Elmo Gold Drive            |
+| `elmo_brake_engage_msec`        | How long it takes to re-engage the brakes                    |
+| `elmo_brake_disengage_msec`     | How long it takes to disengaged the brakes                   |
+| `elmo_crc`                      | CRC of the flashed Elmo parameter set                        |
+| `elmo_drive_max_current_limit`  | The fixed, maximum drive current for the Elmo Drive          |
 | `smooth_factor`                 | Affects controller smoothing, defaults to `0`                |
 | `winding_resistance`            | OPTIONAL: Winding resistance of motor for optional power calculation |
 | `torque_constant`               | OPTIONAL: Torque constant of motor for optional power calculation  |
@@ -212,7 +217,7 @@ Engineering Units (EU) are radians for revolute actuators and meters for linear
 ### Example
 
 ``` yaml
-    - device_class:                  Actuator
+    - device_class:                  PlatinumActuator #or GoldActuator 
       name:                          tool
       actuator_type:                 revolute # eu = radians
       gear_ratio:                    19
@@ -231,16 +236,85 @@ Engineering Units (EU) are radians for revolute actuators and meters for linear
       high_pos_cmd_limit_eu:         1e15
       high_pos_cal_limit_eu:         1e15
       holding_duration_sec:          5.0
-      egd_brake_engage_msec:         10 
-      egd_brake_disengage_msec:      10
-      egd_crc:                       -3260
-      egd_drive_max_current_limit:   10
+      elmo_brake_engage_msec:         10 
+      elmo_brake_disengage_msec:      10
+      elmo_crc:                       -3260
+      elmo_drive_max_current_limit:   10
       smooth_factor:                 0
 ```
 
 
 
-## Egd (Elmo Gold Drive) TODO
+## Egd (Elmo Gold Drive) 
+
+This is a thin wrapper around the JSD EGD device. This does not have fastcat-side profiling nor any notion of gear ratio so the drive must be commanded in encoder counts.
+
+| Parameter                        | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------ |
+| `cs_cmd_freq_hz`                 | The Target loop rate to command the drive in {CSP, CSV, CST} modes |
+| `drive_cmd_mode`                 | Either `CS` or `PROFILED` see notes below for more details |
+| `max_motor_speed`                | Maximum speed this drive may be commanded in counts/sec   |
+| `torque_slope`                   | Rate to apply torque in certain profiled torque command modes |
+| `max_profile_accel`              | ELMO-side profiler acceleration in counts/sec |
+| `max_profile_decel`              | ELMO-side profiler deceleration in counts/sec |
+| `velocity_tracking_error`        | ELMO-side velocity tracking error in counts/sec |
+| `position_tracking_error`        | ELMO-side position tracking error in counts |
+| `peak_current_limit`             | Peak instantaneous current in Amp |
+| `peak_current_time`              | Max apply duration of Peak current before dropping down to Max Continuous current |
+| `continuous_current_limit`       | Max continuously supplied current permitted to actuator |
+| `motor_stuck_current_level_pct`  | See Elmo docs for details on this feature, `0` disables|
+| `motor_stuck_velocity_threshold` | See Elmo docs for details on this feature, `0` disables|
+| `motor_stuck_timeout`            | See Elmo docs for details on this feature |
+| `over_speed_threshold`           | High motor speed used for overspeed violations in counts/sec |
+| `low_position_limit`             | Lower position the drive can move to in position mode, in counts |
+| `high_position_limit`            | Upper position the drive can move to in position mode, in counts|
+| `brake_enage_msec`               | How long it takes to re-engage the brake |
+| `brake_disengage_msec`           | How long it takes to disengage the brake |
+| `crc`                            | CRC of the flashed parameter set |
+| `drive_max_current_limit`        | The fixed, Maximum drive current for the EGD |
+
+`drive_cmd_mode` controls the structure of the Process Data Objects (PDO) exchanged with the device during nominal runtime. The Gold Drive has a fixed limit on the size of the PDO which means that it cannot support all DS-402 commands in the same configuration (in the preferred manner we like to use the drive anyways). 
+The Elmo Platinum Drive does not have this PDO limitation so it will accept all 6 command modes.
+
+`drive_cmd_mode: PROFILED` means that ONLY profiled commands are accepted:
+ - `egd_prof_pos`
+ - `egd_prof_vel`
+ - `egd_prof_torque`
+
+`drive_cmd_mode: CS` means that ONLY Cyclic-Synchronous commands are accepted:
+ - `egd_csp`
+ - `egd_csv`
+ - `egd_cst`
+
+Note: the `GoldActuator` device uses the `Egd` device in `CS` mode. Profiled commands like `ACTUATOR_PROF_POS` are implemented with fastcat-side profiling. 
+
+
+
+``` yaml
+    - device_class:                    Egd
+      name:                            egd_1
+      cs_cmd_freq_hz:                  100
+      drive_cmd_mode:                  PROFILED
+      max_motor_speed:                 50000
+      torque_slope:                    0.25
+      max_profile_accel:               50000
+      max_profile_decel:               50000
+      velocity_tracking_error:         10000000
+      position_tracking_error:         100000000
+      peak_current_limit:              1.5
+      peak_current_time:               0.5
+      continuous_current_limit:        1.0
+      motor_stuck_current_level_pct:   0
+      motor_stuck_velocity_threshold:  0
+      motor_stuck_timeout:             1.0
+      over_speed_threshold:            100000
+      low_position_limit:              0
+      high_position_limit:             0
+      brake_engage_msec:               0
+      brake_disengage_msec:            0
+      crc:                             0
+      drive_max_current_limit:         5
+```
 
 
 

example_configs/one_of_every_device_offline.yaml

@@ -34,8 +34,8 @@ buses:
       crc:                             0
       drive_max_current_limit:         5
 
-    - device_class:                    Actuator
-      name:                            act_1
+    - device_class:                    GoldActuator
+      name:                            gold_act_1
       actuator_type:                   revolute # revolute: eu = radians
       gear_ratio:                      100 
       counts_per_rev:                  500
@@ -53,10 +53,35 @@ buses:
       high_pos_cmd_limit_eu:            3.14159
       high_pos_cal_limit_eu:            3.2 
       holding_duration_sec:            3.0 # chosen arbitrarily
-      egd_brake_engage_msec:           500 
-      egd_brake_disengage_msec:        1000
-      egd_crc:                         12345
-      egd_drive_max_current_limit:     10 # amps
+      elmo_brake_engage_msec:           500 
+      elmo_brake_disengage_msec:        1000
+      elmo_crc:                         12345
+      elmo_drive_max_current_limit:     10 # amps
+      smooth_factor:                   0 # default value is 0
+
+    - device_class:                    PlatinumActuator
+      name:                            plat_act_1
+      actuator_type:                   revolute # revolute: eu = radians
+      gear_ratio:                      100 
+      counts_per_rev:                  500
+      max_speed_eu_per_sec:            10  #rad/sec
+      max_accel_eu_per_sec2:           30  #rad/sec/sec 
+      over_speed_multiplier:           2 
+      vel_tracking_error_eu_per_sec:   1000 # chosen arbitrarily
+      pos_tracking_error_eu:           1000 # chosen arbitrarily
+      peak_current_limit_amps:         10
+      peak_current_time_sec:           3.0 # chosen arbitrarily
+      continuous_current_limit_amps:   5
+      torque_slope_amps_per_sec:       0.5 # amps/sec; chosen arbitrarily
+      low_pos_cal_limit_eu:            -3.2
+      low_pos_cmd_limit_eu:            -3.14159
+      high_pos_cmd_limit_eu:            3.14159
+      high_pos_cal_limit_eu:            3.2 
+      holding_duration_sec:            3.0 # chosen arbitrarily
+      elmo_brake_engage_msec:           500 
+      elmo_brake_disengage_msec:        1000
+      elmo_crc:                         12345
+      elmo_drive_max_current_limit:     10 # amps
       smooth_factor:                   0 # default value is 0
 
     - device_class: El2124

src/CMakeLists.txt

@@ -67,11 +67,10 @@ add_library(fastcat STATIC
     transform_utils.cc
 
     jsd/jsd_device_base.cc
-
     jsd/actuator.cc
     jsd/actuator_fsm_helpers.cc
-    jsd/egd_actuator.cc
-    jsd/epd_actuator.cc
+
+    jsd/ati_fts.cc
     jsd/egd.cc
     jsd/el3208.cc
     jsd/el3602.cc
@@ -81,12 +80,13 @@ add_library(fastcat STATIC
     jsd/el3104.cc
     jsd/el3202.cc
     jsd/el3318.cc
+    jsd/gold_actuator.cc
     jsd/ild1900.cc
     jsd/jed0101.cc
     jsd/jed0200.cc
-    jsd/ati_fts.cc
+    jsd/platinum_actuator.cc
 
-    jsd/egd_actuator_offline.cc
+    jsd/ati_fts_offline.cc
     jsd/egd_offline.cc
     jsd/el2124_offline.cc
     jsd/el4102_offline.cc
@@ -96,11 +96,11 @@ add_library(fastcat STATIC
     jsd/el3104_offline.cc
     jsd/el3202_offline.cc
     jsd/el3318_offline.cc
-    jsd/epd_actuator_offline.cc
     jsd/ild1900_offline.cc
+    jsd/gold_actuator_offline.cc
     jsd/jed0101_offline.cc
     jsd/jed0200_offline.cc
-    jsd/ati_fts_offline.cc
+    jsd/platinum_actuator_offline.cc
 
     ${CMAKE_BINARY_DIR}/fastcat/autogen/fastcat_devices/commander.cc
     fastcat_devices/signal_generator.cc

src/fcgen/fastcat_types.yaml

@@ -76,7 +76,7 @@ states:
     - name: tared_tz
       type: double
 
-  - name: egd_actuator
+  - name: gold_actuator
     fields:
     - name: actual_position
       type: double
@@ -130,7 +130,7 @@ states:
     - name: power
       type: double
 
-  - name: epd_actuator
+  - name: platinum_actuator
     fields:
     - name: actual_position
       type: double

src/jsd/actuator.cc

@@ -673,14 +673,14 @@ std::string fastcat::Actuator::GetFastcatFaultCodeAsString(
 {
   std::string fault_str;
 
-  if (state.type == EGD_ACTUATOR_STATE || state.type == EPD_ACTUATOR_STATE) {
+  if (state.type == GOLD_ACTUATOR_STATE || state.type == PLATINUM_ACTUATOR_STATE) {
     ActuatorFastcatFault fault;
-    if (state.type == EGD_ACTUATOR_STATE) {
+    if (state.type == GOLD_ACTUATOR_STATE) {
       fault = static_cast<ActuatorFastcatFault>(
-          state.egd_actuator_state.fastcat_fault_code);
+          state.gold_actuator_state.fastcat_fault_code);
     } else {
       fault = static_cast<ActuatorFastcatFault>(
-          state.epd_actuator_state.fastcat_fault_code);
+          state.platinum_actuator_state.fastcat_fault_code);
     }
 
     switch (fault) {
@@ -731,13 +731,13 @@ std::string fastcat::Actuator::GetJSDFaultCodeAsString(const DeviceState& state)
 {
   std::string fault_str;
 
-  if (state.type == EGD_ACTUATOR_STATE) {
+  if (state.type == GOLD_ACTUATOR_STATE) {
     auto fault = static_cast<jsd_egd_fault_code_t>(
-        state.egd_actuator_state.jsd_fault_code);
+        state.gold_actuator_state.jsd_fault_code);
     fault_str = std::string(jsd_egd_fault_code_to_string(fault));
-  } else if (state.type == EPD_ACTUATOR_STATE) {
+  } else if (state.type == PLATINUM_ACTUATOR_STATE) {
     auto fault = static_cast<jsd_epd_fault_code_t>(
-        state.epd_actuator_state.jsd_fault_code);
+        state.platinum_actuator_state.jsd_fault_code);
     fault_str = std::string(jsd_epd_fault_code_to_string(fault));
   } else {
     fault_str = "State is not an Elmo actuator type.";
@@ -750,12 +750,12 @@ bool fastcat::Actuator::IsJsdFaultCodePresent(const DeviceState& state)
 {
   bool fault_present = false;
 
-  if (state.type == EGD_ACTUATOR_STATE) {
-    if (state.egd_actuator_state.jsd_fault_code != JSD_EGD_FAULT_OKAY) {
+  if (state.type == GOLD_ACTUATOR_STATE) {
+    if (state.gold_actuator_state.jsd_fault_code != JSD_EGD_FAULT_OKAY) {
       fault_present = true;
     }
-  } else if (state.type == EPD_ACTUATOR_STATE) {
-    if (state.epd_actuator_state.jsd_fault_code != JSD_EPD_FAULT_OKAY) {
+  } else if (state.type == PLATINUM_ACTUATOR_STATE) {
+    if (state.platinum_actuator_state.jsd_fault_code != JSD_EPD_FAULT_OKAY) {
       fault_present = true;
     }
   } else {
@@ -771,10 +771,10 @@ bool fastcat::Actuator::IsJsdFaultCodePresent(const DeviceState& state)
 double fastcat::Actuator::GetActualPosition(const DeviceState& state)
 {
   double actual_position;
-  if (state.type == EGD_ACTUATOR_STATE) {
-    actual_position = state.egd_actuator_state.actual_position;
-  } else if (state.type == EPD_ACTUATOR_STATE) {
-    actual_position = state.epd_actuator_state.actual_position;
+  if (state.type == GOLD_ACTUATOR_STATE) {
+    actual_position = state.gold_actuator_state.actual_position;
+  } else if (state.type == PLATINUM_ACTUATOR_STATE) {
+    actual_position = state.platinum_actuator_state.actual_position;
   } else {
     ERROR(
         "GetActualPosition must be called on states of Elmo actuator "