SDK installation

Use a versioned package when it contains the API your integration needs. For source integration, use a checkout pinned to a tested commit or release. Repository APIs may be newer than published packages; use documentation from the same revision.

OpenAxis SDKs work with Rotatrix devices. Device verification is handled automatically. OpenAxis 1.0 and later require Rotatrix 1.6.0 or newer; see Rotatrix compatibility.

Choose your language below. To work from the repository, obtain a checkout. Checkout commands run from the OpenAxis repository root unless noted.

Python

Requires Python 3.11 or newer. Install the published prerelease:

python -m pip install --pre openaxis

For development against a source checkout:

python -m pip install -e py/openaxis

Use an exact tested package version in your application’s dependency configuration. Editable installation is for development; package the SDK and its dependencies into the integration’s runtime environment for distribution.

C#

The SDK targets .NET Framework 4.8 and .NET Standard 2.0 and produces one OpenAxis assembly. The reference raylib application’s requirements are separate from the SDK’s target frameworks.

From your application’s project directory, add a source reference:

dotnet add reference path/to/openaxis/cs/OpenAxis/OpenAxis.csproj

Restore and build with your normal application build. The SDK declares its MessagePack dependency in its project file. Distribute required runtime dependencies with the integration.

TypeScript

Install the package:

pnpm add @openaxis/sdk

Commit your lockfile. The client uses the runtime’s WebSocket API; geometry and protocol helpers are available through separate package exports.

To build the SDK from a checkout, use Node 22.12 or newer and the pnpm version declared in the repository’s package.json:

pnpm install --frozen-lockfile
pnpm -C ts/sdk build

From your application directory, install the built local package with pnpm add ./path/to/openaxis/ts/sdk. Rebuild the SDK after source changes.

C++

Requires C++17 and CMake 3.24 or newer. The C++ SDK is distributed as source and compiled with your application.

Fetch with CMake

Use FetchContent to fetch a pinned release during CMake configuration. This method also requires Git. Add the following to your application’s CMakeLists.txt, after defining the my_app target:

include(FetchContent)
set(OPENAXIS_BUILD_TESTS OFF CACHE BOOL "")
set(OPENAXIS_BUILD_DEMO OFF CACHE BOOL "")
FetchContent_Declare(openaxis
  GIT_REPOSITORY https://github.com/rotatrix/openaxis.git
  GIT_TAG cpp/v1.0.0-rc.1
  SOURCE_SUBDIR cpp
)
FetchContent_MakeAvailable(openaxis)
target_link_libraries(my_app PRIVATE OpenAxis::openaxis)

Use the C++ release tag for the version you have tested, or its full commit SHA for an exact content pin. SOURCE_SUBDIR cpp selects the SDK within the repository.

Use a downloaded archive or checkout

To manage the source yourself, download openaxis-cpp-1.0.0-rc.1.tar.gz from the matching C++ GitHub Release and extract it into a directory such as third_party/openaxis. The archive contains a cpp directory; use that directory in add_subdirectory below. A source checkout or submodule works the same way.

After defining your application’s my_app target:

set(OPENAXIS_BUILD_TESTS OFF CACHE BOOL "")
set(OPENAXIS_BUILD_DEMO OFF CACHE BOOL "")
add_subdirectory(path/to/openaxis/cpp openaxis-build)
target_link_libraries(my_app PRIVATE OpenAxis::openaxis)

Replace path/to/openaxis with the extracted directory or checkout. Configure and build your application normally; CMake builds and links the SDK with it.

Dependencies

CMake looks for installed nlohmann/json 3.11+ and fetches the pinned version if missing. Set OPENAXIS_FETCH_DEPENDENCIES=OFF and provide nlohmann/json locally for an offline build. Linux and macOS also require OpenSSL Crypto; Windows uses the system BCrypt library.

The SDK includes a private, modified IXWebSocket source tree and builds it automatically. It does not use an installed IXWebSocket package. This transport supports plaintext ws:// connections, including the default loopback endpoint; TLS and WebSocket compression are disabled. GLFW, OpenGL and ImGui are needed only for the reference demo.

After installation, follow the Navigation integration guide.

For SDK tests, packaging limitations and parity work, see SDK implementation and parity.

Source checkouts

The public source repository is rotatrix/openaxis. The commands below require a published snapshot accessible to you. Before public publication, use the source checkout supplied for development. Clone a published snapshot for standalone SDK development:

git clone https://github.com/rotatrix/openaxis.git
cd openaxis

Use a tested public release revision and its accompanying documentation. In examples above, replace path/to/openaxis with the path to this checkout, relative to your application project.

Embed as a Git submodule

A submodule is useful for C++ embedding or integrations maintained against SDK source. From your application’s repository root:

git submodule add https://github.com/rotatrix/openaxis.git third_party/openaxis

Check out your tested release commit inside third_party/openaxis, then commit .gitmodules and the third_party/openaxis entry in your application repository. Use third_party/openaxis in the source-reference or CMake instructions above.

Developers and CI cloning your application initialize its pinned dependencies with:

git submodule update --init --recursive

Review and test SDK updates before committing a new submodule revision. Submodules include the whole OpenAxis repository; package consumers do not need one. See Git’s submodule guide.