API Reference¶
Lookup¶
The following classes are used to retrieve information about modules discovered on the network.
Viewing Discovered Modules¶
Group¶
A group is the interface through which you can communicate with the modules
by sending commands and receiving data. Group commands are not created
directly - they are returned from methods in the Lookup class, as
well as from the create_imitation_group() function. An
imitation group can be created without any modules, mainly for testing
and prototyping purposes. See Imitation Group.
IPython Issues¶
Some IDE and development tools such as Jupyter Notebook and Spyder use a Python command shell called IPython. IPython is a very useful tool which unfortunately creates some subtle issues if used with this API.
Currently, the only known issue is when a script is run multiple times
while the user assigns a Group
object from the script into the running environment repetitively.
For example, assume the following commands are input within a running IPython instance:
In [1]: run ./your_script.py
In [2]: group1 # This is a group instance from your python script run above
Out[2]: <string representation of group1>
In [3]: run ./your_script.py
group1 is saved to a hidden variable in IPython named Out.
If the command at In [2] was not executed, there would be no leaking
of the group instance referenced by group1 -
rerunning the script would reference a different group and allow the original one to be disposed.
However, because group1 is saved to the dict named Out, it will stay alive until
it is explicitly deleted. This can become problematic if done repetitively, especially
if the groups have a high feedback frequency set.
One way to resolve this issue is to use a function called util.clear_all_groups().
This function explicitly disposes of all current group instances created by the API.
However, it is generally recommended that you ensure to not allow multiple group instances, which refer to the same modules, to be run simultaneously.
Kinematics¶
Robot Model¶
The Robot Model interface is used to create a kinematic body on which one can perform subsequent forward and inverse kinematics computations.
HRDF Importing¶
Metadata¶
A RobotModel contains metadata for each component of the kinematic body.
Using the metadata property on an instance, one can retrieve a list of all metadata comprising the body.
All metadata elements are guaranteed to have the following properties:
type, which returns an enum value
is_dof, which returns a boolean
The type property returns an enum value corresponding to the type of element it represents. All possible values are:
hebi.robot_model.enums.RobotModelElementTypeActuator
hebi.robot_model.enums.RobotModelElementTypeBracket
hebi.robot_model.enums.RobotModelElementTypeJoint
hebi.robot_model.enums.RobotModelElementTypeLink
hebi.robot_model.enums.RobotModelElementTypeRigidBody
hebi.robot_model.enums.RobotModelElementTypeEndEffector
Using this property, you can determine what fields are present on a metadata object.
Objective Functions¶
These functions are meant to be used with the
RobotModel IK solver.
Trajectory Planning¶
Creating Trajectories¶
To create a trajectory, a simple interface is provided.
Trajectory Objects¶
Arm¶
The arm API is a high level interface intended to be used with robotic chains which have a simple (i.e., non-tree) topology. As the name suggests, this interface is best suited for robotic arms. This API encapsulates the module communication and kinematic description, while also exposing a few tunables and state associated with common kit use cases.
Components¶
Arm¶
End Effector¶
An arm can optionally have an end effector associated with it.
Plugins¶
Plugins provide extra functionality for the arm, through an interface which
is essentially a collection of callbacks invoked by the arm on certain methods.
To add a plugin to an existing arm, one can simply add it via arm.Arm.add_plugin().
Some plugin implementations are provided:
Creating an Arm Object¶
Utility Functions and Objects¶
Miscellaneous functions which don’t fall under any other category appear here.
Mobile IO¶
Notice: This API is considered experimental and may change in ways which may break backwards compatibility in future versions.
Creating a MobileIO Instance¶
Mobile IO Classes¶
Imitation Group¶
An imitation group is an instance of a Group
which provides all of the same methods and attributes of a group
representing a physically connected collection of HEBI modules
on a local network. However, the imitation group differs in implementation
due to the fact that it represents a virtual collection of modules.
Contrasted to Physical Group¶
For simplicity, think of the “physical” group returned from a lookup operation as a PhysicalGroup and the imitation group returned from this function as an ImitationGroup.
Commands¶
While both interfaces allow for commands to be sent, there is no network communication involved in the ImitationGroup implementation. Consequently, any commands sent to an imitation group will be visible immediately.
For example:
group = create_imitation_group(3)
print('Position:')
# Prints [0.0, 0.0, 0.0]
print(group.get_next_feedback().position)
# Move modules in group
cmd = GroupCommand(group.size)
cmd.position = [4.0, 2.0, -2.0]
# Send command, which will be visible immediately
group.send_command(cmd)
# Prints [4.0, 2.0, -2.0]
print(group.get_next_feedback().position)
Info¶
An ImitationGroup will never return info. In fact, any calls to
Group.request_info() will return None. A PhysicalGroup should always
return valid info.
Feedback¶
An ImitationGroup will always have feedback available - i.e., calling
Group.get_next_feedback() on an ImitationGroup will always return feedback
immediately. In contrast, a PhysicalGroup requires a non-zero feedback
frequency, or the Group.send_feedback_request() function to be called. To achieve
some level of deterministic behavior, the feedback in an ImitationGroup
is always set to an initial state, which is basically a set of sane values
for each field in a GroupFeedback object.
Therefore, the following code is valid with the imitation group:
group = create_imitation_group(3)
print('3 Positions:')
# Prints the same position 3 times ([0.0, 0.0, 0.0])
print(group.get_next_feedback().position)
print(group.get_next_feedback().position)
print(group.get_next_feedback().position)
The default feedback frequency for an imitation group is 0. This means that any attached feedback handlers will not be invoked when the object is in its initial state. You must explicitly set the feedback frequency to a positive number if feedback handlers are desired. Remember that unless commands are actively being set, the feedback data will be the same exact value on every feedback handler invocation.