jetsonhacks / fusion-engine-client

FusionEngine client interaction support.

Point One FusionEngine Client

This library provides message definitions and support functionality for interacting with Point One FusionEngine in real time, as well as processing recorded output data. Both C++ and Python are supported.

See http://docs.pointonenav.com/fusion-engine/ for the latest API documentation.

• Requirements
• Directory Structure
  • Example Applications
• Installation
  • CMake
    • Compiling (Linux)
    • Compiling (Windows)
    • Running Examples
  • Bazel
    • Compiling
    • Running Examples
  • Compiling Documentation
• Usage
  • Body Coordinate Frame Definition

Requirements

C++ Support

• C++11 or later
• CMake 3.x or Bazel 3.x
• GCC, Clang, or Microsoft Visual Studio

Python Support

• Python 3.4 or later

Documentation Build Support (Optional)

• Doxygen version 1.8.18
  • Versions 1.8.19 and 1.8.20 have a known issue with enum documentation and do not currently work

Directory Structure

• <root> - Top-level Bazel and CMake build files (C++)
  • examples/ - C++ example applications
  • python/ - Python source files
    • examples/ - Python example applications
    • fusion_engine_client - Top Python package directory
      • messages - Python message definitions
  • src/ - C++ source files
    • point_one/
      • fusion_engine/
        • messages/ - C++ message definitions

Example Applications

The examples/ directory contains example applications demonstrating how to use this library. They are:

• message_decode - Print the contents of messages contained in a binary file.
• generate_data - Generate a binary file containing a fixed set of messages.

Installation

CMake

Compiling (Linux)

Use the following steps to compile and install this library using CMake:

mkdir build
cd build
cmake ..
make
sudo make install

This will generate libfusion_engine_client.so, and install the library and header files on your system. By default, this will also build the example applications.

Compiling (Windows)

Use the following steps to compile and install this library using CMake and MSBuild:

mkdir output
cd output
cmake ..
MSBuild p1_fusion_engine_client.sln

Note: For Windows, we name the build directory output. Windows is not case-sensitive, and build conflicts with the Bazel BUILD file.

Running Examples

By default, the compiled example applications will be located in build/examples/ and can be run from there:

./build/examples/message_decode/message_decode

Bazel

Compiling

To use this library in an existing Bazel project, add the following to your project's WORKSPACE file:

git_repository(
    name = "fusion_engine_client",
    branch = "master",
    remote = "[email protected]:PointOneNav/fusion_engine_client.git",
)

Then add the following dependency to any cc_library() or cc_binary() definitions in your project:

cc_library(
    name = "my_library",
    deps = [
        "@fusion_engine_client",
    ],
)

If desired, you can add a dependency for only part of the library. For example, to depend on only the core message definitions and support code, set your deps entry to @fusion_engine_client//:core.

Note that there is no need to explicitly compile or link this library when using Bazel - it will be built automatically when your application is built. If desired, however, you can build a stand-alone shared library as follows:

bazel build -c opt //:libfusion_engine_client.so

The generated file will be located at bazel-bin/libfusion_engine_client.so.

Running Examples

Note: The /examples directory has been structured like a stand-alone Bazel project to illustrate how to integrate this library into your own project. The bazel-bin/ directory below refers to <root>/examples/bazel-bin/.

To build all example applications, navigate to the examples/ directory and run the following:

bazel build -c opt //:*

Alternatively, you can build individual applications as follows:

bazel build -c opt //message_decode

The generated applications will be located in bazel-bin/. For example:

bazel-bin/message_decode/message_decode message_decode/example_data.p1bin

You can also use the bazel run command to build and run an application in one step:

bazel run -c opt //message_decode -- message_decode/example_data.p1bin

Compiling Documentation

The documentation for the latest release is generated automatically and hosted at http://docs.pointonenav.com/fusion-engine/. If you would like to build documentation locally, simply run doxygen from the repository root directory. The generated output will be located in docs/html/. To view it, open docs/html/index.html in a web browser.

Usage

All FusionEngine messages contain a MessageHeader followed by the payload of the specific message. To decode an incoming message you must:

1. Deserialize the header.
2. Validate the message by checking the CRC (optional).
3. Deserialize the payload indicated by the message_type field in the header.

For example:

#include <point_one/fusion_engine/messages/core.h>

using namespace point_one::fusion_engine::messages;

void DeserializeMessage(const uint8_t* buffer) {
  const MessageHeader& header = *reinterpret_cast<const MessageHeader*>(buffer);
  if (header.message_type == MessageType::POSE) {
    const PoseMessage& contents =
        *reinterpret_cast<const PoseMessage*>(buffer + sizeof(MessageHeader));
    ...
  }
}

See the message_decode example for more details.

Body Coordinate Frame Definition

The platform body axes are defined as +x forward, +y left, and +z up. A positive yaw is a left turn, positive pitch points the nose of the vehicle down, and positive roll is a roll toward the right. Yaw is measured from east in a counter-clockwise direction. For example, north is +90 degrees (i.e., heading = 90.0 - yaw).