Modules are connected to host computers via standard Ethernet and standard commercially available networking equipment. In an Ethernet network every client needs to obtain an IP address in order to communicate. There are two ways to get an IP address:

Modules run on DC voltages between 24V-48V. The internal electronics of the modules are designed to properly regulate and automatically scale motor control parameters as the bus voltage changes.

However, if actuators are heavily loaded and are being back-driven or impacting the world with significant amounts of force there may be voltage spikes as energy is sent from a back-driven actuator out into the power system. In these cases we recommend using a shunt regulator, or using a large battery system that can absorb these effects.

The Status LED is a multi-color indicator that provides information about the current state of a module, detailed in the table below. It is located under the white plastic window on the side of the module near the connector. There is also a smaller white LED to the left of the Status LED that indicates that module is receiving power.

You create a Group using a Lookup to see what’s on the network. You can adjust settings like the CommandLifetime and FeedbackFrequency.

Once one or more modules are turned on and plugged into the network they can be discovered by a Lookup that periodically sends broadcast messages on the network. The interval is configurable and by default is set to 5 Hz. Each module has a user-settable Name and Family to help better organize a system on the network. These can be set from the APIs or by right-clicking modules in the left panel in the Scope GUI.

Discovered modules can be combined into a Group that provides a basic way to send commands and retrieve feedback. Groups also handle higher-level issues such as data synchronization and logging. You can also request Info from the modules in a group.

Each module has multiple keys that can be used to identify a module on a given network:

There are no software limits on the number of active groups, the number of modules within a group, or the number of groups that a module is part of. Groups are the only way to communicate with modules using the APIs. Even if you are working with a single module, you will need to create a group for that module.

You get synchronized Feedback from a Group. Once a Group is created, feedback requests automatically go out to all the individual modules and actuators in the group at the FeedbackFrequency and get organized by the API into vectors, matrices, and structures of data corresponding to all the feedback from a single point in time.

You can view the most recent feedback for a group at any time by getting the NextFeedback for the group. The details of how NextFeedback is returned are API-dependent.

Feedback contains things like the position/velocity/effort of an actuator, the states of various input/output pins of an I/O board, and a wealth of other sensors and internal module state. The complete details of what is returned in module feedback is specific to the particular hardware or software application and are documented in the sections below:

You can send Commands to a group, typically desired position, velocity, and effort commands for actuators to execute. These commands are targets for low-level controllers that run on an actuator. Commands are typically sent from a loop that runs around 100 Hz, but you can run faster (up to 1kHz) or slower depending on the needs of your application. Generating smooth commands to go from one position to another can be accomplished the Trajectory API.

For safety, each command has a CommandLifetime. This is the maximum duration that a command may be active before it expires. If the hardware does not receive further commands within the specified time frame, all local controllers get deactivated. This is similar to a safety feature that many industrial robots have that requires users to send at least one update every interval (e.g. 5 ms) to keep the robot from turning off and locking up. Since the timeout deadline depends heavily on the application, we chose to implement the inverse approach in which every command specifies its own lifetime.

Additionally, moudles do not accept commands from any other sources during the lifetime of a command. This lock-out mitigates the risk of other users accidentally sending conflicting targets (e.g., by dragging slider in the Scope GUI). The default command lifetime in all APIs is 0.25 sec. You can set CommandLifetime to be any value greater than 0. Setting CommandLifetime to 0 is a special case that disables it. This means that commands sent once will be active on a module indefinitely, and that a module will also accept commands from other sources, since there is no lock-out.

While the timeout can be deactivated, we strongly recommend to make use of this feature. Otherwise, the hardware will continue to execute the last sent command indefinitely, which can result in unwanted behavior, especially when commanding velocities and efforts (torques). Alternatively, we recommend using a hardware button that triggers a motion stop ("M-Stop").

You can log feedback automatically in the background at the group’s FeedbackFrequency. These logs can be loaded into memory or converted into different formats for use with other tools. Each Group can be generating one log at a time. It is possible (and often useful) to have more than one group simultaneously gathering feedback and/or logging from the same modules.

Logs are stored in a binary format and by default are labeled with a .hebilog file extension. Logging begins with a startLog call that returns the path to the .hebilog file and ends with a stopLog call. Calling startLog on a group that is already logging will immediately stop the current log and start a new one. Each API has tools that can load and parse logs into organized formats.

You can also use the APIs to set a number of different module-specific parameters, such as Gains and Safety Limits. See the Hardware Documentation for more detail.

Position, velocity, and effort controllers can be run individually or in any combination simultaneously. To combine these control inputs, PID control loops are used on position, velocity, and effort. These controllers can be cascaded and combined in different preset configurations, termed Control Strategies.

The active Control Strategy and its corresponding parameters can be set using:

In all of the control strategies, a series of safety controllers run after the calculation of the final PWM values (the 'Motor PWM' value in the control strategy diagrams above). These safety controllers will potentially modify the PWM value based on things like the bus voltage, motor winding temperature, motor velocity, and position limits.

The diagram below shows the priority in which the safety controllers run. Safety ontrollers that are applied later in the chain (further to the right in the diagram) take priority over safety controllers that are applied earlier (further to the left). Some of these safety controllers are parameterized and can be set by the user, such as the position safety limits. Other controllers, such as the voltage limit and motor temperature limits, are fixed and are set specifically for a certain type of hardware.

The configurable safety controllers (such as the position limit strategy and its corresponding limit values) can be configured from:

In addition to safety limits, actuators also support a Motion-Stop that can be triggered by pressing an external hardware button. The trigger action can be chosen by setting one of the following m-stop strategies.

Each controller for position, velocity, and effort is a full PID controller that exposes gains for tuning the proportional, integral, and derivative response of the control loop. Additionally, there are are number of other parameters that can be used to modify the response of the loop (see table below), threshold and low-pass the input and output, limit integral windup, set a deadzone region, and provide feedforward commands where appropriate.

A diagram showing the effect of min/max output limits, deadzone, and punch parameters on a standard proportional controller (P-controller) is shown below.

The kinematic structure of the robot can be specified using built-in body types. A body can be either a static component (e.g. link) or a dynamic component (e.g. joint). Currently, our kinematics APIs only support serial chains of these bodies.

Parameterized body types are built-in to each API and correspond to components on our parts list. Please refer to the language-specific API documentation for more information on using these libraries in your application. While the types and parameters for setting up kinematics are consistent across APIs, the concrete implementation does depend on the language.

The first step in using the kinematics API is to configure the robot by adding bodies together in a kinematic chain. The details are API-dependent, but the overall idea is to form of chain of actuated joints, connected by passive links. The APIs have functions for quickly defining and parameterizing HEBI actuators and accessories as well as functions to fully define custom links and joints.

Additionally, you can save and load kinematic descriptions to and from files using the HEBI Robot Description Format.

The last body of the chain is considered to the the end-effector. All the coordinate frames for kinematics are expressed in the BaseFrame. The first body in the kinematic chain is by default at the origin of the BaseFrame. If desired, it can be set to be something different.

Forward kinematics refers to calculating the pose (position and orientation) of various bodies on the robot based on a given configuration (a set of joint positions).

Once the bodies of a robot are configured, the API can return the forward kinematics of the robot for a given set of joint positions as [4 x 4] homogeneous transforms in the base frame. In the case where the frames of multiple bodies are returned (e.g. the output frames of each body in the robot for visualization) they are returned as m [4 x 4] 3D matrix where m is the number of bodies in the robot.

In robotics, the Jacobian, \(\mathbf{J}\), refers to a matrix that relates the velocities, \(\dot{\theta}\), of a robot’s joints, \(\theta\), to the velocities, \(\mathbf{v}\), (both linear and rotational) of various bodies of the robot, the typical case being the body that is the end effector of an arm. It also relates the torque of a robot’s joints, \(\tau\), to the forces and torques, \(\mathbf{f}\), on different bodies.

The Jacobian has the following relationships:

The Jacobian itself is a matrix of partial derivatives, defined at a given set of joint angles. The size of the Jacobian is [6 x n] where n the number of joints (degrees of freedom, of DoF) in the robot. Rows 1-2-3 of the Jacobian relate respectively to the X-Y-Z translation of a body, and rows 4-5-6 relate respectively to the X-Y-Z rotations of a body, all expressed in the base frame.

So in the equations above the vector of forces, \(\mathbf{f}\), and the vector of velocities, \(\mathbf{v}\), are:

Once the bodies of a robot are configured, the API can calculate the Jacobian to all the different bodies for a given set of joint positions. In the case where Jacobians to multiple bodies are returned (e.g. the Jacobians to the center-of-mass of each body in the robot for compensating for the robot’s dynamics) they are returned as m [6 x n] matrices, where m is the number of bodies in the robot.

Inverse kinematics (IK) refers to solving for the [1 x n] vector of joint positions that put the end-effector of the robot in a certain pose (position and/or orientation), where n is the number of joints (or DoF) in the robot. This is in general a harder problem than forward kinematics, as there can frequently be multiple IK solutions for a desired pose. Our approach in the HEBI APIs is to use local optimization to find an approximate solution for joint positions, given an initial 'guess' of joint positions.

The APIs allow you to provide different 'targets' for the end effector for IK solver to try to reach. You can combine multiple targets, e.g. you can solve for both the position and orientation of the end effector by specifying both XYZ and SO3. All poses are expressed in the base frame. You can also specify the InitialPositions for where the optimizer to starts.

HEBI provides a trajectory generator API that creates smooth trajectories between various sets of joint positions (waypoints). These trajectories have the property that they smoothly accelerate and decelerate with "minimum jerk" and are similar to human movement. The generated trajectories are essentially a set of polynomials parameterized by time that can be evaluated to get intermediate positions, velocities, and accelerations that smoothly move between waypoints. The implementation of our trajectory generator is based on methods that have been developed to control small quadrotors.

In addition to position waypoints, there are additional constraints that can be applied so that the trajectory matches velocity and acceleration constraints at the end waypoints or any intermediate waypoints. For example, if you are controlling the swinging of a leg on a robot you can use the trajectory generator to find a smooth sweeping motion that lifts the leg up and puts it down as well as match a desired foot velocities and lift-up and touch-down.

In the table below p is the number of waypoints in the trajectory and n is number of joints (DoF) in the robot.

After a trajectory has been generated, it can be evaluated at any point in time betwen its first and last values in the times vector. Evaluating a trajectory at a given time will return a set of positions, velocities, and accelerations that smoothly move between waypoints.

Requirements:

Block Commutation Typical Duty Cycles

Block Commutation, also known as Six-Step Commutation, drives the motor at a constant voltage. It utilizes a motor’s embedded Hall Effect Sensors to detect the rotor’s electrical position. The hall state is derived from the hall sensor inputs as well as the Hall Order and Hall Offset Scope parameters.

hall_state = [A << 2 | B << 1 | C << 0]

table_index = index[hall_state] + hall_offset

As the motor spins, the hall state will update to reflect the new rotor position. At slow speeds you can watch the hall state tick up (or down, depending on the motor direction) from 0 to 5.

Block Commutation Typical Hall States

The hall state tells us the Motor Driver what index to use in the excitation table (shifted by 3 depending on the direction).

Excitation Table

This commutation strategy results in "blocky" winding currents and noticeable torque ripple.

Block Commutation Typical Current Feedback

Implementation Requirements:

FOC Typical Duty Cycles

Field Oriented Control, often abbreviated to FOC, drives the motor at a constant current. It uses a high-resolution measurement of the rotor position to generate sinusoidal currents in the motor. This results in higher efficiency, torque output, and lower electrical noise.

FOC Typical Currents

All of these advantages don’t come for free - FOC is much more complicated and computationally demanding compared to Block Commutation. FOC requires good current estimates, an encoder calibration, and tuned PI gains.