search

unitreerobotics / unitree_legged_sdk

SDK tools for control robots.
BSD 3-Clause "New" or "Revised" License
283 stars 156 forks source link

Documentation related to Safety class #65

Open qw8z5fUB opened 1 year ago

qw8z5fUB commented 1 year ago

Hi there, I have a few questions related to https://github.com/unitreerobotics/unitree_legged_sdk/blob/master/include/unitree_legged_sdk/safety.h

Apologies for packing a bunch of questions into a single issue, but as this class relates to safety I'd like to understand it well.

  1. Is there any documentation related to what this class does, beyond the comments in the file?
  2. Can you explain the difference between PositionLimit and PositionProtect?
  3. I assume the basic operation of the class is to alter commands which exceed the defined limits. Related to this: a. How do I know when a limit has been exceeded? Do the protection functions print out a warning? Newer versions of the sdk include an int return variable - does this somehow indicate limit status? b. What is the output behaviour when a limit is exceeded? Is the command set to zero?
  4. For PowerProtect: I understand input factor 10 relates to 100% power - is this equivalent to not setting the limit at all? (i.e. if I'm calling it will factor=10, should I just remove the call altogether?)
  5. Is the purpose of this safety class to prevent damage to the robot actuators? We've seen a couple actuators broken and I'm wondering if it was due to not setting sufficient limits in these protection functions.
  6. Would you consider open-sourcing the implementation of this Safety class? I'd be more comfortable if this was something I could review myself rather than a sparsely-documented black box.
JonasFovea commented 1 year ago

Good questions!

I have a guess for the answer of question 6: No

I haven't had a deeper look into this functionality, but my first assumptions where the same as yours...

qw8z5fUB commented 1 year ago

Note to self, and/or anyone else interested in this, related to question 3.a;

Violating position protection will cause your program to exit, with an error message like:

leg 0 calf: -164.881840                             
leg 1 calf: -187.146668                             
leg 2 calf: -182.498594                                                                                  
Error: Position Protection.

Additionally, violation of power protection causes program exit with error:

Error: Power Protection.

Observed on sdk v3.3.4.

qw8z5fUB commented 1 year ago

Another note, from testing tripping the PositionProtect;

It appears that position protect will trigger when a joint gets within the provided threshold of it's limit.

For instance, the calf joint shows a limit of -155 degrees in the urdf. With position limit set to 0.087 (5 degrees), PositionProtect will trigger and shut down the sdk-client program when the calf joint reaches -150 degrees.

Given PositionProtect takes the current command as an input, I'd assumed it blocked position commands which are far from the current position, but this is not the case based on my testing.

If anyone can confirm or clarify whether these observations are correct, that would be much appreciated.

xyq1223 commented 1 year ago

Hello, No. 1: We are very sorry that there is no documentation on this at the moment No. 2:PositionLimit and PositionProtect are both used for joint position protection, to prevent the user from giving position commands that are greater than the physical limits of the joints, thus protecting the robot. The difference is that PositionLimit selects different limits depending on the type of robot and the limit data is stored in a1_const.h go1_const.h aliengo_const.h. The third parameter of PositionProtect allows the user to customise his own limit data, which is represented by the third parameter of the function in a1_const.h aliengo_const.h. const.h go1_const.h aliengo_const.h, the third parameter of PositionProtect allows you to customize your own limit data.

xyq1223 commented 1 year ago

No. 3: a: If you use the PositionLimit() function, no statement will be output and the function will automatically limit your command. If you use the PositionProtect() function, when protection is triggered it will prompt Error: Position Protection. If you use the PositionProtect() function, the function will return -1 when protection is triggered, or 1 if it is not triggered.

b: The PositionLimit() function will automatically limit your command to the predefined limit data in the a1_const.h go1_const.h aliengo_const.h file, while using the PositionProtect() function ,once the protection is triggered, all motors are taken out of servo mode, or as it is called Braking mode

xyq1223 commented 1 year ago

No. 4: In the PowerProtect() function we have divided the power protection into 10 levels, from 1 to 10, just put the level you want in the third parameter.

xyq1223 commented 1 year ago

No. 5:These functions are designed to prevent damage to the robot motor caused by incorrect user commands,but these are not the only causes of motor damage.

xyq1223 commented 1 year ago

No. 6: Sorry we are not open sourcing Safety class at the moment, if you have any more questions, please feel free to ask again!

qw8z5fUB commented 1 year ago

@xyq1223 thank you for the clarifications. I don't have further questions at this point, feel free to close the ticket if you wish, or it could be left open until this kind of documentation is made available in a more appropriate place (README or sdk docs).

xyq1223 commented 1 year ago

Ok, thank you for your support .