HEBI C++ API  2.0.1
The HEBI C++ API

Introduction

The C++ API provides a more user-friendly interface to the HEBI C API. For those familiar with the C API, the core concepts here are the same.

The purpose of this API is to allow the user to communicate with groups of HEBI modules. This is accomplished by sending commands to the modules or by requesting feedback and other info from the modules.

A good place to start is figuring out how to create a group – this is done through the lookup, which acts as a registry of modules.

Then, look at the basic functionality of a group - how to send commands and receive feedback and other info.

Finally, dig into the details of the command, feedback, and info structures to see all of the information that you can send to and receive from the modules.

Along the way, there are plenty of examples to help you get started – these are a great place to start for those just wanting to jump right in. See github.com/HebiRobotics/hebi-cpp-examples. These will help you get started with compiling and using the API in your own project as well.

Using the library and API in your project

First, note that this library was designed to be used with the C++11 standard, and is not compatible with C++03. Ensure that you have the proper compiler switches to enable this support (e.g., -std=c++11 for gcc).

Integrating the library in your own project follows the basic approach taken by the examples (and looking through the CMakeLists.txt file is a good start). The steps are:

  1. Add the include/ and src/ directories to your own project (they can be renamed as necessary) to allow you to reference the library functions from your code.
  2. Add the library binary files to your project to allow you to link your executable against the library; ensure this path is referenced at runtime.
  3. Add the necessary elements to your build process to reference the include/src directories and link against the HEBI library (as well as pthreads when running on Linux).

The third step is the tricky one – for projects using CMake, this should be relatively straightforward by following the example of the CMakeLists.txt used for the example code. Of course, your build system may be significantly different, even when using CMake. Basically, the crucial elements are a few command line parameters during compilation and linking of your project (the arguments below assume you are using gcc or g++):

  1. Add "-I<directory where you put the files from 'include'>" and "-I<directory where you put the files from 'src'>" during compilation to ensure the compiled code generates the correct library calls.
  2. Add "-L<directory where you put library> -lpthread -lhebi" during linking to ensure the calls to the library and its dependencies can be resolved. Remember that linking is done left to right, so these should be included after your source files on the command line.
  3. Also, ensure the files in 'src' are passed in as sources during the compilation/linking processes.

API Design/Usage Notes

Generally, users of the C++ API should restrict themselves to the documented public functions of the classes in the C++ API (those in the 'src' directory). There are a handful of public functions which are marked as 'internal'; these must be public due to certain class interactions, but should not be used except by other classes in the API.

Files in the C++ API are able to be modified by the user, but this is not recommended as (1) there may be unintended side effects and (2) future API updates may change these files arbitrarily.

Similarly, users of the C++ API are expected to only access HEBI modules through the C++ API; direct use of the lower-level C API along with the C++ API is not recommended, as the C++ wrappers are designed to prevent memory management pitfalls.