Skip to content

Install C++ API

This guide walks you through the installation of the PULSAR HRI C++ API, which allows you to programmatically control and interact with PULSAR actuators from C++ applications.

The C++ API is distributed as a prebuilt SDK containing:

  • C++ headers,
  • a compiled shared library,
  • CMake package files,
  • examples,
  • and the pulsar-cli command-line tool.

The current release targets Linux x86_64 systems, mainly Ubuntu/Debian.

Available Packages

PULSAR HRI provides the C++ API in two Linux package formats:

pcp-api-cpp-<version>-linux-x86_64.deb
pcp-api-cpp-<version>-linux-x86_64.tar.gz

Use the .deb package if you are using Ubuntu or Debian.

Use the .tar.gz archive if you want a manual installation in a custom location, such as /opt/pcp_api.

Requirements

The C++ API currently targets Linux x86_64 systems.

Runtime dependency

The C++ API requires libserialport for serial communication.

On Ubuntu/Debian:

sudo apt update
sudo apt install libserialport0

Build tools

If you plan to build examples or your own C++ applications, install:

sudo apt update
sudo apt install build-essential cmake

Serial device permissions

You may need permission to access the USB-CAN adapter device.

On Ubuntu/Debian systems, add your user to the dialout group:

sudo usermod -aG dialout $USER

Then log out and log back in.

You can verify your groups with:

groups

You can check the USB device permissions with:

ls -l /dev/ttyACM0

Option 1: Installation from .deb

For Ubuntu/Debian systems, the recommended installation method is the Debian package.

Download:

pcp-api-cpp-<version>-linux-x86_64.deb

Install it with:

sudo apt install ./pcp-api-cpp-<version>-linux-x86_64.deb

Option 2: Installation from .tar.gz

Use this method if you want to install the SDK manually into a custom folder.

Download:

pcp-api-cpp-<version>-linux-x86_64.tar.gz

Extract it to a location of your choice. For a system-like local installation, /opt/pcp_api is recommended:

sudo mkdir -p /opt/pcp_api
sudo tar -xzf pcp-api-cpp-<version>-linux-x86_64.tar.gz -C /opt/pcp_api

The extracted SDK should contain a structure similar to:

/opt/pcp_api/
├── include/
│   └── pcp_api/
├── lib/
│   ├── libpcp_api.so
│   └── cmake/pcp_api/
├── bin/
│   └── pulsar-cli
└── share/
    └── pcp_api/

Using the C++ API in Your Project

The SDK provides a CMake package, so the recommended way to use it is through find_package.

Create a CMakeLists.txt file:

cmake_minimum_required(VERSION 3.16)
project(my_pulsar_app LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(pcp_api CONFIG REQUIRED)

add_executable(my_pulsar_app main.cpp)
target_link_libraries(my_pulsar_app PRIVATE pcp_api::pcp_api)

Create a simple main.cpp:

#include <iostream>
#include <pcp_api/pcp_api.hpp>

int main() {
    auto ports = pcp_api::PCP_over_USB::get_ports();

    std::cout << "Detected ports: " << ports.size() << std::endl;
    for (const auto& port : ports) {
        std::cout << "  " << port << std::endl;
    }

    return 0;
}

Building When Installed from .deb

If the API was installed using the .deb package, CMake should find it automatically:

cmake -S . -B build
cmake --build build

Run:

./build/my_pulsar_app

Building When Installed from .tar.gz

If the SDK was extracted manually, pass the SDK path to CMake:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/pcp_api
cmake --build build

Run:

LD_LIBRARY_PATH=/opt/pcp_api/lib:$LD_LIBRARY_PATH ./build/my_pulsar_app

Runtime Library Path

If you installed the SDK from the .tar.gz archive, Linux may need help finding libpcp_api.so at runtime.

For temporary use:

export LD_LIBRARY_PATH=/opt/pcp_api/lib:$LD_LIBRARY_PATH

To make this permanent for your shell, add the line above to your ~/.bashrc or equivalent shell configuration file.

If you installed the API using the .deb, you normally do not need to set LD_LIBRARY_PATH.

Checking Package Integrity

If a SHA256SUMS file is provided, verify the downloaded files:

sha256sum -c SHA256SUMS

Run this command in the same folder as the downloaded package files.

Uninstalling

If installed from .deb

sudo apt remove pcp-api-cpp

To remove configuration files as well, if any:

sudo apt purge pcp-api-cpp

If installed from .tar.gz

Remove the installation folder:

sudo rm -rf /opt/pcp_api

If you added LD_LIBRARY_PATH to your shell configuration, remove that line from ~/.bashrc or equivalent.

Troubleshooting

libpcp_api.so: cannot open shared object file

The dynamic library cannot be found at runtime.

If you installed from .tar.gz, set:

export LD_LIBRARY_PATH=/opt/pcp_api/lib:$LD_LIBRARY_PATH

Then rerun your application.

If you installed from .deb, run:

sudo ldconfig

SerialPort: failed to open port /dev/ttyACM0

Your user may not have permission to access the USB serial device.

Add your user to the dialout group:

sudo usermod -aG dialout $USER

Then log out and log back in.

Check the device permissions:

ls -l /dev/ttyACM0

libserialport.so not found

Install the runtime serial communication library:

sudo apt update
sudo apt install libserialport0

For development from source, install:

sudo apt install libserialport-dev

CMake cannot find pcp_api

If installed from .tar.gz, make sure you pass the SDK path:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/opt/pcp_api

Check that the CMake package files exist:

ls /opt/pcp_api/lib/cmake/pcp_api

If installed from .deb, check:

dpkg -L pcp-api-cpp | grep cmake

pulsar-cli: command not found

If installed from .deb, check:

dpkg -L pcp-api-cpp | grep pulsar-cli

If installed from .tar.gz, call the CLI using its full path:

/opt/pcp_api/bin/pulsar-cli --help

or add it to your PATH:

export PATH=/opt/pcp_api/bin:$PATH

Next Steps

Once the C++ API is installed, you can:

  • Use the command-line interface to quickly interact with PULSAR hardware.
  • Build and test the provided examples.
  • Integrate the C++ API into your own CMake projects.
  • Use the generated headers under include/pcp_api/ as the main API reference.
  • Contact the PULSAR HRI support team if you encounter installation or hardware communication issues.