xvisio 0.3.0

ROS-free Python SDK for Xvisio XR-50 and Seer controller devices

XvisioTech Camera Examples

This repository contains the driver and examples for using XvisioTech devices:

• XR-50 - 6DoF SLAM tracking camera with stereo fisheye, RGB, and IMU
• DS-80 - 6DoF SLAM tracking camera with ToF depth sensor
• Seer Wireless Controller - 6DoF motion controller with buttons and joystick

It provides the necessary instructions to install the driver, set up the ROS2 package, and get started with the devices.

ROS-free Python SDK (Recommended for scripting)

This repo includes a ROS-free Python package, xvisio, built with nanobind. It lets you access Pose (SLAM), IMU, and Controller data directly from Python with minimal setup.

Supported devices:

• XR-50 / DS-80 cameras (pose, IMU)
• Seer wireless controller (pose, buttons, joystick)

Quick start (pip install)

# Install from PyPI
pip install xvisio

# Install with visualization examples (includes viser)
pip install xvisio[examples]

# Run system setup (one-time, requires sudo)
sudo xvisio-setup

# Test installation
python3 -c "import xvisio; print(xvisio.discover())"

View the package at pypi.org/project/xvisio/.

Running examples after pip install:

Examples are included in the pip package. Use the xvisio-examples command:

# List available examples
xvisio-examples --list

# Copy examples to local directory
xvisio-examples --copy
cd xvisio_examples
python demo_pose_imu.py

See PIP_INSTALL.md for more details on running examples.

Quick start (source checkout)

1) Clone the repository

git clone https://github.com/xvisiotech/xvisiotech_camera_examples.git
cd xvisiotech_camera_examples

2) Run system setup (one-time, requires sudo)

This installs the USB udev rule and the XVSDK driver .deb:

sudo ./scripts/setup_host.sh

If the script adds you to the plugdev group, log out and log back in once.

3) Install the Python package

pip install -e . --no-build-isolation

4) Run the demo

python examples/demo_pose_imu.py

Or visualize the pose in 3D:

python examples/demo_pose_visualization.py
# Then open http://localhost:8080 in your browser

Or use the Python API directly:

import xvisio

with xvisio.open() as dev:
    dev.enable(slam=True, imu=True)
    pose = dev.pose_world_aligned()
    imu = dev.imu()
    print(pose.position, imu.accel)

Development installation (pixi)

For development, use pixi:

# Install pixi
curl -fsSL https://pixi.sh/install.sh | bash

# Run host setup (one-time, requires sudo)
sudo ./scripts/setup_host.sh

# Install Python package
pixi run install

# Run demo
pixi run demo_pose_imu

See INSTALL.md for detailed installation instructions.

Minimal usage example

Camera (XR-50 / DS-80):

import xvisio

with xvisio.open() as dev:
    dev.enable(slam=True, imu=True)

    pose = dev.pose()
    imu = dev.imu()

    print(pose.position, pose.quat_wxyz, pose.confidence)
    print(imu.accel, imu.gyro)

Seer Wireless Controller:

import xvisio

# Open controller (auto-detects on /dev/ttyUSB0)
dev = xvisio.open_controller()

left, right = dev.controller()
if right:
    print(right.position, right.quat_wxyz)
    print(f"trigger={right.key_trigger}, side={right.key_side}")
    print(f"rocker=({right.rocker_x}, {right.rocker_y}), key={right.key}")

dev.close()

Running tests

• Unit tests (no hardware needed):

pixi run test

• Hardware smoke test (requires a connected device):

XVISIO_HARDWARE=1 pixi run test

For more details on the Python API, see python/README.md.

Version Management and Publishing

The project includes tools for managing versions and publishing wheels to PyPI.

Version Management

Check current version:

pixi run version

Set a specific version:

pixi run version 0.2.0

Bump version automatically:

# Bump patch version (0.1.0 -> 0.1.1)
pixi run version --bump patch

# Bump minor version (0.1.0 -> 0.2.0)
pixi run version --bump minor

# Bump major version (0.1.0 -> 1.0.0)
pixi run version --bump major

Building Distributions

Build wheel and source distribution:

pixi run build-dist

Build wheel only:

pixi run build-wheel

Build source distribution only:

pixi run build-sdist

Publishing to PyPI

1. Test on TestPyPI first (recommended):

# Build distributions
pixi run build-dist

# Upload to TestPyPI
pixi run upload-testpypi

# Test installation (use --extra-index-url to also check PyPI for build dependencies)
pip install --index-url https://pypi.org/simple/ --extra-index-url https://test.pypi.org/simple/ xvisio

2. Publish to PyPI:

# Build distributions
pixi run build-dist

# Upload to PyPI
pixi run upload-pypi

Note: You'll need to configure PyPI credentials in ~/.pypirc before uploading. See PUBLISHING.md for detailed instructions.

For complete publishing workflow and troubleshooting, see PUBLISHING.md.

Instructions (Docker Container) -- Recommended

If your goal is ROS-free Python scripting, use the ROS-free Python SDK section above (pixi + xvisio). This Docker flow is mainly for the ROS2 driver workflow (RViz, ROS topics, launch files).

Prerequisites

Before proceeding with the installation, ensure you have Docker installed on your system. If you don't have Docker installed, you can follow the instructions provided on the official Docker website. Make sure to use apt-get to install it, instead of docker-desktop GUI app installation, as it may not work with the provided scripts.

Docker Setup:

If you haven't done this before, add the user to the docker group:

sudo usermod -aG docker $USER

Log out and log back in for the group change to take effect. Alternatively, run:

newgrp docker

Note that to be able to run examples with GUIs, make sure graphics forwarding (x11) is enabled in your docker settings. We have added this in the provided scripts for convenience, but you may need to enable it manually if you are using a different setup.

xhost +local:docker

Make sure the device is connected to the host machine and the camera is powered on. If you have just received the camera, you may need to update the firmware to the latest version. Please refer to the "Update Firmware" section below for instructions.

Installation

Start the Docker container with the necessary dependencies and the camera driver installed:

./scripts/start_container.sh

Once the docker image is built and the container is started, you can proceed with setting up the ROS2 package in the container.

Test the driver installation by running the following command:

sudo all_stream

This command will display the output of the camera in the terminal. If the camera is connected and working properly, you should see the camera's output in the terminal (pose and IMU signals) and camera images.

To set up the ROS2 package for the XvisioTech camera, follow these steps in the container:

source ./scripts/setup_ros2_driver.sh

Make sure to source the script to set up the ROS2 package in the current shell. Just running the script without source will not set up the ROS2 package in the current shell.

Usage

This script will build the ROS2 package. You can then launch the ROS2 node using the following command in the container:

ros2 launch xv_sdk_ros2 xv_sdk_node_launch.py

To verify the installation and setup, you can listen to the camera's pose topic or visualize it using RViz (in a new shell) as follows:

Open a new shell in the container currently running the ROS2 node:

./scripts/open_shell.sh

You can listen to pose topic in the new shell:

ros2 topic echo /xv_sdk/<camera_serial_id>/pose

<camera_serial_id> is the serial number of the camera that shows up in the topic list (e.g., SNXR501G10002222006246).

You can also visualize the camera pose in RViz (in the new shell):

rviz2 -d ./xvisio-camera-test.rviz

Optional Features

The XvisioTech camera driver supports several optional features that can be enabled or disabled through launch parameters. By default, most features are disabled to reduce CPU usage and bandwidth, except for SLAM pose and button states which are enabled by default. You can enable specific features based on your requirements.

To enable a feature, add the corresponding parameter to the launch command:

ros2 launch xv_sdk_ros2 xv_sdk_node_launch.py <parameter_name>:=true

Available parameters:

• fisheye_enable: Enable fisheye camera images (default: false)
• rgb_enable: Enable RGB camera images (default: false)
• tof_enable: Enable Time-of-Flight depth camera (default: false)
• rgbd_enable: Enable RGB-D combined data (default: false)
• button_states_enable: Enable button state publishing (default: true)
• event_enable: Enable event data publishing (default: false)
• orientation_enable: Enable orientation data publishing (default: false)
• slam_path_enable: Enable SLAM trajectory publishing (default: false)
• slam_pose_enable: Enable SLAM pose publishing (default: true)

For example, to enable fisheye cameras and RGB images:

ros2 launch xv_sdk_ros2 xv_sdk_node_launch.py fisheye_enable:=true rgb_enable:=true

To disable button states (which are enabled by default):

ros2 launch xv_sdk_ros2 xv_sdk_node_launch.py button_states_enable:=false

Enabling these features will make the corresponding topics available for subscription. Disabling them will prevent the topics from being created, reducing CPU usage and network bandwidth.

Update Firmware

If you just received the camera, you may need to update the firmware to the latest version.

To update the camera firmware, use the latest firmware image file in the firmware folder and run the following command inside the container shell (choose the correct firmware file for your camera model):

./xvisioUpdateImg <firmware_file>

Wait until Done is displayed in the terminal to complete the firmware update. After the update is complete, restart the camera by disconnecting and reconnecting the USB cable. Note that this step needs to be done only once.

Instructions with Manual Installation

This section is only for reference. We recommend using the Docker container as it is easier to install and use.

Prerequisites

Before proceeding with the installation, ensure your system is running Ubuntu22.04 and ROS2 Humble.

Updating Ubuntu

Ensure your Ubuntu distribution is up to date, including the latest stable kernel:

sudo apt-get update

Dependency Installation

Install the dependent libraries required for the camera driver:

sudo apt-get update
sudo apt-get install -y tree g++ cmake cmake-curses-gui pkg-config autoconf libtool libudev-dev libjpeg-dev zlib1g-dev libopencv-dev rapidjson-dev libeigen3-dev libboost-thread-dev libboost-filesystem-dev libboost-system-dev libboost-program-options-dev libboost-date-time-dev liboctomap-dev

USB Permissions

Set up USB permissions by downloading the permissions file and copying it to the correct directory:

1. Download 99-xvisio.rules.
2. Open a terminal in the directory where you downloaded the file and run:

sudo cp 99-xvisio.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

The camera driver is now installed and ready to use. You can proceed to the next section to set up the ROS2 package and start using the camera.

Driver Installation

Install the XvisioTech camera driver using the provided Debian package:

sudo dpkg -i XVSDK_jammy_amd64_022324.deb

Test the installation by running the following command:

sudo all_stream

This command will display the output of the camera in the terminal. If the camera is connected and working properly, you should see the camera's output in the terminal (pose and IMU signals) and camera images.

Setting Up ROS2 Package

To set up the ROS2 package for the XvisioTech camera, follow these steps:

1. Create a ros2 workspace (copy the package into existing one) and build the package:

mkdir -p ~/ros2_ws/src
cp xvsdk-ros2 ~/ros2_ws/src/
cd ~/ros2_ws
colcon build --packages-select xv_ros2_msgs
colcon build --packages-select xv_sdk_ros2
source ~/ros2_ws/install/setup.bash

2. Launch the ROS2 node:

ros2 launch xv_sdk_ros2 xv_sdk_node_launch.py

Usage

To verify the installation and setup, you can listen to the camera's pose topic or visualize it using RViz:

• Listen to pose topic:

ros2 topic echo /xv_sdk/slam/pose

• Visualize the camera pose in RViz:

rviz2 -d ./xvisio-camera-test.rviz

The RViz window will open and display the camera's pose in the 3D space. You can also view the images from the camera (fish-eye stereo and RGB images) in the RViz window.

Maintainer

For any issues or inquiries regarding the camera driver and examples, please contact:

Andy Park [e-mail]

References

For more information on the XvisioTech cameras and their features, please refer to the official documentation:

https://www.xvisiotech.com/doc/

Purchasing Xvisio Camera Modules (XR-50, DS-80) on Mouser Electronics Website

Documentation

For detailed information about changes between versions, please see the Changelog.