Overview

HEBI provides modular robotic building blocks that let you build and program custom robotic systems quickly. We provide physical actuators, digital and analog interface boards, and the mechanical and electrical hardware to connect these components together (see our hardware documentation).

Just as important as the hardware, HEBI also provides software tools and APIs to program and control the robotic system created from these physical components.

Start with one of the following options to get started with your HEBI components:

  • Run through the X-Series Quickstart to hook up and move an actuator, no programming required.

  • Start with one of the customizable HEBI kits complete with example MATLAB code to hit the ground running, and then modify to suit your needs.

  • Pick your favorite programming language, and get started with our code examples:

  • Jump into the full tutorial and documentation for each API for more information and advanced concepts:

Quickstart Guides

X-Series Actuator

Getting Started

actuator and wires

The following instructions are meant to get you up and running quickly if you are new to HEBI X-Series actuators. If you have any questions please:

Download the Scope GUI

Go to docs.hebi.us and get the latest version of the Scope GUI for your computer (Windows, macOS, Linux).

Connect Ethernet

plugging ethernet
DHCP example

Connect a standard ethernet cable to either one of the RJ45 ports on the module. Connect the other end of the cable to a router or switch on your local area network (LAN).

Modules ship by default configured to run on DHCP. This means that to work correctly there needs to be a router on the network configured for DHCP.
It is important to use a wired ethernet connection between your computer and modules for maximum reliability. A wireless connection will work, and is generally still useful for viewing feedback in the Scope GUI. However, there will be some amount of packet loss and increased latency that may cause issues with motor control.

Connect Power

plugging power

Using the provided cabling, or any other compatible Molex Mini-Fit Jr. connectors, plug in the power connection to the module.

Do not hot-plug the modules. Connecting and disconnecting the power while the power is on will cause sparking and may damage the module. Only connect and disconnect the power connector when power is off.

Turn On Power

Turn on the power supply, or connect/activate batteries. The modules run on any DC voltage source between 24V-48V.

An X-Series actuator module can draw up to 50W-150W at peak power, but draws less than 2W at idle. Typical continuous power draw for most applications is much lower than the peak power draw, usually 10W-20W. It is important to choose an appropriate power supply for your application. See the Power section of the online documentation for more information.
application led

The Status LED will start blinking green/orange while the actuator is obtaining an IP address. After a few seconds, the LED will change to a slow green fade. Once the module is in this state it will respond to commands and provide feedback from its internal sensors.

If the actuator does not get an IP address, make sure that your network has a router configured for DHCP. Some corporate and institutional networks may also have network security features set up that can interfere with DHCP and/or UDP broadcast, which can create cases where modules are assigned IP addresses but will not be visible in Scope or the APIs. If you suspect this is the case please talk with your network administrator.

Open the Scope GUI

WelcomeTab

When Scope opens, it will show the Welcome Tab, which provides an overview of useful key-combinations for navigating the interface.

InfoTab

You can then select a device on the list from the left side and display its information in the Dashboard Tab.

Play Around

MonitoringTab

Feel free to play with the module to get a feel for its capabilities. In the lower section of the Monitoring Tab in Scope there are sliders for controlling position, velocity, and effort. There are also buttons in the upper section of the Monitoring Tab for plotting feedback from the various sensors in the module.

Wiring up Multiple Modules

two actuators

The X-Series actuators are designed to be quickly wired and chained together to make assembling full robotic systems as easy as possible. When connecting multiple modules:

  • The ethernet connection can be daisy-chained thru the modules. It does not matter which ports are used to daisy-chain.

  • The power connection needs to be split external to the module, using the provided power splitters or using other custom wiring.

Mechanically Mounting Modules

The X-Series actuators have threaded holes for M5 metric screws on their top and bottom sides for mounting. If you are using standard HEBI connection parts, the appropriate hardware is provided.

Be careful to use the appropriate length screws when mounting the actuators. Using screws that are too long may damage the actuator if they are tightened while bottomed out in the threaded holes.

Sending Commands

ActuationDemo

Commands section of the Monitoring Tab has sliders for commanding different aspects of an actuator’s motion.

The details of how an actuator will respond to commands will depend on the Control Strategy and the gains on the module. Out of the box, an actuator will start up in Control Strategy 3, with gains that perform well under light loads. For heavier loads or multi-DOF systems the actuator gains will likely have to be tuned for the specific application. Actuator control and tuning is a complex topic and it is detailed more completely in the online documentation in the Motor Control section.

You can view the both commanded and feedback position, velocity, and effort by clicking the corresponding button in the upper portion of the Monitoring Tab.

Position Control

The top slider in the Commands section controls the output position of the actuator in radians. Dragging the slider will send new position commands.

Velocity Control

The middle slider in the Commands section controls the output velocity of the actuator in radians / second. Dragging the slider will send new velocity commands, causing the actuator output to turn continuously.

Effort (Torque) Control

The bottom slider in the Commands section controls the output effort of the actuator. For the X-Series actuators this is the output torque in Newton-meters. Dragging the slider will send new effort commands.

Torque control can be a somewhat unintuitive at first. A commanded torque in one direction can cause the output of an actuator to spin up to its maximum speed until sees a load that allows it to exert the commanded torque.

Viewing Feedback

FeedbackDemo

Position / Velocity / Effort (Torque)

You can view the both commanded and feedback position, velocity, and effort by clicking the corresponding button in the upper portion of the Monitoring Tab.

Gyro / Accelerometer

Every module has an internal 3-axis accelerometer and 3-axis gyro. Together these sensors are often called an inertial measurement unit (IMU).

The gyro measures the angular velocity of the module in radians / second. The accelerometer measures a combination of gravity and the module’s linear acceleration in meters / second2.

Current / Voltage

Each module senses its bus voltage, reported in units of volts, It also senses the current draw of the motor at the bus voltage, and the winding current through the windings of motor, both reported in units of amps.

Temperature

Each module reports back an ambient temperature, which is the temperature of the electronics in the module. Acuators also report back a modeled winding temperature, bulk actuator temperature, and motor sensor temperature, all in degrees Celcius.

The winding temperature in particular informs a safety controller where motor power may be limited if it is too high. Watching the plot of winding temperature (the red line in the Scope GUI) is good indication of where you are running withing the actuator’s performance envelope.

Next Steps

After becoming familiar with the basic functions of an actuator, there are multiple ways to control the actuators and configure their behavior.

Scope GUI

The Scope GUI provides a much wider range of capabilities for configuring, controlling, and testing out modules than what is covered above. It is a good starting point for learning about actuation and control in general, and it is an important tool for debugging during devlopment.

API We provide APIs for programmatically controlling the modules from a variety of progamming languages. Choose whichever language you are most comfortable with and get started with the examples in Github.

FAQ

General

Do the HEBI APIs support real time control?

Yes. Each HEBI module run a real time operating system (RTOS) in the module itself that process commands and feedback at 1 kHz. This allows the APIs to provide a much more flexible soft-real time control from a computer over a standard Ethernet network. Under normal conditions on a wired LAN a module will show no packet loss, and round-trip latency of 1-2ms. Our APIs provide sub-millisecond synchronization of modules and API-level command/feedback rates of up to 1 kHz, although most applications only need to operate at about 100 Hz. More technical details can be found on our blog.

Other than a computer, what do I need to have to connect to a module?

The only other things you need are access to a wired ethernet network. There are no separate controllers / converters. Each module ships configured for DHCP so you will typically need a router that provides DCHP, at least to start.

How many modules can I have on a network?

The only limits are the same constraints of a standard ethernet network, which easily supports hundreds of modules. We have thoroughly benchmarked the performance of 40 of our modules running at 1 kHz (10x the usual update rate).

Do you have CAD models available for the actuators and accessories?

Yes, please go to cad.hebi.us. There you can find simplified CAD models of the actuators, and models most of our accessories.

API

Which API should I use?

It depends. It is probably best to start the with language you are most comfortable in. If you are just starting out in programming, the Python API or Matlab API are probably good choices. The full list of supported APIs can be found here.

Do you have a ROS API?

Yes. We have a ROS API as well as a C++ API.

Is there example / starter code for the various APIs?

Yes. We provide example code and tutorials on Github.

Scope

Can I run Scope in parallel with the APIs?

Absolutely. Scope is designed to run in conjunction with anything you may be doing from the API, from either the same or a different computer. The plotting tools in particular are an extremely useful tool for online configuring, tuning, and debugging.

X-Series Actuator

Are the actuators environmentally rated (dust/water protection, vibration)?

The X-Series actuators are meant primarily for indoor use. The primary dust/water ingress points are the ethernet and power connectors on the modules. However some customers have used the X-Series actuators successfully outdoors, for example in an agricultural environment. In this situation the customer created their own 3D-printed housing to seal the power and ethernet connections on the side of the actuators.

What is the maximum temperature that a HEBI module can withstand?

The actuators can run at ambient temperatures up to 50º C. The actuator will have decreased performance at these temperatures, but it will not overheat or shut down. Above this temperature the electronics may shut down due to temperature limits. The internal temperature of the electronics is reported in the actuator feedback.

How hot do the housings of the actuator get?

The housing of an X-Series actuator can theoretically get to about 80 deg-C at near the motor if the module is stalled at full power for several minutes. In our testing here we have seen the housings of an X8 actuator get as high as 65 deg-C.

How fast (at what rate in Hz) can you command the actuators?

You can command up to 1kHz, although for our typical applications we control the actuators at around 100Hz. In general with a controlled wired network, the command and feedback rates are limited by the OS you are running. From macOS / Linux you can get reliable communication up to 1 kHz. On Windows you can get get reliable communication up to about 600 Hz.

What types of sensor feedback do actuators provide and, at what rate (in Hz) can you access this feedback?

All the sensors in the actuator can be accessed at up to 1kHz. These include typical feedback related to motion control like output position, velocity, torque, IMU, motor winding temperatures, voltage, current. We also provide a large amount of additional feedback like hardware timestamps, the status LED color, various internal temperatures, and internal motor velocity.

What is the actuator’s control bandwidth / roll-off frequency / frequency response?

The actuators have a roll-off frequency of about 5-30Hz, depending on the model of the actuator, the gains that set on the actuator, and the details of the commanded motion. Bode plots of the actuators under different load conditions are available in the hardware documentation.

What is the spring stiffness / compliance characteristics of the actuators?

The stiffness depends on the actuator and ranges from about 70 Nm/rad to about 170 Nm/rad. Details are provided in the hardware documentation. The stiffness in all the actuators is approximately linear.

What is the repeatability of the output motion of an individual actuator?

The repeatability of a single module is effected by the module’s load, speed, gains, etc. The actuator’s inherent backlash can be a factor when the output axis is unloaded, or when loads change direction. However, backlash has very little effect when the actuator is preloaded in one direction, for example, when it is holding up a load against gravity.

Kits

Is there example/starter code for the kits?

Yes. We provide example code for the various kits on Github.

When is a shunt regulator needed?

A shunt regulator is a good idea if you are powering off of a standard DC power supply and you expect a system to absorb large amounts of energy. For example, an arm moving a fairly heavy payload would need to absorb a lot of energy if it speeds the load up to a high velocity and then decelerates quickly. Some battery-powered systems may not need a shunt regulator.

What is the accuracy/repeatability of various arms?

Repeatability and accuracy of an arm will depend on the exact configuration, payload, and controller tuning. For the typical tasks we’ve tested we see repeatability of around +/- 2-3 millimeters and accuracy of around +/- 1-2 centimeters.

Shorter arms and arms with fewer DoF will tend to have better accuracy and repeatability. Arms and systems where that are tuned more for compliance and ‘soft’ interaction with the world will tend to be less repeatable than one that is tuned to be more ‘stiff’ for good position control.