Open-Source Leg

OSL v1.0 Python Controls

Note: This tutorial is for the Dephy Actuator firmware version after September 2019. If you are using a firmware version before September 2019, please refer to this page. Below, you’ll find instructional videos that show how to control the Dephy actuators on the knee and ankle. In general, a single-board computer (e.g. Raspberry Pi) sends reference commands to the actuators via a digital bus, and the actuators execute lower-level servo control such as position control, current control, voltage control, or impedance control. This composition enables the development of state machines or other high-level control architectures. The control examples below, which can be thought of as the basic building blocks, serve as example code to realize your control strategy.

Preparation and Setup

  1. Prepare a functioning Raspberry Pi 4 with instructions here, which provides the required library and needed demo scripts.
  2. Power the Raspberry Pi via the USB-C port on the Pi using a computer, a simple wall outlet, or another power source. Wirelessly connect (i.e. SSH) to the Pi from your computer.  If you have not connected wirelessly to the Pi before, see instructions here.
  3. Read the safety warnings on the Dephy Wiki
  4. For safety precautions, connect Dephy actuators to a power supply and not batteries for preliminary tests. If a power supply is unavailable and batteries must be used, be sure to use low gain values for current and position controls in future tests. It is also recommended the OSL be used with the E-Stop, an emergency stop button that can quickly stop electrical power to the OSL.
  5. Connect the actuators to the Raspberry Pi via the USB port on the Raspberry Pi and the micro-USB port on the actuators–use a USB isolator whenever possible which will help protect the Raspberry Pi and Dephy actuators, in the case of any mishaps.
  6. In the command line of Terminal or PuTTY, type “cd ~/code/Actuator-Package/Python” and press Enter. You are now in the directory with demos.
When using a USB cable to control the actuator, THE USB CONNECTION TO THE BOARD MUST BE STRESS RELIEVED.  Ideally, use a 90 degree connector to minimize the bending moment on the board’s micro-USB connector.  If it does not properly stress relieved, the connector can break off the board, and the entire board becomes useless.

Dephy Actuator Examples

The following examples and demos contain reading data from actuators and commanding actuators with different control laws. The details of demo scripts are in the folder “~/code/Actuator-Package/Python/flexseapython/flexsea_demo“. You can change and experiment with those scripts. Find Ports The Raspberry Pi needs to know which USB port is connected to the Dephy actuator. If there are ever errors in accessing a port, you can run the following command and see which ports are in use.
  1. Turn the Dephy actuator on by pressing the center button, and holding for two seconds.
  2. Type “ls /dev/ttyACM*” and press Enter
  3. If the actuator is plugged in and turned on, there should be an outputs “/dev/ttyACM0”.
  4. If the output shows “ls: cannot access ‘/dev/ttyACM*’: No such file or directory”, make sure the actuator is on and connected to the Raspberry Pi.
  5. Open the communication configuration file with an editor by type “nano flexseapython/com.txt” and press Enter.
  6. Edit the second line to be “/dev/ttyACM0“. Press “Control+x”, “y”, and then Enter to save settings.
ReadOnly Demo The Read Only demo outputs the sensor data from the Dephy actuators.  This is an example of the data you can acquire using the actuators.
  1. Make sure you are at the folder “~/code/Actuator-Package/Python”. If not, type “cd ~/code/Actuator-Package/Python” and press Enter
  2. Type “python3 fxMain.py” and press Enter. The outputs show the library path used and the demo options.
  3. Type “0” and press Enter to start the Read Only demo.
  4. The terminal will output the sensor reading as follows.
  5. Press “Control+c” to quit out of the demo, or wait 6 seconds for the demo automatically ends.
Note:
  • In the 48th line of the script “readonly.py”, “time” is the duration of the demo and “time_step” is the interval of reading from the actuator.
  • With the actuator used by the OSL, the demo script calls the printing function “printActPack” on line 14.
Position Control Demo Position control is one of the internal controller modes within the Dephy actuator to hold the actuator at the desired position (angle). This feedback controller mode requires commands to provide controller gains and a reference position. In this demo, the controller is commanded to hold a single position by the Raspberry Pi, and the controller effort can be felt by interacting with the output shaft.
  1. Type “python3 fxMain.py” and press Enter.
  2. Type “1” and press Enter to start the Position Control demo.
  3. Rotate the actuator, and observe the resistance and how it returns to its initial position.
  4. Press “Control+c” or wait 5 seconds to quit out of the demo.
Note:
  • In the 25th line of the script “positioncontrol.py”, the function “fxSetGains” is used to set controller gains for the particular device. The detail could be referred to the webpage (API of the actuator library) or the python library wrapper “flexseapython/pyFlexsea.py”.
  • In the 27th line, the function “fxSendMotorCommand” is used to set a certain type of controller and the reference point for the actuator.

Two Position Control Demo The Two Position Control demo provides an alternating reference signal, toggling between two position targets.
  1. Type “python3 fxMain.py” and press Enter.
  2. Type “2” and press Enter to start the Two Position Control demo.
  3. The actuator will toggle between two positions while the Raspberry Pi commands two reference positions alternatively.
  4. Press “Control+c” or wait 5 seconds to quit out of the function.
Note:
  • In the 17th line of script “twopositioncontrol.py”, “delta” is the angle between two positions and “transition_time” is the switching interval.
  • The unit can reference to Wiki page from Dephy.

Open Speed Control demo The Open Speed demo directly controls the actuator PWM duty cycle, which is another internal controller mode of the Dephy actuator. In this example, the speed (i.e. PWM duty cycle) is a trapezoid, ramping the speed up to a constant velocity, then reducing the speed back to zero.
  1. Type “python3 fxMain.py” and press Enter.
  2. Type “3” and press Enter to start the Open Speed Control demo.
  3. Press “Control+c” or wait 15 seconds to exit out of the function.
Note:
  • In the 8th line of the script “opencontrol.py”, “maxVoltage” is the maximum voltage that the actuator will ramp up to.
  • In the 12th line, the argument “FxVoltage” indicates the actuator is set as the voltage control mode.

Impedance Control Function Impedance Control enables the actuator to prescribe a set of dynamics between the input (position) and output (motor current, as a proxy for torque). This controller needs two more gains (stiffness K and damping B) representing the desired dynamics. In this demo, the actuator holds a position with increasing damping dynamics.
  1. Type “python3 fxMain.py” and press Enter.
  2. Type “4” and press Enter to start the Impedance Control demo.
  3. Try to rotate the actuator to a different angle. You can notice the desired stiffness when rotating the motor and the desired damping when releasing the motor.
  4. Press “Control+c” or wait 10 seconds to exit out of the function.
Note:
  • In the 25th line of the script “impedancecontrol.py”, the script specifies the parameters of desired dynamics in function “fxSetGains”.
  • In the 27th line, the argument “FxImpedance” indicates the actuator is set as the impedance control mode.

Current Control Function The Current Control tracks a reference current, which is analogous to torque control. Similar to the other closed-loop control strategies, the reference is provided by the high-level Raspberry Pi, and the loops are closed on the drive. If there is no external torque placed on the actuator, then the motor will continue to accelerate. Be sure to slow down the motor every once in a while so as not to reach too high of speeds.
  1. Type “python3 fxMain.py” and press Enter.
  2. Type “5” and press Enter to start the Impedance Control demo.
  3. As the actuator accelerates, provide an external torque to slow it down every few seconds. You can also feel the torque from the actuator.
  4. Press “Control+c” or wait 5 seconds to exit out of the function.
Note:
  • In the 21st line of the script “currentcontrol.py”, the argument “FxCurrent” indicates the actuator is set as the current control mode.

Two Devices Position Control Demo You can also command multiple actuators with different control modes for each actuator in a single script. In this demo, we control two actuators to track fixed positions with Position Control respectively.
  1. Connect the second actuator to your Raspberry Pi and power the actuator on.
  2. To control multiple actuators, the communication config file (mentioned in Find Port session) needs to specify the corresponding port name for each device. Follow the above session and should see more items such as “/dev/ttyACM1” in the output of the command “ls /dev/ttyACM*”.
  3. Add the port name showed in the output (/dev/ttyACM1) below the first port name (/dev/ttyACM0). An example is provided in a file named “flexseapython/com_two_devices.txt”.
  4. Type “python3 fxMain.py” and press “Enter”.
  5. Type “6” and press “Enter” to start the Two Devices Position Control demo.
  6. The two actuators will track the current positions. Rotate the actuators, and observe the resistance and how they return to the initial positions.
  7. Press “Control+c” or wait 10 seconds to exit out of the function.
Note:
  • For multiple actuators, you can set gains and controller mode for each controller, such as line 32 to 36 in the script “two_devices_positioncontrol.py”.

Two Devices Impedance Control Demo In this demo, the Raspberry Pi commands two devices to follow certain position pattern with impedance control mode.
  1. Set up the second actuator as the process in Two Devices Position Control demo.
  2. Type “python3 fxMain.py” and press “Enter”
  3. Type “7” and press “Enter” to start the Two Devices Impedance Control demo.
  4. Press “Control+c” or wait 12 seconds to exit out of the function.

Leader-Follower Demo The leader-follower demo shows a possible interaction between two devices, where the follower actuator keeps track of the position of leader actuator. In every time step, the Raspberry Pi reads the position of leader actuator and send the corresponding position command to the follower actuator. You can create other relation between two devices based on this demo.
  1. Set up the second actuator as the process in Two Devices Position Control demo.
  2. Type “python3 fxMain.py” and press “Enter”
  3. Type “8” and press “Enter” to start the Leader-Follower demo.
  4. Try to rotate the leader actuator, and observe the follower actuator rotates correspondingly. Also, try to rotate the follower actuator, while it will try to stay at the position of leader actuator.
  5. Press “Control+c” or wait 10 seconds to exit out of the function.
Note:
  • In the 36th line of the script “two_devices_leaderfollower.py”, the leader actuator is set to track zero current in current control mode, enabling you to rotate the actuator freely.
  • In the 40th line, the follower actuator is set as the position control mode.

OSL Demo – Homing Routine

Showing how to implement some of the above functions on the OSL, this demo will find the limit of each OSL joint and output the reading from the motor encoder and joint encoder. The homing routine commands the OSL to move the joint until the physical limit for both sides.
  1. Change the directory by type “cd ~/code/Actuator-Package/Python/OSL_demo” and press Enter
  2. Edit communication configuration file “com_knee.txt” to match the device port
  3. Type “python3 setup_knee.py” and press Enter
  4. Observe the knee perform its homing routine
  5. Edit communication configuration file “com_ankle.py” to match the device port
  6. Type “python3 setup_ankle.py” and press Enter
  7. Observe the ankle perform its homing routine