Skip to content

Commit c304016

Browse files
benjamin-tambenjamin-tam
authored
Merge pull request #2 from csiro-robotics/feature/update_readme
Feature/update readme
2 parents 0d5c0ed + c0dd092 commit c304016

File tree

5 files changed

+379
-293
lines changed

5 files changed

+379
-293
lines changed

‎CHANGELOG.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Changelog
2+
3+
* v0.5.11
4+
* Added more Bezier curve functionalities:
5+
* Quadratic Bezier and curve to pass through control nodes.
6+
* Cubic Bezier to pass through control nodes.
7+
* Quartic Bezier to pass through control nodes.
8+
* Added feature to move the leg to desired position based on direct Cartesian coordinates in the robot frame.
9+
* Added topics that subscribes to topics published by Syropod Manipulation package.
10+
* v0.5.10
11+
* Added dynamic tuning of step frequency parameter
12+
* Added each leg workspace generation
13+
* Added correct generation of 'walkspace', fit within leg workspace
14+
* Fixed issues with externally set target/default tip poses
15+
* Refactored published tf tree order for use with perception based odometry
16+
* v0.5.9
17+
* Implemented real-time default tip position modification via topic
18+
* Implemented estimation of gravity vector from IMU
19+
* Added transform publisher between frames: odom, walk_plane, base_link and tip frames
20+
* Added joint torque visualisations
21+
* Added touchdown detection feature using data on tip state topic and tuned using new parameters: touchdown_threshold & liftoff_threshold
22+
* Added feature to find ground contact by extending 2nd half of swing below walk plane (distance defined by parameter step_depth)
23+
* Added feature to align tips with gravity using redundancy of leg or body posing.
24+
* Refactored dynamic parameter tuning such that stopping Syropod is no longer required.
25+
* v0.5.8
26+
* Implemented Plan Execution Mode (Transition to target configuration, body/tip pose/s) (Free Gait/Movement)
27+
* Merged Auto Navigation mode and Cruise Control mode to free up Y Button for Plan Execution Mode
28+
* Added callback and msg for externally setting target tip poses at end of swing period (Adaptive Gait)
29+
* Added feature for multi-configuration-step pack/unpacking
30+
* v0.5.7
31+
* Added Rough Terrain mode which includes the following features:
32+
* Feature to allow tip range value to modify tip trajectory at end of swing to prevent early/late touchdown.
33+
* Posing feature to pose robot body such that the final link of each leg completes swing periods vertically.
34+
* Reworked trajectory engine to allow for vertical tip trajectory at end of swing during wave gait
35+
* Feature to estimate walk plane and pose body accordingly.
36+
* Added TipState message and callback to receive tip force/torque and range
37+
* Consolidated tip force callbacks into single callback with custom message on topic "/tip_states"
38+
* Added visualisations for the estimated walk plane and terrain
39+
* v0.5.6
40+
* Added feature adding cost function to joints approaching limits to ensure joint space loop closure in redundant systems.
41+
* Refactored joint/tip frame position functions and leg current/desired positions - to use pose (i.e. position & rotation)
42+
* Added tip orientation visualisations for debugging
43+
* v0.5.5
44+
* *Online specific foot placement
45+
* v0.5.4
46+
* Modified direct startup sequence to operate in joint space instead of tip space to prevent joints jumping if initialised outside limits.
47+
* Renamed impedance controller to 'admittance controller'
48+
* Removed custom Quat class and instead replaced with Eigen::Quaterniond
49+
* Removed IMU data transformation - SHC now expects IMU data in ROS REP103 coordinate frame
50+
* Removed joint offset parameters - SHC now expects all joint offsetting to be enacted at the motor driver level
51+
* v0.5.3
52+
* Improved Impedance Controller to make use of multi-joint effort values
53+
* Added tip force estimate visualisation
54+
* Added time limit to cruise control feature for use in running experiments.
55+
* v0.5.2
56+
* New iterative search based workspace generation method
57+
* v0.5.1
58+
* New simpler Inverse Kinematics calculation method
59+
* Improved workspace calculation
60+
* v0.5.0
61+
* Name change from simple_hexapod_controller to syropod_highlevel_controller, aka SHC.
62+
* Full refactor of controller.
63+
* Conversion to new coordinate system, adhering to ROS REP103
64+
* Overhaul of generation of robot model using DH parameters.
65+
* Overhaul of inverse/forward kinematics engine to handle up to 5 DOF legs.
66+
* New control scheme (see syropod_remote readme)
67+
* Redesigned start-ip/shut-down sequences.
68+
* New bespoke auto posing system (see config/readme.md)
69+
* Implementation of dynamic_reconfigure for key parameters.
70+
* Modifications to tip trajectory calculations to prevent exceeding workspace.
71+
* Modifications to tip trajectory calculations to maximise stride length and body acceleration.
72+
* Conversion of walk controller parameters from percentage based to real world values (SI units).
73+
* Changes to adhere to ROSCPP style guide.
74+
* v0.4.9
75+
* Added functionality for manual leg manipulation (MLM)
76+
* Posing to keep centre of gravity centred over centre of support whilst manipulating legs
77+
* Added dynamic stiffness on legs adjacent to MLM leg
78+
* Added leg name mapping
79+
* Added leg state message to consolidate all leg debugging topics
80+
* v0.4.8
81+
* Redesigned manual compensation to be controlled using velocity and reset on R3
82+
* Moved compensation and impedance control outside of running state so compensation occurs during startup
83+
* v0.4.7
84+
* Changed gaits to remove 'underlap' that existed for non*dynamic impedance controller
85+
* Moved imu compensation code (and all other compensation code) to pose controller - deleted imuCompensation source file and header
86+
* Redesigned auto-compensation to work for all gaits
87+
* v0.4.6
88+
* Added body height compensation code to offset sinking body height from impedance controller
89+
* Redesigned dynamic stiffness engine for use in impedance controller
90+
* v0.4.5
91+
* Added inclination compensation feature which keeps body centre of gravity centred about the tip positions on inclined terrain
92+
* Refactored how compensation methods combine and interact with each other
93+
* v0.4.4
94+
* Added angular velocity parameter for testing
95+
* Refactored walk-controller velocity calculations
96+
* Added 'real-world' velocity input mode toggled using 'velocity\_input\_mode' parameter
97+
* v0.4.3
98+
* Modified Tripod gait to have no 'underlap' between step cycles
99+
* Modified the way auto/imu compensation interact with manual compensation. Manual compensation now 'stacks' with auto/imu compensation
100+
* Added various debugging publishers
101+
* v0.4.2
102+
* Redesigned tip trajectory engine using 3 quartic bezier curves - tip trajectory is now C2 smooth at zero body acceleration
103+
* Removed redundant transition_period from step cycle and modified gait parameters/characteristics to reflect.
104+
* Added auto-calculation option for linear and angular accelerations of body to ensure safe tip trajectories within bounds
105+
* Added stance_depth parameter which allows vertical tip position component in stance phase of step cycle
106+
* Changed various parameter names in line with new engine
107+
* Added various debugging publishers
108+
* v0.4.1
109+
* Fixed bug with body velocity calculation using minFootprintRadius as a diameter
110+
* Fixed bug with tip position jumping upon gait switch
111+
* v0.4.0
112+
* MAX ICRA paper submission version
113+
114+
Note: Version control commenced at v0.4.0. No changes were logged before this version.

‎README.md‎

Lines changed: 262 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,262 @@
1+
# Syropod High-level Controller
2+
3+
[![Syropod Banner](https://i.imgur.com/QyMTwG3.jpg "CSIRO Robotics")](https://research.csiro.au/robotics/)
4+
5+
[![Version](https://img.shields.io/badge/Current%20version-0.5.11-orange "Version")]() [![License](
6+
https://img.shields.io/badge/License-BSD%2FMIT-blue "License")](https://github.com/csiro-robotics/syropod_highlevel_controller/blob/feature/update_readme/LICENSE)
7+
8+
Syropod High-level Controller (SHC) is a versatile controller capable of generating body poses and gaits for quasi-static multilegged robots.
9+
10+
<p align="center">
11+
<a href="https://research.csiro.au/robotics/our-work/research-areas/legged-robots/"><img alt="Gizmo Wizmo Zero" align="center" width="500" src="https://i.imgur.com/HCrmRDS.gif"/></a>
12+
</p>
13+
14+
## Getting Started
15+
16+
If you haven't looked at the tutorials for using Syropod High-level Controller, see [SHC Tutorials](https://github.com/csiro-robotics/shc_tutorials).
17+
18+
Please refer to the readme in the launch folder of individual platforms for information on setting up the platform for use with Syropod High-level Controller.
19+
20+
Video overview of [OpenSHC](https://youtu.be/-E7-2UMP5XU):
21+
22+
<p align="center">
23+
<a href="https://youtu.be/-E7-2UMP5XU"><img alt="OpenSHC" align="center" width="500" src="https://imgur.com/VBabLVr.jpg"/></a>
24+
</p>
25+
26+
### Requirements
27+
28+
* Ubuntu 18.04 LTS
29+
* ROS Melodic
30+
31+
### Dependencies
32+
33+
* syropod_highlevel_controller requires a robot specific configuration and launch repository such as [Bullet Syropod](https://github.com/csiro-robotics/bullet_syropod) to run. Please refer to that readme for more information.
34+
35+
### Installation
36+
37+
```bash
38+
mkdir -p openshc_ws/src
39+
cd openshc_ws/src
40+
git clone https://github.com/csiro-robotics/syropod_highlevel_controller.git
41+
cd ..
42+
catkin build
43+
```
44+
45+
### Publications
46+
47+
The details of OpenSHC is published in the following article:
48+
49+
*Benjamin Tam, Fletcher Talbot, Ryan Steindl, Alberto Elfes, and Navinda Kottege, "OpenSHC: A Versatile Multilegged Robot Controller", [arXiv:2006.04424](https://arxiv.org/abs/2006.04424) [cs.RO], June 2020*
50+
51+
#### How to cite
52+
53+
```bibtex
54+
@article{tam2020openshc,
55+
title={OpenSHC: A Versatile Multilegged Robot Controller},
56+
author={Benjamin Tam and Fletcher Talbot and Ryan Steindl and Alberto Elfes and Navinda Kottege},
57+
year={2020},
58+
eprint={2006.04424},
59+
archivePrefix={arXiv},
60+
primaryClass={cs.RO}
61+
}
62+
```
63+
64+
## Features
65+
66+
<p align="center">
67+
<a href="https://research.csiro.au/robotics/our-work/research-areas/legged-robots/"><img alt="Bullet Syropod" align="center" width="500" src="https://i.imgur.com/cHAZ10Y.gif"/></a>
68+
</p>
69+
70+
* Fully configurable for a variety of platform designs with differing physical characteristics, including up to eight legs each with up to 5 degrees of freedom.
71+
* Four dynamically switchable gait options (Wave, Amble, Ripple and Tripod) plus ability to easily design custom gaits. (see config/readme.md)
72+
* User defined body clearance, step clearance and step frequency.
73+
* Manual body posing in 6 degrees of freedom.
74+
* Manual leg manipulation - select up to two legs simultaneously and toggle manual manipulation of either tip position in Cartesian space or direct control of joint positions (3DOF legs only).
75+
* Choice between two modes of start-up:
76+
* Direct mode which move leg tip positions linearly from initial position to default walking stance positions.
77+
* Full chain of start-up/shutdown sequences which allow a Syropod to start from a 'packed' state and generate a sequence to stand up off the ground into its default walking stance. Similarly able to shut-down and transition back to a packed state.
78+
* Optional impedance controller with dynamic leg stiffness to ensure leg contact with ground and offer a degree of rough terrain walking ability.
79+
* Optional IMU body compensation which uses IMU data to keep body horizontally level at all times.
80+
* Optional inclination compensation which strives to keep body centre of gravity over the estimated centre of support whilst walking on inclined planes.
81+
* Optional bespoke automatic body posing system which poses each robot leg cyclically as defined by auto-pose parameters. (see config/readme.md)
82+
* Cruise control mode which may either force a constant predefined input velocity for the Syropod or set the current input velocity as constant.
83+
* Auto navigation mode which when combined with the correct sensing capabilities and running syropod_auto_navigation node, give autonomous navigation with obstacles avoidance to an input waypoint.
84+
85+
## Config Files
86+
87+
For information on parameters see [readme.md](config/readme.md) in config folder.
88+
89+
## Nodes
90+
91+
### syropod_highlevel_control
92+
93+
#### Subscribed Topics
94+
95+
##### [syropod_remote](https://github.com/csiro-robotics/syropod_remote)
96+
97+
* System State:
98+
* Description: The desired state of the entire Syropod High-level Controller system.
99+
* Topic: */syropod\_remote/system\_state*
100+
* Type: std_msgs::Int8
101+
* Robot State:
102+
* Description: The desired state of the robot.
103+
* Topic: */syropod\_remote/robot_state*
104+
* Type: std_msgs::Int8
105+
* Desired Velocity:
106+
* Description: The desired body velocity of the robot.
107+
* Topic: */syropod\_remote/desired\_velocity*
108+
* Type: geometry_msgs::Twist
109+
* Desired Pose:
110+
* Description: The desired body pose of the robot.
111+
* Topic: */syropod\_remote/desired\_pose*
112+
* Type: geometry_msgs::Twist
113+
* Posing Mode:
114+
* Description: The desired manual body posing input mode.
115+
* Topic: */syropod\_remote/posing\_mode*
116+
* Type: std_msgs::Int8
117+
* Pose Reset Mode:
118+
* Description: The desired manual body pose reset mode.
119+
* Topic: */syropod\_remote/pose\_reset\_mode*
120+
* Type: std_msgs::Int8
121+
* Gait Selection:
122+
* Description: The desired gait selection for the walk controller of the robot.
123+
* Topic: */syropod\_remote/gait\_selection*
124+
* Type: std_msgs::Int8
125+
* Cruise Control Mode:
126+
* Description: The desired cruise control mode.
127+
* Topic: */syropod\_remote/cruise\_control\_mode*
128+
* Type: std_msgs::Int8
129+
* Auto-Nagivation Mode:
130+
* Description: The desired auto-navigation mode.
131+
* Topic: */syropod\_remote/auto\_navigation\_mode*
132+
* Type: std_msgs::Int8
133+
* Primary Leg Selection:
134+
* Description: The desired leg selected for primary manipulation.
135+
* Topic: */syropod\_remote/primary\_leg\_selection*
136+
* Type: std_msgs::Int8
137+
* Primary Leg State:
138+
* Description: The desired state of the leg selected for primary manipulation.
139+
* Topic: */syropod\_remote/primary\_leg\_state*
140+
* Type: std_msgs::Int8
141+
* Primary Tip Velocity:
142+
* Description: The desired tip velocity for the leg selected for primary manipulation.
143+
* Topic: */syropod\_remote/primary\_tip\_velocity*
144+
* Type: geometry_msgs::Point
145+
* Secondary Leg Selection:
146+
* Description: The desired leg selected for secondary manipulation.
147+
* Topic: */syropod\_remote/secondary\_leg\_selection*
148+
* Type: std_msgs::Int8
149+
* Secondary Leg State:
150+
* Description: The desired state of the leg selected for secondary manipulation.
151+
* Topic: */syropod\_remote/secondary\_leg\_state*
152+
* Type: std_msgs::Int8
153+
* Secondary Tip Velocity:
154+
* Description: The desired tip velocity for the leg selected for secondary manipulation.
155+
* Topic: */syropod\_remote/secondary\_tip\_velocity*
156+
* Type: geometry_msgs::Point
157+
* Parameter Selection:
158+
* Description: The desired parameter selection for possible adjustment.
159+
* Topic: */syropod\_remote/parameter\_selection*
160+
* Type: std_msgs::Int8
161+
* Parameter Adjustment:
162+
* Description: The desired adjustment of the selected parameter (increment/decrement).
163+
* Topic: */syropod\_remote/parameter\_adjustment*
164+
* Type: std_msgs::Int8
165+
166+
##### syropod_manipulation
167+
168+
* Primary Leg Tip Pose:
169+
* Description: The desired pose for the leg selected for primary manipulation within Cartesian space.
170+
* Topic: */syropod_manipulation/primary_tip_pose*
171+
* Type: geometry_msgs::Pose
172+
173+
* Secondary Leg Tip Pose:
174+
* Description: The desired pose for the leg selected for secondary manipulation within Cartesian space.
175+
* Topic: */syropod_manipulation/secondary_tip_pose*
176+
* Type: geometry_msgs::Pose
177+
178+
##### Motor and Sensor Inputs
179+
180+
* IMU Data:
181+
* Description: The input data from onboard IMU.
182+
* Topic: */imu/data*
183+
* Type: sensor_msgs::Imu
184+
* Tip State Data:
185+
* Description: Custom message containing force/torque and range sensor data at the tip of each leg.
186+
* Topic: */tip\_states*
187+
* Type: syropod_high-level_controller::TipState
188+
* Joint State Data:
189+
* Description: The actual state of joints within the Syropod as published by hardware.
190+
* Topic: "*/joint\_states*
191+
* Type: sensor_msgs::JointState
192+
193+
#### Published Topics
194+
195+
##### Dynamixel Motor Interface
196+
197+
* Desired Joint Position (per joint)
198+
* Description: Desired joint position for each individual joint.
199+
* Topic: */syropod/\*LEG_ID\*\_\*JOINT_ID\*\_joint/command*
200+
* Type: std_msgs::Float64
201+
* Desired Joint State (combined)
202+
* Description: Desired joint state array for all joints.
203+
* Topic: */desired\_joint\_state*
204+
* Type: sensor_msgs::JointState
205+
206+
##### Miscellaneous
207+
208+
* Body Velocity:
209+
* Description: The desired velocity of the robot body.
210+
* Topic: */syropod_highlevel_controller/body\_velocity*
211+
* Type: geometry_msgs::Twist
212+
* Body Pose:
213+
* Description: The desired pose of the robot body.
214+
* Topic: */syropod_highlevel_controller/pose*
215+
* Type: geometry_msgs::Twist
216+
* ASC Hexapod State: (To be removed)
217+
* Description: ASC Hexapod specific message for toggling of magnetic feet (bool of whether each leg is in stance state or not)
218+
* Topic: */leg\_state\_\*LEG_ID\*\_bool*
219+
* Type: std_msgs::Bool
220+
* Leg State:
221+
* Description: The leg state message combines several leg specific data for use in debugging.
222+
* header: Header with timestamp
223+
* name: Leg designation
224+
* walker_tip_pose: Desired tip pose generated from the walk controller (walk_plane frame)
225+
* target_tip_pose: Future desired tip pose at end of swing period (walk_plane frame)
226+
* poser_tip_pose: Desired tip pose generated from the pose controller (base_link frame)
227+
* model_tip_pose: Desired tip pose finalised by the model inverse/forward kinematics (base_link frame)
228+
* model_tip_velocity: Desired tip velocity finalised by the model inverse/forward kinematics (model).
229+
* joint_positions: Array of desired joint positions for each joint.
230+
* joint_velocities: Array of desired joint velocities for each joint.
231+
* joint_efforts: Array of desired joint efforts for each joint.
232+
* stance_progress: Progress along stance state (0.0->1.0 OR -1 if not in stance)
233+
* swing_progress: Progress along swing state (0.0->1.0 OR -1 if not in swing)
234+
* time_to_swing_end: Time until this leg completes swing period.
235+
* pose_delta: The estimated change in pose of the walk_plane frame with regard to world frame from current time to end of swing period.
236+
* auto_pose: The automatic cyclic posing applied to this leg from the auto-pose system.
237+
* tip_force: Tip force vector used in impedance control calculations
238+
* admittance_delta: Vertical tip position offset - output of admittance control.
239+
* virtual_stiffness: Current virtual stiffness used in admittance control calculations
240+
* Topic: */shc/\*LEG_ID\*\_leg/state*
241+
* Type: syropod_highlevel_controller::LegState (custom message)
242+
243+
## Changelog
244+
245+
See [CHANGELOG.md](CHANGELOG.md) for release details.
246+
247+
## Authors
248+
249+
* Fletcher Talbot
250+
* Ryan Steindl
251+
* Thomas Molnar
252+
* Thomas Lowe
253+
* Oshada Jayasinghe
254+
* Navinda Kottege
255+
256+
## License
257+
258+
This project is licensed under the CSIRO Open Source Software Licence Agreement (variation of the BSD / MIT License) - see the [LICENSE](LICENSE) file for details.
259+
260+
## Issues
261+
262+
Please report bugs using [Issue Tracker](https://github.com/csiro-robotics/syropod_highlevel_controller/issues) or contact us via email [[email protected]](mailto:[email protected]).

‎config/readme.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
# Syropod Parameter File
2+
3+
[![Syropod Banner](https://i.imgur.com/QyMTwG3.jpg "CSIRO Robotics")](https://research.csiro.au/robotics/)
4+
25
*config/\*SYROPOD_NAME\*.yaml*
36

47
## Control Parameters:

‎package.xml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@
1616
<depend>std_msgs</depend>
1717
<depend>sensor_msgs</depend>
1818
<depend>geometry_msgs</depend>
19-
<depend>dynamixel_msgs</depend>
20-
<depend>dynamixel_controllers</depend>
2119
<depend>dynamic_reconfigure</depend>
2220

2321
<build_depend>message_generation</build_depend>

0 commit comments

Comments
 (0)