MIP SDK

Welcome to the official MIP Software Development Kit.

If you have any questions or run into any issues, please let us know! MicroStrain Support Portal

Features

• Send commands using a single function

• Suitable for bare-metal microcontrollers

  • Minimal code size and memory footprint
  • No dynamic memory allocation
  • No dependence on any RTOS or threading

• Simple to interface with existing projects

  • FindMip.cmake is included for CMake-based projects

• It can be used to parse offline binary files

• C++ API for safety, flexibility, and convenience.

• C API for those who can't use C++

• Advanced Features

  • MIP packet creation
  • MIP packet parsing and field iteration
  • Data field deserialization

Examples

See the examples directory for more details

Documentation

Documentation for all released versions can be found here.

C and C++ APIs

The C++ API is implemented on top of the C API to provide additional features:

• Object-oriented interfaces
• Improved type safety and sanity checking
• Better clarity / reduced verbosity (e.g. with using namespace mip)

The C++ API uses TitleCase for types and camelCase for functions and variables, while the C api uses snake_case naming for everything. This makes it easy to tell which is being used.

The C API can be accessed directly from C++ via the mip::C namespace.

Command Results

MIP devices return an ack/nack field in response to commands to allow the user to determine if the command was successfully executed. These fields contain a "reply code" which is defined by the MIP protocol. This library additionally defines several "status codes" for situations where an ack/nack field is not applicable (i.e., if the device doesn't respond to the command, if the command couldn't be transmitted, etc.).

See the documentation page for Command Results for details.

Timestamps

To implement command timeouts and provide time of arrival information, this library requires applications to provide the time of received data. The time must be provided as an unsigned integral value with reasonable precision, typically milliseconds since program start time. By default, the timestamp type is set to uint64_t, but some embedded applications may wish to change this to uint32_t via the MICROSTRAIN_TIMESTAMP_TYPE define. Note that wraparound is permissible if the wraparound period is longer than twice the longest timeout used by the application.

See the documentation page for Timestamps.

Communications Interfaces

Two connection types are provided with the MIP SDK to make it easy to use on both Windows and Unix systems.

Serial Port

A basic serial port interface is provided in C and C++ for Linux, Mac, and Windows. The user can modify these for other platforms. The serial port connection will be used in most cases when the MIP device is connected via a serial or USB cable (the USB connection acts like a virtual serial port).

Enable it in the CMake configuration with -DMICROSTRAIN_ENABLE_SERIAL=1.

TCP Client

The TCP client connection allows you to connect to a MIP device remotely. The MIP device must be connected via the normal serial or USB cable to a computer system running a TCP server which forwards data between the serial port and TCP clients.

Enable it in the CMake configuration with -DMICROSTRAIN_ENABLE_TCP=1.

How to Build

Prerequisites

• A working C compiler
  • C11 or later required
  • Define MICROSTRAIN_ENABLE_CPP=OFF if you don't want to use any C++. Note that some features are only available in C++.
• A working C++ compiler, if using any C++ features
  • C++14 or later is required.
  • C++20 or later for metadata
• CMake version 3.10 or later (technically this is optional, see below)
• Doxygen for building documentation

CMake Build Configuration

The following options may be specified when configuring the build with CMake (e.g. cmake .. -DOPTION=VALUE):

CMake Option	Default	Description
MICROSTRAIN_LOGGING_MAX_LEVEL	MICROSTRAIN_LOGGING_LEVEL_TRACE_	Max log level the SDK is allowed to log. If this is defined, any log level logged at a higher level than this will result in a noop regardless of runtime configuration. Useful if you want some logs, but do not want the overhead compiled into the code.
MICROSTRAIN_TIMESTAMP_TYPE	uint64_t	Overrides the default timestamp type. See Timestamps in the documentation.
MICROSTRAIN_ENABLE_CPP	ON	Causes the src/cpp directory to be included in the build. Disable to turn off the C++ api.
MICROSTRAIN_ENABLE_EXTRAS	ON	Builds some higher level utility classes and functions that may use dynamic memory.
MICROSTRAIN_ENABLE_SERIAL	ON	Builds the included serial port library.
MICROSTRAIN_ENABLE_TCP	ON	Builds the included socket library (default enabled).
MICROSTRAIN_BUILD_PACKAGE	OFF	Adds a package target to the project that will build a .deb, .rpm, or .zip file containing the library
MICROSTRAIN_BUILD_EXAMPLES	OFF	If enabled, the example projects will be built.
MICROSTRAIN_BUILD_TESTS	OFF	If enabled, the test suite will be compiled and linked.
MICROSTRAIN_BUILD_DOCUMENTATION	OFF	If enabled, the documentation will be built with doxygen. You must have doxygen installed.
MICROSTRAIN_BUILD_DOCUMENTATION_FULL	OFF	Builds internal documentation.
MICROSTRAIN_BUILD_DOCUMENTATION_QUIET	ON	Suppress standard doxygen output.
MIP_LOGGING_MAX_LEVEL	MICROSTRAIN_LOGGING_LEVEL_TRACE_	Max log level the SDK is allowed to log. If this is defined, any log level logged at a higher level than this will result in a noop regardless of runtime configuration. Useful if you want some logs, but do not want the overhead compiled into the code.
MIP_ENABLE_DIAGNOSTICS	ON	Adds some counters to various entities which can serve as a debugging aid.
MIP_ENABLE_METADATA	ON if supported	Builds metadata for MIP commands. If not set, the system will try to determine if C++20 is available to enable it. C++20 is required for the metadata module.
MIP_ENABLE_EXTRAS	MICROSTRAIN_ENABLE_EXTRAS	Builds some higher level utility classes and functions that may use dynamic memory. (default MICROSTRAIN_ENABLE_EXTRAS)

Compilation

1. Create the build directory (e.g. mkdir build).
2. In the build directory, run cmake .. <options>
   • Replace <options> with your configuration options, such as -DMICROSTRAIN_ENABLE_SERIAL=1.
   • You can use cmake-gui .. instead if you'd prefer to use the GUI tool (and have it installed).
   • An alternative generator may be used, such as ninja, code blocks, etc. by specifying -G <generator>
3. Invoke cmake --build . in the build directory
4. (Optional, if MICROSTRAIN_BUILD_PACKAGE was enabled) Run cmake --build . --target package to build the packages.

Running the test suite

Automatically (preferred)

The test suite uses CTest, which has good support for various development environments. How to run it depends on what you are using, but most IDEs provide a target such as "All CTest".

Manually

Navigate to the build directory and execute the following commands:

ctest -C CONFIG --verbose --output-on-failure --parallel

CONFIG should be replaced with the configuration that was built, such as Debug or Release.

Building without CMake

If your target platform doesn't support CMake, you can build the project without it. To do so, include all the necessary files and define a few options.

Minimum Required Files for building without CMake

C only

• All source files in src/c/microstrain, except logging.c if logging is disabled
• Source files in src/c/microstrain/connections for your required connection types
• All source files in src/c/mip and src/c/mip/utils
• All source files in src/c/mip/definitions (or at least all the required descriptor sets)

C++

• The C files indicated above, except those in definitions (they can be added too but aren't required)
• Source files in src/cpp/microstrain/connections for your required connection types
• All source files in src/cpp/microstrain
• All source files in src/cpp/mip/definitions (or at least the required descriptor sets)
• Source files in src/cpp/mip/extras as needed for your project
• Source files in src/cpp/mip/metadata if using metadata

Note: When using MSVC with C++, build the C and C++ code separately as libraries. Some C and C++ files have the same name, and MSVC will try to compile both to the same object file. This causes one to be overwritten by the other. Building as separate libraries causes the object files to be placed in different subdirectories, avoiding the conflict.

Required #defines for building without CMake

Pass these to your compiler as appropriate, e.g. arm-none-eabi-gcc -DMICROSTRAIN_TIMESTAMP_TYPE=uint32_t -DMICROSTRAIN_LOGGING_MAX_LEVEL=MICROSTRAIN_LOGGING_LEVEL_WARN_

These definitions must be set when building the MIP SDK sources and for any code that includes MIP SDK headers.

Name	Description
MICROSTRAIN_LOGGING_MAX_LEVEL	Enables/Disables logging more detailed messages (e.g. debug tracing) to improve performance.
MICROSTRAIN_TIMESTAMP_TYPE	Type to use for mip::Timestamp / mip::Timeout. Defaults to uint64_t if not defined.
MICROSTRAIN_USE_STD_ENDIAN	Define to 1 to enable the use of std::endian from C++20.
MIP_LOGGING_MAX_LEVEL	Enables/Disables logging more detailed messages (e.g. debug tracing) to improve performance.
MIP_ENABLE_DIAGNOSTICS	Enables diagnostic counters.

These options affect the compiled code interface and sizes of various structs. They MUST be consistent between compiling the MIP SDK and any other code that includes headers from the MIP SDK. (If you change them after building, make sure everything gets rebuilt properly. Normally, CMake takes care of this for you).

Include directories

• src/c
• src/cpp (if using C++)

Other compiler settings

• C++14 or later is required (if using C++)
  • For gcc: --std=c++14
  • For msvc: /std:c++14
  • Use C++17 or later if using metadata.
• If building TCP socket support on Windows, link against ws2_32.lib.

How to use the pre-packaged libraries

• Available Modules:
  • microstrain
  • microstrain_extras (CPP only)
  • microstrain_recording_connection (CPP only)
  • microstrain_serial
  • microstrain_socket
  • mip
  • mip_extras (CPP only)
  • mip_metadata (CPP only)

Including the packages using CMake

We have included CMake find_package config files with the package for easy project integration.
The simplest way to include all desired modules is to find the MIP package and request the desired modules as components.
Each module has an associated config file which defines <NAME>_LIBRARY <NAME>_LIBRARIES and <NAME>_INCLUDE_DIRS.
When using find_package, the name of the package should be all lowercase.

Minimum requirements for CMake projects

• Include the installation directory in CMAKE_PREFIX_PATH (Usually not required on Linux)
• Find the package in CONFIG mode
• Link the libraries and include directories to your target/project

# Find the desired package/module
find_package(mip COMPONENTS <list_of_modules> CONFIG)

# Link the libraries
target_link_libraries(<target_name> PUBLIC ${MIP_LIBRARIES})

# Add the include directories
target_include_directories(<target_name> PUBLIC ${MIP_INCLUDE_DIRS})

You may need to add the installation directory to the CMake prefix path if it cannot find the package.
This is usually not required on Linux.

# Set the installation directory to the package
set(MIP_SDK_DIR <path_to_installation_dir>)

# Add the directory to the CMake prefix paths to search for the package
list(APPEND CMAKE_PREFIX_PATH ${MIP_SDK_DIR})

# Find the desired package/module
find_package(...)

Including the packages without CMake

If you want to include the MIP SDK without a CMake project, you will need to include the installation
directory in your project configuration.

Minimum requirements for projects without CMake

• Include the library directory <path_to_installed_package>/lib
• Link the libraries/modules
• Add the include directory <path_to_installed_package>/include/microstrain

Please note, all libraries work with C, but only some work with C++

Known Issues

• suppress_ack=true is not supported.
• The commanded BIT, device settings, and capture gyro bias commands can time out unless the timeout is increased.

See the documentation page for Known Issues.