HEBI C API  0.16
The HEBI C API

Introduction

The basic purpose of the C API is to allow the user to communicate with groups of HEBI modules, either through 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.

Installation/Setup

NOTE: the API is currently supported on Windows (32-bit and 64-bit), OSX, and Linux (x86-64 and ARM) systems.

The API uses CMake to easily generate platform-specific build files for the examples. However, CMake is not needed to use the API or even to build the examples – see the section below for guidance on how to set up a custom build system.

To get started, build and run the example scripts. First unzip the provided examples .zip files, and then unzip the platform-specific API .zip or .tar.gz file into the new directory. (You should now have a "hebi" directory beside the "examples" directory.)

If you choose to use CMake, create a directory to contain your build files (we suggest creating a directory called "build" as a subdirectory in the extracted API folder). From this file, run "cmake <path to API folder root>". If building on Linux ARM or Windows 32 bit systems, you must also suppy a "-DARCH=<arch>" command line parameter, where <arch> is "arm" for Linux ARM systems and "x86" for Windows 32 bit systems.

After this, the process to build and run the program changes depending on the platform and resulting build system. For example, using a standard Makefile, you can run "make examples" to build the example scripts. On Windows with Visual Studio installed, you can open the .sln file and build the "examples" project.

You can then run the scripts by running the generated example executables. Generally, the example scripts will only be useful in conjunction with modules accessible on the network. Depending on the example, you will have to either pass appropriate command line arguments to determine the module or group to use, or modify the hardcoded values in the example itself.

For a fast/easy start, copy one of the existing examples and start from there.

Using the library and API in your project

Integrating the library in your own project follows the basic approach taken by the examples. The steps are:

  1. Add the hebi/include directory to your own project (it can be renamed as necessary) to allow you to reference the library functions from your code.
  2. Add the hebi/lib library binary files to your project to allow you to link your executable against the library. Be sure you choose the appropriate files based on your system.
  3. Add the necessary elements to your build process to reference the include directory and link against the HEBI library as well as pthreads and the system math library.

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. 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++ on Linux):

  1. Add "-I<directory where you put the files from 'include'>" during compilation to ensure the compiled code generates the correct library calls.
  2. Add "-L<directory where you put library> -lhebi -lpthread -lm" 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.