VKH6 is a medium-sized humanoid robot developed in-house by VKBOTS, standing 1.45 m tall with motion parameters comparable to a human of similar height. It is designed for high-dynamic movement and open-platform development.

Front View	Side View

Key Highlights

• High-Dynamic Motion: 31 VKBOTS hollow planetary joint motors across the body, enabling running, jumping, backflips, and parkour
• Skeletal Lightweight Design: Minimized weight; custom shells can be attached to change appearance and mount additional devices
• High Reliability: Hollow cable routing greatly reduces the wiring harness; built-in fall-resistant design
• High-Speed Bus: PCIE-CANFD with full-body control frequency > 1000 Hz
• Hot-Swap Battery: Replace batteries without powering off, ensuring continuous operation
• Open Development Interface: CANFD MIT protocol for direct motor control + ROS2 SDK + one-click MuJoCo simulation deployment

Full Specifications

Appearance & Motion Performance

Full-Body Joint Parameters

Detailed motor specifications can be found in Joint Actuator Modules.

Mechanical Structure

Degrees of Freedom

Electrical System

Control Communication Architecture

Computing & Perception

Computing Unit - CPU

Computing Unit - GPU

IMU

Sensors & Peripherals

Software Ecosystem

Accessories

This document contains instructions for unboxing, basic operations, safety precautions, and secondary development for the VKH6 robot.
Please read and follow the Robot Safety Instructions and Safety Guidelines before operating the robot

Unboxing Instructions

1. Placement and Unboxing: Open the box face up, remove the surrounding foam, and lift the robot out with at least two people.

   • Pay strict attention to the cable positions during extraction to avoid crushing or tearing.
   • After taking it out, it is recommended to suspend the robot using a hanger or lay it flat on the ground.

2. Backplate Structure Introduction:

   • The following figure shows the robot backplate structure ((backplate and charging-port photo pending)).
   • Upper Display Screen: Shows voltage, reference battery level, and temperature. Press the button on the right side of the screen to wake it up; it will automatically turn off after 10 seconds.
     • Use the voltage value as the main battery-state reference. The percentage / battery bars are for reference only and may not match the actual remaining capacity.
   • Lower Right: The power switch button for the main battery.
   • Upper Body: Charging port.

3. Host System Information:

   • The host operating system of the robot is Ubuntu 22.
   • Username: bxi
   • Password: Contact the supplier to obtain

Power-on and Operation Steps

1. Turn on Battery Power & Host Power

• Press the battery power button. The battery will supply power normally, and the host will also power on simultaneously. Check the voltage value on the backplate display. The percentage / battery bars may be inaccurate, so use the voltage value as the reference.
• Voltage note:
  1. New 58V machines: The backplate display shows the current battery-pack voltage. When fully charged, the voltage is about 58.8V. The voltage gradually decreases during use. If the voltage is clearly low (below 50V), stop and charge the robot first.
  2. Older 48V machines: The backplate display shows the current battery-pack voltage. When fully charged, the voltage is about 48.8V. The voltage gradually decreases during use. If the voltage is clearly low (below 40V), stop and charge the robot first.

Charging Notes

Verify charger output voltage: Connect the charger directly to a power source (without connecting to the robot) and check that the charger display is within the supplier-specified range:

1. Older machines with 48V batteries: The recommended voltage is 48.8V. If it is different, adjust it before connecting the robot.
2. New machines with 58V batteries: The recommended voltage is 58.8V. If it is different, adjust it before connecting the robot.

Note: The percentage / battery bars may be inaccurate. Before powering on or moving the robot, use the voltage value as the primary battery-state reference.

Robot Backplate Charging Port	Charger Diagram

2. Connect Remote Controller

Connect the remote controller to the robot PC via Bluetooth. The controller is pre-paired at the factory. - Long press the Xbox button directly. - Wait for the indicator light below the button to stay solid, which means the controller has successfully connected to the robot PC.

3. Run the Control Program

Watch the operation instruction video carefully. The built-in control program of the robot has multiple modes: Walking, Zero Torque, Initial Posture, Zero-position, High-speed Run, Medium-speed Run, Dance, Recovery, Front Flip (run without dummy hands installed), Clap, Wave, etc., and will be continuously updated.

3.1 Start the Program

(It is recommended to remain suspended): After the robot powers on, wait about 30 seconds for the system to finish starting up, then press the Right Stick (RS/R3) to start the robot. Observe the chest light of the robot; if it lights up, the control program has started running. It enters Zero Torque mode by default. After the chest light turns on, wait about 10 seconds for self-check to complete before switching the robot to Initial Posture, Walking, or other modes.

3.2 Initial Posture Initialization

(It is recommended to remain suspended): - Press RB + B simultaneously to make the robot enter the initial posture. - Check if the robot is normal: Briefly observe if the motors have any anomalies (such as no response or abnormal noises). - Stand the robot up: If everything is normal, stand the robot up in this state, with both feet touching the ground. The operator should assist in maintaining the initial-posture standing state to prevent external forces from disrupting the posture initialization.

3.3 Switch to Motion State

(At this point, initial-posture initialization is complete, it is still recommended to remain suspended, and you can release the lanyard after a successful and stable switch): - Walking State: Press RB + X simultaneously. The robot enters the walking state, where it can move omnidirectionally on flat ground.

Shutdown and De-energization

4.1 Termination Shutdown (De-Energization Button)

• Press Start, the control program will exit automatically, and the robot motors will immediately de-energize. The robot will naturally fall due to gravity. > Note: Before shutdown, place a chair under the robot or hang it on a hanger to ensure it does not fall hard onto the ground.
• Restart: Return to Section 3.1 to restart the program.

Gamepad Motion Control

Remote controller power indicator colors: A solid light means the controller is connected successfully. White indicates 2.4G wireless connection, blue indicates Bluetooth connection, and green indicates USB wired connection. A flashing red battery indicator means the battery is low.

Remote controller mode switch: The mode switch is located on the bottom/back of the controller near the USB-C port. It has three positions: USB, BT, and RF.

• USB: USB wired connection mode, using a USB-C data cable to connect to the PC.
• BT: Bluetooth connection mode, used to connect to the robot PC via Bluetooth.
• RF: 2.4G wireless connection mode, used with a 2.4G USB receiver. The 2.4G USB receiver is located in the controller box by default.

Movement Direction Control

In Walking, High-speed Run, and Medium-speed Run modes, use the following inputs to move the robot:

Custom Program (SDK) Control

For developers who wish to control the robot via custom algorithms, ROS, or other programs.

The operating environment and low-level programs are pre-configured, fully supporting out-of-the-box usage. - SDK and ROS2 example: https://github.com/bxirobotics/bxi_rl_controller_ros2_example

Packing and Transportation

[To be added: insert packing guide images here]

• Avoid Limits: Do not leave joints in mechanical dead zones or extreme limit positions.
• Isolation Protection: Insert original foam cushioning to prevent direct contact between metal casings, especially between two motor housings, during transportation.

I. Safety Notice

1. Familiarize Yourself with Product Features: Before operating the robot for the first time, thoroughly review all relevant documentation to fully understand its functional parameters, operating procedures, range limitations, and safety precautions.

2. Operating Environment Requirements: Place the robot on flat, dry, stable, and obstruction-free surfaces. Do NOT operate in the following environments: high or low temperatures exceeding the product's rated range, humid or dusty areas, surfaces with excessive slope, significant elevation changes, ground prone to collapse or slipping, fragile load-bearing surfaces, or areas with strong vibrations.

3. Regular Maintenance: Conduct regular status checks on the robot, focusing on critical components such as joint motors, sensors, and power systems. If you detect aging, loosening, damage, or abnormal operation of any components, immediately shut down the robot for repair or replacement. Operating the equipment with known faults is strictly prohibited.

4. Master Emergency Stop Operation: Before use, confirm and familiarize yourself with the emergency stop activation method to quickly halt the robot in emergency situations. When emergency stop is triggered, all joints will lose support and the robot will collapse to the ground. Therefore, pay special attention to site safety, and use protective frames throughout the post-emergency stop period. Do not activate the emergency stop unless absolutely necessary.

5. Maintain Safe Operating Area: During robot operation, ensure adequate clearance around the robot (recommended radius >6.5 feet), maintain safe distances from walls, fixed obstacles, personnel, and valuable items, and avoid narrow enclosed spaces, high-traffic areas, and cluttered zones to effectively reduce risks of collision, pinching, and scraping.

6. Electrical Safety: Before powering on, carefully inspect power cables, plugs, outlets, and equipment power interfaces to ensure they are intact with no damage, short circuits, or loose connections. During operation, if the robot exhibits abnormal heating, hot cables, unusual odors, or strange sounds, immediately disconnect the main power supply. Only restart the equipment after identifying and resolving the issue.

7. Avoid Improper Use: Ensure the robot is used only for compliant and reasonable applications. Do not deploy it for dangerous, non-compliant, or legally prohibited purposes.

II. Safety Guidelines

1. Pre-Operation Inspection

• Before powering on or executing motion commands, thoroughly clear the work area of all unauthorized personnel, debris, and obstacles. Pay special attention to areas surrounding the robotic arm, moving joints, and end effectors to ensure no interference or obstruction exists, preventing collisions, personnel injury, or equipment damage during operation.

• Before starting the equipment, verify the robot's status and confirm that all power-on self-check procedures have completed successfully with no fault error messages.

2. Operating Procedures and Training

All operators must receive necessary training in advance, becoming familiar with the robot's usage specifications, operating methods, and emergency response procedures to reduce safety risks caused by improper operation.

3. Maintain Safe Distance

During robot operation, do not manually interfere with its movements. All personnel must maintain a minimum distance of 3 feet from the robot's operating area. When the robot executes rapid movements or heavy-load operations, personnel are strictly prohibited from remaining within the equipment's projected motion trajectory. Do not observe closely or reach out to touch moving components.

When adjusting, servicing, or manually handling the robot, you must first ensure the robot has completely stopped and is in a powered-off state before proceeding.

4. Rated Load and Accessory Use

• Operate the robot within its rated load capacity. Do not perform operations exceeding its design capabilities.

• When using end effectors, gripping mechanisms, or other functional components, ensure they are compatible with the target objects to avoid additional compression, abnormal stress, or component damage caused by incompatibility.

5. Emergency Response Procedures

If the robot experiences stuttering, abnormal movements, loss of control, unusual sounds or odors, system errors, or other sudden hazardous conditions, immediately execute the emergency stop operation via the remote control to terminate equipment motion as quickly as possible.

6. Remote Control Safety Guidelines

• If the robot has or is using remote control functionality, operate under reliable and secure network conditions whenever possible to avoid control instability caused by network interruption, latency, or external intrusion.

• During remote control operations, operators must have real-time monitoring capabilities to continuously track the robot's operating status and on-site environmental conditions, thereby enhancing remote operation safety.

III. Disclaimer

1. Violation of this Safety Notice and Safety Guidelines resulting in personal injury, equipment damage, property loss, or other safety incidents shall be the full responsibility of the liable party.

2. These safety specifications will be revised as needed in accordance with product upgrades, scenario expansion, and regulatory updates for the semi-awake robot.

VKBOTS provides a full-stack open architecture:

• CANFD-based motor hardware control and debugging interfaces
• MuJoCo-based simulation environments, robot URDF/XML resources, and related assets
• ROS2-based hardware management nodes, allowing control policies to be deployed seamlessly to simulation and real hardware
• Reinforcement-learning-based motion control training example code

CAN Bus & CAN ID

The robot has a total of 31 joint motors, distributed across 5 CANFD buses. Each bus corresponds to one body part:

The figure below is the URDF visualization of the robot, with each joint index annotated:

[Pending: insert the URDF visualization image with joint indices annotated here]

The table below lists the joint index, joint name, CAN bus, and CAN ID for every motor. Note that:

• The Joint Index is the index of the joint in the control program's joint/motor array, numbered continuously across the whole body starting from 0.
• The CAN ID is the motor's address on its bus; it increments independently within each bus, starting from 1.

Domain ID

Purpose

The robot control system is built on ROS2, which uses DDS for inter-node communication at its core. ROS_DOMAIN_ID partitions the communication domain:

• Nodes with the same Domain ID can discover each other and exchange topics/services.
• Nodes with different Domain IDs are isolated from each other and do not interfere.

When multiple robots exist on the same local network, or multiple debugging hosts are connected at once, using the same Domain ID causes topic data to cross-talk and leads to abnormal control behavior. Assigning each robot a unique Domain ID isolates each robot's ROS2 communication network from the others.

Default Domain ID

Each robot is configured with a default Domain ID at the factory according to the following rules. The value depends on how the robot is started:

• Gamepad startup: ROS_DOMAIN_ID = generation × 10 + robot serial number. VKH6 is a third-generation product, so the generation number is 3, and the Domain ID is 30 + serial number.
  • Example: elf3-15 → 3 × 10 + 15 = 45
  • Example: elf3-20 → 3 × 10 + 20 = 50
• APP startup: ROS_DOMAIN_ID is fixed at 22.

How to Configure

The Domain ID is set via an environment variable. Run the following in a terminal on the robot host or development host:

export ROS_DOMAIN_ID=45

To apply it automatically on every boot, add the command to ~/.bashrc:

echo "export ROS_DOMAIN_ID=45" >> ~/.bashrc
source ~/.bashrc

Documentation Directory

• ROS2-based control policy deployment framework with seamless deployment to simulation and real hardware: https://github.com/bxirobotics/bxi_rl_controller_ros2_example
• Robot URDF resources: https://github.com/bxirobotics/bxi_rl_controller_ros2_example/tree/main/resources

This document provides motion control development instructions for the VKH6 robot.

Project repository (please read the README carefully): bxi_rl_controller_ros2_example

The bxi_ws folder in the robot controller's root directory contains the motion control program.

Launching the Robot Program

Auto-Start Logic

After the robot controller powers on, the systemd service ros_elf_launch.service automatically starts the robot program. The startup chain has two stages:

1. Auto-start service: ros_elf_launch.service is the boot entry point, responsible for starting the remote controller program remote_controller/remote_conroller_launch.py in the background.
2. Real robot program: The remote controller launch file remote_conroller_launch.py includes the logic to start the real robot program (triggered by pressing the right joystick on the controller). The auto-started real robot program is located by default in ~/bxi_ws/bxi_rl_controller_ros2_example.

Tip: Before debugging a single launch file or custom node, stop ros_elf_launch.service first to avoid conflicts between the background default nodes and your manually started nodes.

Managing the Auto-Start Service

If you are not the root user, prepend sudo to systemctl commands.

# Check service status
systemctl status ros_elf_launch.service

# Start the service
systemctl start ros_elf_launch.service

# Restart the service
systemctl restart ros_elf_launch.service

# Stop the service
systemctl stop ros_elf_launch.service

# Enable auto-start on boot
systemctl enable ros_elf_launch.service

# Disable auto-start on boot
systemctl disable ros_elf_launch.service

Manually Launching a Launch File or Node

Before manually debugging, stop the default service first:

systemctl stop ros_elf_launch.service

Start Simulation Program

source /opt/bxi/bxi_ros2_pkg/setup.bash
cd bxi_ws/bxi_rl_controller_ros2_example
source install/setup.bash
ros2 launch bxi_example_py_elf3 example_demo.launch.py

Start Real Robot Program (⚠️ Pay Attention to Safety)

Programs that interact with the robot's motors require root privileges:

sudo su
source /opt/bxi/bxi_ros2_pkg/setup.bash
cd /home/bxi/bxi_ws/bxi_rl_controller_ros2_example
source install/setup.bash
ros2 launch bxi_example_py_elf3 example_demo_hw.launch.py

After startup, the motors will power on and all motor indicator LEDs will turn green. The robot enters a self-check routine. If the green lights remain on after approximately 6 seconds, the self-check has passed.

Start Remote Controller Program

# Real robot
sudo su
source /opt/bxi/bxi_ros2_pkg/setup.bash
cd /home/bxi/bxi_ws/bxi_rl_controller_ros2_example
source install/setup.bash
ros2 launch remote_controller remote_controller_launch.py

# Simulation
source /opt/bxi/bxi_ros2_pkg/setup.bash
cd ~/bxi_ws/bxi_rl_controller_ros2_example
source install/setup.bash
ros2 launch remote_controller remote_controller_launch.py

To start a single node, after sourcing the environment:

ros2 run <package_name> <executable_name>

Secondary Development Guide

Choosing the Right Modification Level

Start from Level 1: Keep the official motion control program intact and only replace the node that publishes /motion_commands. Only modify the auto-start service or its startup script if you need to change the default boot behavior.

Notes per level:

1. Custom control node: Stop ros_elf_launch.service or the default remote controller node before debugging to avoid multiple nodes publishing control commands simultaneously.
2. Modify launch files and main program: The default programs are located in ~/bxi_ws/bxi_rl_controller_ros2_example/src/bxi_example_py_elf3. After modifying, rebuild, re-source the workspace, and verify with ros2 launch or by restarting the service.

Adding a Custom Controller Node

Step 1: Stop the auto-start service

systemctl stop ros_elf_launch.service
# or
killall remote_controller

Message Type

Once started, the robot subscribes to the /motion_commands topic. The message type is a custom message defined in bxi_ros2_pkg: communication/msg/MotionCommands.

std_msgs/Header header
    builtin_interfaces/Time stamp
        int32 sec
        uint32 nanosec
    string frame_id
geometry_msgs/Vector3 vel_des
    float64 x
    float64 y
    float64 z
float32 height_des
float32 yawdot_des
int32 mode
int32 btn_1  ... int32 btn_10
int32 axis_1 ... int32 axis_10

Step 2: Create a Publisher

C++ Example

1. Create a Package

# Replace my_cpp_pkg with your package name
ros2 pkg create my_cpp_pkg --build-type ament_cmake --dependencies rclcpp std_msgs

2. Write the Node

Create main.cpp under src/:

#include "rclcpp/rclcpp.hpp"
#include "std_msgs/msg/string.hpp"
#include <communication/msg/motion_commands.hpp>

using namespace std::chrono_literals;

class MotionCtrl : public rclcpp::Node
{
public:
    MotionCtrl() : Node("motion_ctrl")
    {
        publisher_ = this->create_publisher<communication::msg::MotionCommands>("/motion_commands", 20);
        timer_ = this->create_wall_timer(500ms, std::bind(&MotionCtrl::timer_callback, this));
    }

private:
    void timer_callback()
    {
        auto message = communication::msg::MotionCommands();
        message.header.stamp = this->get_clock()->now();
        message.header.frame_id = "";
        message.vel_des.x = 0.5;  // forward/backward velocity
        message.yawdot_des = 0.5; // yaw rotation velocity
        publisher_->publish(message);
    }

    rclcpp::Publisher<communication::msg::MotionCommands>::SharedPtr publisher_;
    rclcpp::TimerBase::SharedPtr timer_;
};

int main(int argc, char **argv)
{
    rclcpp::init(argc, argv);
    rclcpp::spin(std::make_shared<MotionCtrl>());
    rclcpp::shutdown();
    return 0;
}

Add the following to CMakeLists.txt:

find_package(communication REQUIRED)
add_executable(cpp_node src/main.cpp)
ament_target_dependencies(cpp_node rclcpp std_msgs communication)

install(TARGETS
  cpp_node
  DESTINATION lib/${PROJECT_NAME}
)

3. Build and Run

colcon build
source install/setup.bash
ros2 run my_cpp_pkg cpp_node

Python Example

1. Create a Package

# Replace my_py_pkg with your package name
ros2 pkg create my_py_pkg --build-type ament_python --dependencies rclpy std_msgs

2. Write the Node

Create my_py_pkg/motion_ctrl.py:

import rclpy
from rclpy.node import Node
from communication.msg import MotionCommands


class MotionCtrl(Node):
    def __init__(self):
        super().__init__('motion_ctrl')
        self.publisher_ = self.create_publisher(MotionCommands, '/motion_commands', 20)
        self.timer = self.create_timer(0.5, self.timer_callback)

    def timer_callback(self):
        message = MotionCommands()
        message.header.stamp = self.get_clock().now().to_msg()
        message.header.frame_id = ''
        message.vel_des.x = 0.5   # forward/backward velocity
        message.yawdot_des = 0.5  # yaw rotation velocity
        self.publisher_.publish(message)


def main(args=None):
    rclpy.init(args=args)
    node = MotionCtrl()
    try:
        rclpy.spin(node)
    finally:
        node.destroy_node()
        rclpy.shutdown()


if __name__ == '__main__':
    main()

Add the dependency in package.xml:

<depend>communication</depend>

Register the entry point in setup.py:

entry_points={
    'console_scripts': [
        'motion_ctrl = my_py_pkg.motion_ctrl:main',
    ],
},

3. Build and Run

colcon build
source install/setup.bash
ros2 run my_py_pkg motion_ctrl

FAQ

1. How to View Logs When the Real Robot Program Fails to Start

Official program logs are stored in /var/log/bxi_log/, sorted by time. Find the latest log file for details.

2. Checking the Auto-Start Service Status

systemctl status ros_elf_launch.service

This guide presents two joint-control paths. To control only the head, publish named joint commands directly to actuators_cmds_override without writing code. For complete 31-DoF control, create a Mod containing only state.py and mod.yaml and generate the trajectory directly in on_update().

The example targets Mod API 4.0:

• Complete framework source
• Complete Mod API documentation

Run the commands below from the framework repository root.

Before you start: hardware defaults to 29 DoF

The hardware launch uses enable_head:=auto by default and reads the robot module configuration from /opt/bxi/robot_config.yaml. Both of the following conditions must be satisfied before the two head joints and the complete 31-DoF hardware are enabled:

1. /opt/bxi/robot_config.yaml exists and can be read successfully;
2. the configuration contains modules.head.enabled: true.

The minimum configuration structure is shown below. Production configuration should be generated with bxi_robot_config_tool:

modules:
  head:
    enabled: true

Any of the following cases falls back to the built-in 29-DoF configuration without the head motors:

• /opt/bxi/robot_config.yaml is missing, unreadable, or malformed;
• modules.head.enabled is absent;
• modules.head.enabled is false.

The current implementation uses the same hardware_elf3 package whether or not the head is enabled. Inspect the motor_disable mask in the startup log to determine whether the head motors are enabled:

# Head enabled; no other motor-disable bits are set in this example
[bxi hardware config] package=hardware_elf3, motor_disable=0x00000000, ...

# Head disabled; no other motor-disable bits are set in this example
[bxi hardware config] package=hardware_elf3, motor_disable=0x60000000, ...

If other motors are also disabled, the complete motor_disable value may differ from the examples above. Check only the head mask: motor_disable & 0x60000000 == 0 means that the head is enabled, while motor_disable & 0x60000000 == 0x60000000 means that it is disabled. Do not infer the DoF mode from hardware_elf3_head versus hardware_elf3 package names.

In 29-DoF mode, the runtime joint layout does not contain head_z_joint or head_y_joint, so the head-override command below is rejected as containing unknown joint names. Generate a valid /opt/bxi/robot_config.yaml and restart the hardware program first. The simulation VKH6 model already contains both head joints and is not controlled by this hardware configuration.

1. No-code head-joint override

At the final output stage, the controller reads override commands of type communication/msg/ActuatorCmds and replaces only the joints listed in actuators_name. All other joints remain controlled by the current state or policy, so head-only control does not require a Mod or a complete 31-element command.

The override topic includes the launch-time topic_prefix:

Overrides are disabled in zero-torque mode by default. After starting the robot and waiting for the joint layout to initialize, enter zero-position mode or another actively controlled state. For example, enter zero-position mode with:

ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_4: 1}"

ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_4: 0}"

The command below overrides both head joints at 20 Hz. The targets for head_z_joint and head_y_joint are 0.20 rad and -0.10 rad, respectively:

# Simulation
ros2 topic pub -r 20 \
  /simulation/actuators_cmds_override \
  communication/msg/ActuatorCmds \
  '{
    actuators_name: ["head_z_joint", "head_y_joint"],
    pos: [0.20, -0.10],
    kp: [16.747, 16.747],
    kd: [1.066, 1.066]
  }'

Use the same message on hardware and change only the topic:

# Hardware; suspend the robot and prepare the emergency stop first
ros2 topic pub -r 20 \
  /hardware/actuators_cmds_override \
  communication/msg/ActuatorCmds \
  '{
    actuators_name: ["head_z_joint", "head_y_joint"],
    pos: [0.20, -0.10],
    kp: [16.747, 16.747],
    kd: [1.066, 1.066]
  }'

actuators_name defines the joint order for every command array. The lengths of pos, kp, and kd must match the number of joint names. Omitted vel and torque fields are treated as zero.

The default override timeout is 0.2 s, so --once cannot hold a target. After the 20 Hz publisher stops, the command expires automatically and blends back to the current state's output over 0.2 s. An empty message explicitly requests release:

# Simulation; replace simulation with hardware on the robot
ros2 topic pub --once \
  /simulation/actuators_cmds_override \
  communication/msg/ActuatorCmds '{}'

To generate a time-varying head trajectory, continuously publish the same message type from a ROS node; each new message atomically replaces the previous override. Use the Mod approach below when state-machine integration, a whole-body trajectory, or more complex control logic is required.

2. The 31-joint order

The qpos, kp, and kd arrays in a MotorFrame must use the same joint layout. The formula arrays in this example use the order below; position values are in radians.

The example explicitly binds this layout to its MotorFrame. The runtime layout may use a different order as long as it contains the same 31 named joints; the framework maps commands to the actual order by joint name.

3. Create the Mod

cd ~/bxi_ws/bxi_rl_controller_ros2_example
mkdir -p src/bxi_example_py_elf3/mods/com.example.elf3_31dof

Only two files are required:

src/bxi_example_py_elf3/mods/com.example.elf3_31dof/
├── mod.yaml
└── state.py

4. Write state.py

import math

import numpy as np

from bxi_example_py_elf3.framework.mod_api import JointLayout, RobotControlState


ELF3_JOINT_NAMES = (
    "waist_y_joint", "waist_x_joint", "waist_z_joint",
    "l_hip_y_joint", "l_hip_x_joint", "l_hip_z_joint",
    "l_knee_y_joint", "l_ankle_y_joint", "l_ankle_x_joint",
    "r_hip_y_joint", "r_hip_x_joint", "r_hip_z_joint",
    "r_knee_y_joint", "r_ankle_y_joint", "r_ankle_x_joint",
    "l_shoulder_y_joint", "l_shoulder_x_joint", "l_shoulder_z_joint",
    "l_elbow_y_joint", "l_wrist_x_joint", "l_wrist_y_joint",
    "l_wrist_z_joint", "r_shoulder_y_joint", "r_shoulder_x_joint",
    "r_shoulder_z_joint", "r_elbow_y_joint", "r_wrist_x_joint",
    "r_wrist_y_joint", "r_wrist_z_joint", "head_z_joint",
    "head_y_joint",
)
ELF3_LAYOUT = JointLayout(ELF3_JOINT_NAMES, label="ELF3 31-DoF")


class Elf31DofState(RobotControlState):
    # The order exactly matches ELF3_JOINT_NAMES. The first 29 entries use
    # zero-position-mode gains; the final two entries are the head gains.
    KP = np.array([
        500, 500, 300,
        300, 100, 100, 300, 50, 50,
        300, 100, 100, 300, 50, 50,
        100, 80, 80, 100, 20, 20, 20,
        100, 80, 80, 100, 20, 20, 20,
        16.747, 16.747,
    ], dtype=np.float32)
    KD = np.array([
        3, 3, 3,
        2.5, 2, 2, 2.5, 2, 2,
        2.5, 2, 2, 2.5, 2, 2,
        2.5, 2, 2, 2.5, 1, 1, 1,
        2.5, 2, 2, 2.5, 1, 1, 1,
        1.066, 1.066,
    ], dtype=np.float32)

    def __init__(self, name, state_id):
        super().__init__(name, state_id)
        self.elapsed = 0.0
        self.qpos = np.zeros(31, dtype=np.float32)

    def on_enter(self, ctx):
        if frozenset(ctx.robot_layout.names) != frozenset(ELF3_JOINT_NAMES):
            raise RuntimeError(
                "ELF3 joint set mismatch: "
                f"expected={ELF3_JOINT_NAMES}, actual={ctx.robot_layout.names}"
            )
        self.elapsed = 0.0

    def on_update(self, ctx, dt):
        # Regenerate the target from zero every cycle; do not accumulate offsets.
        self.qpos.fill(0.0)
        phase = 2.0 * math.pi * 0.25 * self.elapsed

        # Hard-coded 31-DoF example: hold the waist and legs at zero while
        # moving both arms and the head through small sinusoidal trajectories.
        self.qpos[15] = 0.15 * math.sin(phase)        # left shoulder y
        self.qpos[18] = 0.12 * math.sin(phase)        # left elbow y
        self.qpos[22] = -0.15 * math.sin(phase)       # right shoulder y
        self.qpos[25] = -0.12 * math.sin(phase)       # right elbow y
        self.qpos[29] = 0.10 * math.sin(phase)        # head z
        self.qpos[30] = 0.06 * math.sin(2.0 * phase)  # head y

        frame = self._motor_frame(
            ctx, self.qpos, self.KP, self.KD, layout=ELF3_LAYOUT
        )
        self._apply_frame(ctx, frame)
        self.elapsed += dt

There are four essential points:

1. qpos, KP, and KD are all 31-element float32 arrays interpreted using ELF3_LAYOUT, so the state commands the complete robot layout every cycle.
2. phase advances using the framework-provided dt, rather than assuming an exact number of loop iterations.
3. _motor_frame() reuses the state's internal MotorFrame buffer, and _apply_frame() submits it to the framework.
4. Neither EntryFrameProvider nor RunningFrameProvider is implemented; the trajectory is produced exclusively by on_update().

The current MotorFrame also supports the MIT vel and torque fields. This example omits both when calling _motor_frame(), so the framework explicitly fills them with zero.

Only six joints move in this formula, but the other 25 joints are still actively controlled by qpos=0 and their corresponding kp/kd. To change the motion, edit the formulas for the relevant indices in on_update() without changing the array order.

5. Write mod.yaml

schema: 1
id: com.example.elf3_31dof
name: ELF3 31-DoF Formula Trajectory
version: 1.0.0
api: ">=4,<5"
enable: true
entrypoint: null
visibility: public
requires:
  - id: com.bxi.basic_actions
    version: ">=1,<2"
conflicts: []
python_exports: []
runtime_requirements:
  python: []
  ros: []
  system: []

events:
  activate:
    slot: btn_10
    value: 99

states:
  formula_31dof:
    factory: state:Elf31DofState
    label: 31-DoF Formula Trajectory
    priority: 100
    group: Customer
    icon: waves
    confirm: true
    confirm_message: This unbalanced example is for simulation only

routes:
  - from: com.bxi.basic_actions/initial_pos
    event: activate
    to: formula_31dof

  - from: formula_31dof
    event: com.bxi.basic_actions/initial_pos
    to: com.bxi.basic_actions/initial_pos

Both routes intentionally omit transition. The project's elf3_state_machine.yaml sets default_transition to instant, so the state changes immediately and the target state's on_update() starts on the next control cycle. This is what “no transition” means in this example. If the system default has been changed, add transition: instant explicitly to both routes.

The example can only be entered from com.bxi.basic_actions/initial_pos (zero-position mode). This both reduces the target discontinuity during an instant switch and reflects the fact that the formula trajectory has no balance capability. Do not add routes from normal, walking, or other action states. Send btn_10=99 to enter and use the zero-position-mode command to return. This example does not use btn_10=10 because that binding is already owned by com.bxi.any_motion/activate.

6. Build and run

colcon build --packages-select bxi_example_py_elf3 \
  --symlink-install --merge-install
source install/setup.bash

Start in simulation:

ros2 launch bxi_example_py_elf3 example_demo.launch.py

First send the zero-position-mode command:

ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_4: 1}"

ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_4: 0}"

After the robot enters zero-position mode, send btn_10=99 to enter the formula-trajectory state:

ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_10: 99}"

# Releasing btn_10 is required so later btn_10 actions can trigger
ros2 topic pub --once /motion_commands \
  communication/msg/MotionCommands "{btn_10: 0}"

Publishing btn_10=0 only restores the released button state; it does not exit the formula-trajectory state that was just entered.

A successful load includes this log entry:

[com.example.elf3_31dof]: loaded v1.0.0: .../com.example.elf3_31dof

The fully qualified state name is com.example.elf3_31dof/formula_31dof.

The formula-trajectory Mod in this tutorial is for simulation only and must not be treated as a hardware standing controller. To verify joint motion on hardware, use actuators_cmds_override; after suspension, keep the underlying state in initial_pos or pd_brake only. Hardware control requires root privileges. Stop the background autostart service first so two controllers cannot command the motors concurrently. See the Motion Control Development Guide for startup instructions.

Troubleshooting

Joint layout mismatch

Inspect the actual ctx.robot_layout.names. A different order does not affect control because the framework maps the names from ELF3_LAYOUT automatically. Update the layout and all three 31-element arrays only when joints are missing or the hardware uses different joint names.

The state loads but the robot does not move

Make sure the latest workspace has been loaded with source install/setup.bash, and confirm that the startup log contains com.example.elf3_31dof. A non-symlink installation must be rebuilt after every Mod change.

The robot jumps when switching

This is an expected risk of an instant switch. Enter zero-position mode first, and ensure that on_update() produces the zero pose at elapsed=0. If the state must enter smoothly from arbitrary poses, use a Transition; that is outside this minimal example.

This guide uses Pinocchio's damped least-squares method to convert a wrist target pose into seven VKH6 single-arm joint angles. Resources for both the left and right arms are provided. It performs offline inverse kinematics only; it does not start ROS or command any motors.

1. Download the example resources

Download the scripts and URDFs for both arms into the same directory:

• Left arm: pinocchio_ik_solve.py and elf3_arm_l.urdf
• Right arm: pinocchio_ik_solve_r.py and elf3_arm_r.urdf

The directory should look like this:

elf3_arm_ik/
├── elf3_arm_l.urdf
├── elf3_arm_r.urdf
├── pinocchio_ik_solve.py
└── pinocchio_ik_solve_r.py

Both URDFs contain STL paths for visual and collision geometry. This example calls pin.buildModelFromUrdf() to build only the kinematic model, so the STL files are not required for the minimal IK solver.

2. Install Pinocchio

Use an isolated Python environment on the development computer so Pinocchio's NumPy dependencies do not affect the ROS environment:

cd elf3_arm_ik
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install pin scipy

Verify the installation:

python -c "import pinocchio as pin; print(pin.__version__)"

This guide was verified with pin 4.1.0, numpy 2.2.6, and scipy 1.15.3. Other compatible versions may also work.

3. Complete solver code

Complete left-arm code

The code below exactly matches the downloadable pinocchio_ik_solve.py:

import numpy as np
import pinocchio as pin
from scipy.spatial.transform import Rotation as R


if __name__ == "__main__":
    # 从 URDF 创建机器人模型
    model = pin.buildModelFromUrdf("elf3_arm_l.urdf")
    data = model.createData()

    # 选择末端坐标系
    frame_id = model.getFrameId("l_wrist_z_link")

    # 设置目标位置和目标姿态
    target = pin.SE3(
        R.from_euler("xyz", [10, 0, 0], degrees=True).as_matrix(),
        np.array([0.1, 0, 0]),
    )

    # 初始关节角
    q = np.zeros(model.nq)

    max_iterations = 1000
    error_tolerance = 1e-5
    step_size = 0.1
    damping = 1e-6

    for i in range(max_iterations):
        # 正运动学，计算当前末端位姿
        pin.forwardKinematics(model, data, q)
        pin.updateFramePlacements(model, data)
        current = data.oMf[frame_id]

        # SE(3) 位姿误差：当前末端坐标系到目标坐标系的变换
        current_to_target = current.actInv(target)
        error = pin.log6(current_to_target).vector

        # 判断是否收敛
        if np.linalg.norm(error) < error_tolerance:
            break

        # 计算末端在局部坐标系下的雅可比矩阵
        jacobian = pin.computeFrameJacobian(
            model,
            data,
            q,
            frame_id,
            pin.ReferenceFrame.LOCAL,
        )

        # 将末端雅可比转换为 SE(3) 位姿误差的雅可比
        jacobian = -pin.Jlog6(current_to_target.inverse()) @ jacobian

        # 阻尼最小二乘法，计算关节角增量
        velocity = -jacobian.T @ np.linalg.solve(
            jacobian @ jacobian.T + damping * np.eye(6),
            error,
        )

        # 更新关节角，并限制在 URDF 给出的关节范围内
        q = pin.integrate(model, q, velocity * step_size)
        q = np.clip(q, model.lowerPositionLimit, model.upperPositionLimit)

    print(q)

Use the same solver for the right arm

This page keeps only one complete code listing because the solver flow is identical for both arms. For the right arm, download pinocchio_ik_solve_r.py, or copy the left-arm code above and change only these two strings:

• Change elf3_arm_l.urdf to elf3_arm_r.urdf.
• Change l_wrist_z_link to r_wrist_z_link.

Both scripts use the same solver sequence:

1. Compute the current end-frame pose with forward kinematics.
2. Obtain the six-dimensional SE(3) pose error with pin.log6().
3. Compute the frame Jacobian in the local frame.
4. Compute joint velocity with damped least squares:

v = -Jᵀ (J Jᵀ + λI)⁻¹ e

1. Update the configuration with pin.integrate() and clip it to the URDF limits.

End-frame origin and orientation

The left-arm end frame is l_wrist_z_link; the right-arm frame is r_wrist_z_link. In the simplified URDFs supplied with this guide:

• The end-frame origin is at the common intersection of the wrist X, Y, and Z rotation axes, not at the palm centre or a fingertip. Both wrist_y_joint and wrist_z_joint have <origin xyz="0 0 0" rpy="0 0 0">, so the three wrist joints share one origin.
• base_link is the root of the simplified single-arm model. Its origin is at the first shoulder-axis centre for that arm; it is not a full-robot base frame located at the torso or on the ground. Transform the pose before using it with a full-robot model.
• With all seven joint angles at zero, the end-frame origin is (0.256, 0, -0.256) m in this base_link: the chain first goes 0.256 m along -Z from shoulder to elbow and then 0.256 m along +X from elbow to wrist. The simplified left- and right-arm URDFs use the same zero-position geometry.
• Every fixed joint rpy is zero. At the zero configuration, the end-frame +X/+Y/+Z axes therefore align exactly with the corresponding base_link axes. Under VKH6's ROS body-frame convention, +X points forward, +Y to the robot's left, and +Z upward. The end axes rotate with the wrist as the joints move.

target.translation, in metres, is the desired end-frame origin expressed in the simplified base_link. target.rotation is the desired orientation of the end-frame axes relative to base_link. In the example, R.from_euler("xyz", [10, 0, 0], degrees=True) requests an end frame rotated 10 degrees about X; it does not simply add 10 degrees to one wrist joint.

4. Run and interpret the result

Run from the directory containing the resources because both scripts open their URDF through a relative path:

cd elf3_arm_ik
source .venv/bin/activate

# Left arm
python pinocchio_ik_solve.py

# Right arm
python pinocchio_ik_solve_r.py

Both scripts use the same target pose and currently print:

[-0.18420714  0.14130363 -0.02609032 -0.95993     0.14621128  1.309
 -0.14385886]

elf3_arm_l.urdf defines the left-arm array order:

The right-arm output uses the same seven numeric values, mapped by elf3_arm_r.urdf to:

r_shoulder_y_joint, r_shoulder_x_joint, r_shoulder_z_joint,
r_elbow_y_joint, r_wrist_x_joint, r_wrist_y_joint, r_wrist_z_joint

Production code should recompute the error after the loop and accept the result only when it is below the tolerance. If convergence fails, adjust the target pose, initial configuration, step size, or damping.

5. Change the target pose

Change the target position with:

target_position = np.array([x, y, z])  # metres, in base_link

Change the target orientation with:

target_rotation = R.from_euler(
    "xyz",
    [roll, pitch, yaw],
    degrees=True,
).as_matrix()

Combine them into a Pinocchio pose:

target = pin.SE3(target_rotation, target_position)

A seven-DoF arm is redundant for a six-dimensional end pose, so the same target may have multiple solutions. The initial q, damping, and step size affect the result. For continuous trajectories, use the previous solution as the next initial configuration to avoid joint jumps.

6. Use the result as a joint override

The IK result is only a joint target. To validate it in simulation, use actuators_cmds_override to override the named left-arm joints. The publishing rate must satisfy the override timeout; the current default is 0.2 s.

ros2 topic pub -r 20 \
  /simulation/actuators_cmds_override \
  communication/msg/ActuatorCmds \
  '{
    actuators_name: [
      "l_shoulder_y_joint", "l_shoulder_x_joint",
      "l_shoulder_z_joint", "l_elbow_y_joint",
      "l_wrist_x_joint", "l_wrist_y_joint", "l_wrist_z_joint"
    ],
    pos: [
      -0.18420714, 0.14130363, -0.02609032, -0.95993,
      0.14621128, 1.309, -0.14385886
    ],
    kp: [54.224, 54.224, 16.747, 54.224, 16.747, 16.747, 16.747],
    kd: [3.452, 3.452, 1.066, 3.452, 1.066, 1.066, 1.066]
  }'

Press Ctrl+C to stop continuous publication; the override then times out and blends back to the current state. It can also be released explicitly:

ros2 topic pub --once \
  /simulation/actuators_cmds_override \
  communication/msg/ActuatorCmds '{}'

Use /hardware/actuators_cmds_override on hardware. To control the right arm, replace the seven l_ joint names in the command with their corresponding r_ names. Because the current example solution contains two limit values, do not send it directly to hardware.

The VKH6 top display is used to show basic robot status information. It can also display cute facial expressions to make the robot feel more lively. For secondary development, the screen supports Bluetooth and Wi-Fi communication for wireless data transmission, and it also supports touch interaction.

Features

The top display can be used for:

• Robot expressions: Display cute facial expressions to make the robot feel more lively.
• Data display: Supports Bluetooth and Wi-Fi communication for wireless data transmission.
• Touch interaction: The screen supports touch input, allowing custom interactive programs to be developed.

Hardware Platform

The top display is based on the Waveshare ESP32-S3-Touch-LCD-2.1 touch display development board, which is suitable for robot status display and simple interaction.

Usage

On the real robot, the top display is connected to the robot host through a USB cable. This USB connection can be used for firmware flashing and debugging.

Basic usage:

1. Make sure the main robot battery power is turned on.
2. Check that the USB connection between the top display and the robot host is secure.
3. If the display lights up normally, the screen is working.

Communication

The current real-robot setup uses USB wired communication by default, which is suitable for flashing and debugging. The display hardware also supports Bluetooth 5 (BLE) and 2.4GHz Wi-Fi, but the wireless link, communication protocol, and host-side data publisher need to be developed according to project requirements.

Secondary Development

The top display program is maintained in the https://github.com/Luckyt1/bxi_show repository. When modifying displayed content, page layout, backlight behavior, communication method, or reflashing firmware, use the following workflow:

1. Read the build, flashing, and dependency instructions in the bxi_show repository.
2. Configure the development environment according to the framework used by the project, referring to the Waveshare Arduino or ESP-IDF documentation as needed.
3. Connect the display to the development host via USB, then compile, flash, and debug through the serial port.
4. After flashing, verify that data refresh works while the robot is stationary before starting motion debugging.

Common development items include:

• Use the LVGL graphics library to develop facial expressions and animations.
• Adjust the layout of voltage, battery level, temperature, and other displayed fields.
• Add robot status, network status, or debugging status indicators.
• Change brightness, sleep timeout, and wake-up behavior.
• Extend BLE or Wi-Fi data communication.
• Add color, icon, or text warnings for abnormal states.

Debugging Checklist

References

• Display hardware manual: https://docs.waveshare.net/ESP32-S3-Touch-LCD-2.1
• Top display program: https://github.com/Luckyt1/bxi_show

This page is intended for customer-side deployment of the Revo2 dexterous hand on VKH6. It focuses on wiring, dependency installation, build, run, and acceptance checks. For SDK APIs and custom development, refer to the example repository:

• VKBOTS Revo2 example: bxi_revo2_example
• Official hand SDK: brainco-hand-sdk

Environment

The example package communicates with the VKBOTS CANFD hardware node through communication/msg/CANFDPacket, so the bxi_ros2_pkg environment must be sourced first.

Wiring

With the default wiring, no source-code changes are required:

After wiring, start the robot normally. When the hardware node starts successfully, the Revo2 hand usually opens automatically. Use this as the first hardware-link check.

Quick Deployment

1. Get The Example Package

Run the following on the robot controller or a ROS 2 host:

cd ~/bxi_ws
git clone https://github.com/konodoki/bxi_revo2_example.git

If GitHub is unavailable on site, download the repository in advance and copy it to ~/bxi_ws/bxi_revo2_example.

2. Download The C++ SDK Files

The C++ demo requires the official SDK shared library and headers before build.

cd ~/bxi_ws/bxi_revo2_example
./download-lib.sh

The script creates:

• dist/include/
• dist/shared/linux/libbc_stark_sdk.so
• VERSION

3. Install The Python SDK

Install the pinned SDK version before running the Python demo:

pip install bc-stark-sdk==1.5.1 --index-url https://pypi.org/simple/

4. Build The Package

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
colcon build
source install/setup.bash

Run And Validate

1. Set The CANFD ROS 2 Environment

The hand demo communicates with the robot hardware node through /canfd_packet/rx and /canfd_packet/tx. Because the hardware node normally runs as root, set the same ROS 2 Domain and CycloneDDS network configuration in a root shell, and run the demo from that shell:

sudo su
export ROS_DOMAIN_ID=ROBOT_DOMAIN_ID
export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
export ROS_LOCALHOST_ONLY=0
export CYCLONEDDS_URI='<CycloneDDS><Domain Id="any"><General><Interfaces><NetworkInterface name="lo" multicast="true"/></Interfaces><AllowMulticast>true</AllowMulticast></General></Domain></CycloneDDS>'

Replace ROBOT_DOMAIN_ID with the numeric Domain ID used by the robot. Do not set the variables only in a normal-user shell and then switch to root; sudo su does not reliably preserve the ROS environment.

2. Start The Robot Hardware Node

Start VKH6 using the normal robot startup flow. See Motion Control Development Guide if needed.

Check that the CANFD topics exist:

source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
ros2 topic list | grep canfd_packet

Expected topics:

/canfd_packet/rx
/canfd_packet/tx

3. Run The Demo

Run the C++ demo:

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
source install/setup.bash
ros2 run bxi_revo2_example bxi_revo2_example

Or run the Python demo:

cd ~/bxi_ws/bxi_revo2_example
source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
source install/setup.bash
ros2 run bxi_revo2_example bxi_revo2_example.py

3. Acceptance Check

The terminal should print device information, finger positions, speeds, currents, and configuration values. The hand will run:

1. Basic position control: fist, open hand, single-finger motion;
2. Speed, current, and PWM control;
3. Revo2 advanced control: unit mode, position with time, position with speed, multi-finger motion;
4. Built-in gestures: Open, Fist, Pinch, Point, and others;
5. Device information and parameter queries.

The default demo runs the left hand first, then the right hand. If both hands complete these actions without continuous errors, the basic deployment is complete.

Change The Default Bus Or ID

If the site wiring or hand ID differs from the default configuration, update the bus and ID in the example source.

Python example:

~/bxi_ws/bxi_revo2_example/src/bxi_revo2_example.py

Default configuration:

left_ctx = await init_bxipci_device(5, 126, master_id=1, is_canfd=True, ...)
right_ctx = await init_bxipci_device(6, 127, master_id=1, is_canfd=True, ...)

C++ example:

~/bxi_ws/bxi_revo2_example/src/bxi_revo2_example.cpp

Default configuration:

init_bxipci_device(&left_ctx_, 5, 126, true);
init_bxipci_device(&right_ctx_, 6, 127, true);

Rebuild after changing the source:

cd ~/bxi_ws/bxi_revo2_example
colcon build
source install/setup.bash

Troubleshooting

Missing stark-sdk.h Or libbc_stark_sdk.so

The C++ SDK files have not been downloaded. Run:

cd ~/bxi_ws/bxi_revo2_example
./download-lib.sh

Then rebuild the package.

No module named bc_stark_sdk

The Python SDK is missing or installed into the wrong Python environment. Run:

pip install bc-stark-sdk==1.5.1 --index-url https://pypi.org/simple/

communication.msg.CANFDPacket not found

The VKBOTS ROS 2 message package environment has not been sourced:

source /opt/bxi/bxi_ros2_pkg/setup.bash
source ~/bxi_ws/bxi_revo2_example/install/setup.bash

No Response Or Read Timeout

Check the following:

1. Left hand is connected to CAN5 and uses ID 126;
2. Right hand is connected to CAN6 and uses ID 127;
3. The robot hardware node is running and /canfd_packet/rx plus /canfd_packet/tx exist;
4. Cabling and power are normal;
5. No other process is controlling the same hand at the same time.
6. If it is a factory-installed hardware node, please check if ROS_DOMAIN_ID is consistent.

Development Entry

Customer deployment usually does not require changes to the low-level CAN bridge. To control the hand from a custom ROS 2 node, see “Use In Your Own ROS 2 Node class” in the example repository README:

https://github.com/konodoki/bxi_revo2_example

com.bxi.upper_body_teleop is a standalone VKH6 Mod. It bundles PICO access, MediaMTX, head-camera RTSP, Pinocchio dual-arm IK, and its runtime libraries. It only requires com.bxi.basic_actions; the legacy bxi_teleop_v2 and separate bringup nodes are not required.

• Mod: com.bxi.upper_body_teleop
• PICO client: XRoboToolkit-PICO-1.1.1.apk

Installation

Install the Mod in the independent directory that is not overwritten by App updates:

sudo mkdir -p /opt/bxi/mods
sudo git clone https://github.com/konodoki/com.bxi.upper_body_teleop.git /opt/bxi/mods/com.bxi.upper_body_teleop

Update an existing checkout:

cd /opt/bxi/mods/com.bxi.upper_body_teleop
git pull --ff-only

If an older project already contains the same Mod in its built-in mods or private_git_mods, back it up and move it outside the scanned directories. Two copies with the same Mod ID will prevent startup.

Startup

Start the robot and the normal control program. The Mod nodes start automatically when com.bxi.upper_body_teleop/upper_body_teleop is entered. Do not run the legacy elf3_arm_bringup_nohand.launch.py, pico_bxi_server, or bxi_teleop_v2 scripts separately.

PICO Connection And Calibration

Use the same PICO connection and body-tracking calibration procedure as Sonic:

1. Secure one Motion Tracker to each leg, with the button/indicator side facing upward, and power them on.
2. Open Motion Tracker on the PICO home screen, confirm both trackers are connected, select Start Calibration, and complete the guided procedure.
3. Select Adjust Floor and align the virtual floor with the physical floor.
4. Open XRoboToolkit and connect to the robot through Network → PC Service using the robot's LAN IP.
5. Confirm these settings:

1. Confirm the Network status is WORKING and the log has no continuous errors. Then enter the Mod state and perform the button calibration.

Operation

1. From normal, press LB + LT + X (btn_10=17) on the remote controller to enter upper-body teleoperation.
2. On PICO, enable Body Tracking, Controller, and Send. Confirm XRoboToolkit reports WORKING.
3. Hold the standard upright posture and press A+B+X+Y to calibrate. Successful calibration enters POSE automatically; A+X is not required.
4. Hold the left or right grip to take over the corresponding arm. Releasing the grip smoothly returns that arm to its PD standing posture.
5. The left and right triggers control the corresponding grippers. Each state entry performs a low-speed gripper limit calibration.
6. Press A+B+X+Y again to recalibrate; both arms return to PD posture during calibration.
7. Exit through the standard system event to normal, PD brake, recover, or zero-torque.

A+X no longer toggles following mode. If PICO temporarily disconnects, the lower body continues under the gait policy and both arms hold the PD posture.

Video Streaming

MediaMTX and the head-camera node are managed by the Mod. The default URL is rtsp://<robot-ip>:2212/video. Select this address in the PICO app on the same LAN; no separate video script is required.

Acceptance And Troubleshooting

• Logs should show mediamtx_server, head_camera_rtsp, pico_manager, and arm_ik_bridge starting automatically;
• A+B+X+Y enters POSE, and the gripped arm follows the controller;
• Triggers control the grippers and child processes stop on state exit.

For a duplicate Mod ID error, keep only /opt/bxi/mods/com.bxi.upper_body_teleop and move the old project copy outside the scanned directories. If no PICO data arrives, wake the headset, enable Body Tracking and Send, and confirm WORKING.

This guide explains how to deploy and use Sonic full-body teleoperation on VKH6, including robot-side dependency installation, PICO Motion Tracker calibration, XRoboToolkit network configuration, full-body motion following, and the exit procedure.

• Motion-control repository: bxi_rl_controller_ros2_example
• Sonic Mod repository: com.bxi.sonic
• PICO client: XRoboToolkit-PICO-1.1.1.apk

Environment

Choose the Project Directory

Use the project path that matches how the robot is started. Do not place the Sonic Mod inside the App project or its private_git_mods; install it in the independent /opt/bxi/mods directory, which is outside the App download and survives App updates.

mv ~/bxi_ws/bxi_rl_controller_ros2_example/src/bxi_example_py_elf3/mods/private_git_mods/com.bxi.sonic \
  ~/bxi_ws/bxi_rl_controller_ros2_example/com.bxi.sonic.backup

When following the commands below, use the project path for your startup method. Clone the Sonic Mod into the independent /opt/bxi/mods/com.bxi.sonic directory.

Prepare the Robot

0. Clone the Sonic Mod

The Sonic Mod is maintained in a separate repository. Clone it manually into the motion-control project's private Mod directory before building:

sudo mkdir -p /opt/bxi/mods
sudo git clone https://github.com/konodoki/com.bxi.sonic.git /opt/bxi/mods/com.bxi.sonic

If the directory already exists, update that repository separately:

cd /opt/bxi/mods/com.bxi.sonic
git pull --ff-only

The parent project does not track this directory. At runtime, the configured /opt/bxi/mods root is scanned recursively, so the Mod remains available after an App update.

1. Update the Motion-Control Project

Update bxi_rl_controller_ros2_example on the robot to the latest version:

cd /home/bxi/bxi_ws/bxi_rl_controller_ros2_example
git pull --ff-only

After updating the source, rebuild the project as described in the repository README and source the environment:

source /opt/ros/humble/setup.bash
source /opt/bxi/bxi_ros2_pkg/setup.bash
cd /home/bxi/bxi_ws/bxi_rl_controller_ros2_example
bash build.sh
sudo systemctl restart ros_elf_launch.service

2. Install Sonic Dependencies

Before using Sonic for the first time, switch to the root user on the robot and install the Python dependencies required for PICO connectivity:

sudo su
python3 -m pip install -r /opt/bxi/mods/com.bxi.sonic/requirements-pico.txt

If no proxy is configured, or downloads from the default PyPI index are slow or time out, retry with the Tsinghua University PyPI mirror in the same root shell. The following command sets the timeout to 120 seconds and disables caching:

python3 -m pip install \
  -r /opt/bxi/mods/com.bxi.sonic/requirements-pico.txt \
  -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple \
  --no-cache-dir \
  --timeout 120

The dependencies normally need to be installed only once. Run the command again after an update if requirements-pico.txt has changed.

3. Install the PICO Application

Download XRoboToolkit-PICO-1.1.1.apk and install the APK on the PICO headset. After installation, XRoboToolkit is available under Unknown Sources in the PICO Library.

Enter the Sonic Ready State

1. Start VKH6 normally, confirm that the robot has completed its self-check, and use the remote controller to put the robot into walking mode. The robot should hold its normal standing posture.

1. Press LB + RB + X simultaneously on the robot remote controller to request Sonic full-body teleoperation.

2. Wait for the state transition to finish. The robot assumes the ready posture shown below. Continue with PICO calibration and motion following only after the posture is stable.

Calibrate the PICO Motion Trackers

Recalibrate the Motion Trackers before each full-body teleoperation session to reduce body-pose and floor-height errors.

1. Secure one Motion Tracker to each leg. The side with the button and indicator light must face upward along the body. Press the button to turn on each tracker.

2. Put on the PICO headset and pick up both controllers. Select Motion Tracker in the lower-right corner of the PICO home screen.

1. Confirm that both leg trackers are connected. Select Start Calibration and follow the instructions in the headset.

1. After calibration, select Adjust Floor and follow the instructions to align the virtual floor with the physical floor.

1. Observe the avatar on the screen. When the operator moves their head, hands, and legs, the avatar should follow those movements and its feet should remain close to the floor.

Connect XRoboToolkit

1. Return to the PICO Library and open XRoboToolkit under Unknown Sources.

1. Confirm that PICO and the robot are connected to the same LAN, then obtain the robot's LAN IP address.

2. In the Network section of XRoboToolkit, select Enter next to PC Service, enter the robot's IP address, and connect.

3. Check the tracking and transmission options against the table below:

1. Confirm that Status in the Network section shows WORKING and that the log does not contain continuous errors.

Calibrate the Reference Posture and Start Following

1. Face the same direction as the robot and stand upright. Let the upper arms hang naturally, bend the elbows approximately 90 degrees, and hold the forearms horizontally in front of the body as shown below.

1. Hold the posture steady and press A + B + X + Y across the two PICO controllers at the same time. This aligns PICO three-point tracking with the robot's reference posture.

2. After calibration, continue matching the robot's posture and heading. Confirm that body tracking in the headset does not show significant drift.

3. Press A + X simultaneously on the PICO controllers. The robot begins following the operator's full-body motion. Move the arms slowly first, then make small torso and leg movements to verify that all motion directions are correct.

4. To pause following and return the robot to its default posture, press A + X simultaneously again.

5. After confirming that real-time following has stopped, press RB + X simultaneously on the robot remote controller to return the robot to normal walking mode.

Common controls:

Acceptance Check

After deployment, verify all of the following:

1. Both leg trackers show as connected in the PICO Motion Tracker screen;
2. The avatar's head, hands, and legs follow the operator's movements;
3. XRoboToolkit shows WORKING, Mode is set to Full-body, and Send is selected;
4. The robot enters and stably holds the Sonic ready posture after LB + RB + X is pressed;
5. After calibration with A + B + X + Y, pressing A + X makes the robot follow small movements with low latency;
6. Pressing A + X again returns the robot to its default posture, and pressing RB + X returns it to normal walking mode.

Troubleshooting

XRoboToolkit Cannot Connect to the Robot

• Confirm that PICO and the robot are on the same LAN;
• Confirm that PC Service contains the robot's IP address, not the PICO IP address;
• Check whether the IP address changed after switching networks;
• Confirm that XRoboToolkit shows WORKING, and review its log for connection errors.

The Avatar's Legs Do Not Follow or Its Feet Float

• Confirm that both leg trackers are connected and sufficiently charged;
• Make sure the button and indicator side of each tracker faces upward along the body;
• Run Start Calibration and Adjust Floor again;
• Confirm that XRoboToolkit uses Full-body mode with Num set to 2.

The Robot Cannot Enter the Sonic Ready State

• Confirm that the robot has completed its self-check and is in normal walking mode;
• Confirm that LB + RB + X is pressed as a three-button combination;
• Confirm that the project has been updated to the latest version and rebuilt;
• On first use, confirm that the packages in requirements-pico.txt were installed into the Python environment used by the robot process.

The Robot Does Not Follow After Calibration

• Confirm that Send is selected in XRoboToolkit and its status is WORKING;
• Confirm that the avatar in PICO Motion Tracker follows the operator correctly;
• Return to the initial posture and press A + B + X + Y again;
• Wait for calibration to finish, then press A + X to start real-time following.

The Robot Moves in a Different Direction From the Operator

Stop real-time following, face the same direction as the robot, and recalibrate. If only the heading is offset, press X alone on the robot remote controller while no shoulder or trigger button is held to reset heading alignment.

Motion Stutters or the Posture Jumps

Stop large movements and check the wireless network quality between PICO and the robot, the tracker connections, and the XRoboToolkit log. Before resuming, verify the initial posture and surrounding safety again. If the issue continues, exit Sonic, then recalibrate and reconnect.

References

• bxi_rl_controller_ros2_example
• Sonic Mod repository
• XRoboToolkit Unity Client

This guide explains how to configure a Livox MID-360s LiDAR for VKH6 and use bxi_rc_app to create maps, edit navigation data, and run guided tours.

Reference project: bxi_nav

Prerequisites

• Install the latest version of bxi_rc_app.
• Prepare an VKH6 robot equipped with a Livox MID-360s LiDAR.
• Make sure the bxi_rc_slam package is up to date.
• Connect the computer directly to the LiDAR with an Ethernet cable.
• Keep the operating area safe and the paths clear, with as little pedestrian traffic as possible.

Environment Setup

This guide assumes Ubuntu 22.04 and ROS 2 Humble. Before continuing, source a ROS 2 environment with Navigation2 installed, then install the point-cloud-to-laser-scan tool:

source /opt/ros/humble/setup.bash
sudo apt update
sudo apt install -y ros-humble-pointcloud-to-laserscan

After installation, verify that the required packages are available:

ros2 pkg prefix nav2_bringup
ros2 pkg prefix pointcloud_to_laserscan

If both commands print their package installation paths, the environment is ready.

1. Configure the Livox MID-360s LiDAR

If the LiDAR does not start, the network or device configuration is usually incorrect. First confirm that the computer and LiDAR are on the same subnet, then check the configuration file.

1.1 Configure a Static IP Address

Set the computer's Ethernet interface to a static IP address, such as 192.168.1.51. A direct Ethernet connection is recommended. Changing network settings through a remote desktop session may cause permission issues.

1.2 Update the LiDAR Configuration File

Configuration file path:

bxi_rc_slam/src/livox_ros_driver2/config/MID360s_config.json

Check the following fields:

• host_ip: the static IP address of the computer's Ethernet interface, such as 192.168.1.51.
• ip: the LiDAR IP address. A MID-360s address is typically in the 192.168.1.1xx range. The final two digits may be printed below the QR code on the LiDAR housing.

If the label is difficult to read, place the computer and LiDAR on the same subnet and run:

ros2 launch livox_ros_driver2 msg_MID360s_launch.py

Identify the LiDAR IP address in the program output, then enter it in the configuration file.

Example configuration:

{
  "lidar_summary_info": {
    "lidar_type": 8
  },
  "Mid360s": {
    "lidar_net_info": {
      "cmd_data_port": 56100,
      "push_msg_port": 56200,
      "point_data_port": 56300,
      "imu_data_port": 56400,
      "log_data_port": 56500
    },
    "host_net_info": [
      {
        "host_ip": "192.168.1.51",
        "cmd_data_port": 56101,
        "push_msg_port": 56201,
        "point_data_port": 56301,
        "imu_data_port": 56401,
        "log_data_port": 56501
      }
    ]
  },
  "lidar_configs": [
    {
      "ip": "192.168.1.128",
      "pcl_data_type": 1,
      "pattern_mode": 0,
      "extrinsic_parameter": {
        "roll": 0.0,
        "pitch": 0.0,
        "yaw": 0.0,
        "x": 0,
        "y": 0,
        "z": 0
      }
    }
  ]
}

  sudo /opt/bxi/bxi_rc_slam/install.sh

2. Use the Navigation App

1. Open bxi_rc_app and select My Devices (我的设备).

1. Select the robot you want to navigate from the device list to open its details page.

1. Open Map Management (地图管理) from the robot details page.

2.1 Create a Map

1. Open Map Management (地图管理) and select New Map (新建地图).

1. Start the robot and keep it in walking mode. After confirming that the point cloud is displayed correctly, select Start Mapping (开始建图).

1. Stand behind the robot and remotely drive it through the target area. Staying behind the robot prevents the operator from being captured in the map. Minimize pedestrian movement while mapping.

2. After the map covers the target area, select Save (保存). Wait for confirmation that the map has been saved before leaving the mapping page.

2.2 Edit the Map

1. In Map Management (地图管理), select the map you just saved.

1. Open the guided-tour editor, switch to Waypoint (航点), and mark each destination on the map.

1. Set the robot's arrival heading for each waypoint. Add a waypoint name if needed.

1. Optional: To make the robot perform a specific behavior after reaching the waypoint, select Add Action (添加动作), choose Voice (语音), Action (动作), or Delay (延迟), configure it, and then select Add (添加). You can add multiple behaviors to the same waypoint if needed.

1. Switch to Area (区域) and select Add Clearing Zone (添加清除区). Draw clearing zones over the robot's travel paths to remove obstacles that no longer exist in the physical environment.

1. Verify the waypoints, headings, arrival behaviors, and clearing zones, then wait for the map to be saved successfully.

2.3 Start a Guided Tour

1. Return to the robot details page, open Operating Mode (运行模式), and select guided-tour mode.

1. Select the required map, then select Start (开始) on its card.

1. Select Relocalize (重定位). Tap the robot's approximate position on the map, then drag the pose marker in the direction the robot is facing.

1. Check whether the red point cloud around the robot aligns with the walls on the map. If they align, select Confirm (确认). If the offset is significant, adjust the position and heading again.

1. Select Navigate (导航) to start the guided-tour task.

1. If a problem occurs during the tour, immediately select Pause (暂停) or Stop (终止). You can also use the on-screen joystick to take manual control and prevent the robot from continuing off course.

1. When the tour is complete, stop navigation before leaving the page.

Troubleshooting

How to Adjust the Remote-Control Speed

1. Open the robot remote-control page and select the Settings icon in the upper-right corner.

1. Select Control (控制) on the Settings page, then adjust the following parameters as needed:

2. Speed Output Range (速度输出范围): limits the forward and reverse linear speed for both the on-screen virtual joystick and an external gamepad.

3. Rotation Output Range (旋转输出范围): limits the left and right turning speed for both the on-screen virtual joystick and an external gamepad.

After changing the ranges, test the robot at low speed in a clear, safe area. Increase the limits gradually only after confirming that the robot moves as expected.

The LiDAR Does Not Start

• Confirm that the computer and LiDAR are connected by Ethernet and are on the same subnet.
• Confirm that host_ip matches the static IP address of the computer's Ethernet interface.
• Confirm that ip matches the actual LiDAR IP address.

People or Dynamic Obstacles Appear on the Map

• Keep the mapping operator behind the robot.
• Minimize pedestrian movement during mapping.
• Add clearing zones in the map editor for obstacles that no longer exist.

The Point Cloud Does Not Align with the Walls After Relocalization

• Select the robot's position on the map again.
• Adjust the pose marker to match the robot's actual heading.
• Start navigation only after the red point-cloud returns are reasonably aligned with the walls.

This document contains manipulation algorithm development instructions for the VKH6 robot.

Pipeline Overview

Theoretical Background

Training Environment

Deployment Framework

VKBOTS Control is used to add, connect to, control, and maintain VKBOTS robots. This guide reflects the current App pages and routing for Android and Windows.

Before you use a robot for the first time

If this is your first robot, complete onboarding, Wi-Fi provisioning, and the first start with guidance from an experienced on-site operator. In this guide, the controller is the phone, tablet, or PC running the App; the robot is the physical device being added and controlled; binding saves that robot to the current account or controller so it can be connected again later.

For first-time use, follow this order:

1. Place the robot in a level, clear area without people, loose items, or objects that could be knocked over.
2. Open VKBOTS Control on the controller and choose sign-in or Local mode.
3. Use Add Device to scan and bind the robot, then complete Wi-Fi provisioning as prompted.
4. Connect by Wi-Fi and open Device Home; check battery and Diagnostics first.
5. If the App reports legacy firmware, complete the firmware upgrade first.
6. Enter Remote Control and start the robot only when you understand the controls, the site is safe, and you are authorized to operate it.

Page map

1. Home

1.1 First launch

The welcome page is shown on first launch. If you already have a VKBOTS account, enter a mobile number, accept the Terms of Service and Privacy Policy, and request a verification code. For first on-site use without an account, select Enter Local Mode at the bottom. Local mode does not create a cloud account automatically, but it can connect to robots already bound on this controller.

1.2 Home entries

After signing in or entering Local mode, the Home page provides Add Device, My Devices, Firmware Upgrade, Diagnostics, and Profile. The Local Mode label at top right means the App is using device bindings stored on this controller.

Cloud mode and Local mode

Local mode suits offline and field maintenance. Cloud mode suits multi-device collaboration, account management, and support services.

2. Add a robot

2.1 Add Device guidance

Select Add Device on Home. This lets the controller recognize and save the robot, and must be completed for first use. Before starting:

1. Turn on the robot controller and place the robot safely.
2. Enable Bluetooth and location permission on the phone or tablet.
3. Connect the controller to usable Wi-Fi. For Wi-Fi control, the controller and robot should be on the same LAN.
4. Select Start Pairing to scan for nearby robots.

2.2 Scan and select a Bluetooth device

The scan page lists discoverable VKBOTS robots and their signal strength. Select Connect for the target robot, then follow the on-screen flow to provision or bind it.

2.3 Provisioning and binding

After Bluetooth connection, confirm the target robot, enter or select Wi-Fi information, and wait for the robot to join the network. Think of this as finding the robot over Bluetooth first, then telling it which Wi-Fi network to join. Once binding is complete, the robot appears in My Devices.

3. Manage and connect devices

3.1 My Devices

My Devices shows bound robots as cards. Select a card to choose a connection method. It also provides entries such as pairing a new robot and scanning a maintenance credential. Online status only indicates discoverability; it is not a substitute for an on-site safety check.

3.2 Choose a connection method

3.3 Wi-Fi auto-discovery and network changes

After selecting Wi-Fi connection (called Wi-Fi Control in some releases), the App automatically looks for the robot on the LAN currently used by the phone, tablet, or PC. A bound robot on the same subnet can then be connected for video, diagnostics, and firmware management.

To move a robot to another Wi-Fi network:

1. Connect the phone or tablet to the destination Wi-Fi.
2. Return to the robot's Connection Method page and select Wi-Fi connection / Wi-Fi Control.
3. If the App finds that the robot and controller are on different networks, it enters the Wi-Fi provisioning flow.
4. Confirm the destination network, finish provisioning, wait for the robot to join it, then start Wi-Fi control again.

3.4 Device Home

After a successful connection, Device Home provides entries for the current robot. On your first successful connection, check Firmware Management first, then learn Remote Control:

• Operation Mode: choose Remote Control or Touring mode;
• Diagnostics: view robot diagnostic data;
• Firmware Management: review and install robot packages;
• The top-right More menu can open Settings or Remote Assistance, depending on connection and permissions.

4. Selecting an operation mode and the remote-control interface

4.1 Operation modes

Select Operation Mode from Device Home to open the mode picker:

• Remote Control: operate the robot with virtual joysticks or an external gamepad. Read the Remote-control interface section below before first use.
• Touring: follow a prepared route. Core functionality is complete and is undergoing internal testing and optimization; it will be made generally available later.

4.2 Remote-control interface

After entering Remote Control, do not operate the joysticks yet. First verify that the video or model view, network, and battery are normal, then enable the robot if required. Opening this screen does not enable the robot or issue movement commands.

4.3 Top-bar functions and view switching

Refresh Video only refreshes the Wi-Fi video stream. Use it when video is missing, frozen, or needs to be fetched again after network recovery. Bluetooth direct connection has no video stream.

Diagnostics is a shortcut to robot-reported status. If battery, temperature, joint, or log data looks abnormal, stop remote-control activity, put the robot in a safe state, and then investigate.

Use the view switch for live video and the 3D digital-twin model. Video is best for checking the surrounding environment, footing, and actual pose; the model is best for inspecting pose and joint state.

4.4 Gamepad, virtual joystick, and control settings

The screen supports virtual joysticks, keyboard input, and external gamepads. A USB or Bluetooth gamepad connects to the phone, tablet, or PC running the App. Open the gamepad-status overlay from the right-side function island to verify connection and input state.

In Settings → Control, configure gamepad enablement, sensitivity, dead zone, translation/rotation output ranges, and hold mode. When using a gamepad for the first time, inspect input feedback with the robot stopped and begin at a low speed.

4.5 Start, stop, and safety reminders

Start Robot makes the robot ready to receive control commands; once active, the button becomes Stop Robot to exit that state. Network and battery icons are informational only and cannot replace an assessment of the site and mechanical state.

5. Settings

Open Settings from the remote-control shortcut or Profile. Available tabs include:

• Control: speed level, joystick sensitivity and dead zone, translation/rotation ranges, gamepad enablement, and hold mode;
• Video: video quality and video statistics;
• Developer: shown only after Developer mode is unlocked, for development and troubleshooting.

Use Import, Export, and Reset at lower left to manage local settings. Import only configurations from trusted sources.

6. Diagnostics

Diagnostics reads robot runtime data over Wi-Fi. Use it after the first connection, before remote control, or when something appears abnormal. On first entry, confirm DOMAIN_ID; it is the identifier used for internal robot communication and must match the robot's ROS 2 communication domain. If you do not know this value, ask the on-site technical team rather than changing it.

6.1 Diagnostics overview

The left panel identifies the diagnostic target and data-stream state; the right panel groups pages under View and Tools. Waiting for data or No data normally means that the robot has not reported that diagnostic data. Check Wi-Fi, DOMAIN_ID, and robot services instead of repeatedly operating remote control.

6.2 Logs

Select Logs to choose a current log file and view runtime records. Logs help investigate service startup, connection, and node errors. The file name and body in this screenshot are redacted.

6.3 Joint Temperature

Joint Temperature displays temperatures reported for each joint. Use filtering and paging controls to inspect the records. Stop high-load movement and follow maintenance procedures for sustained high temperature, abnormal fluctuations, or missing data. The test screenshot shows the normal empty state; actual values depend on robot reporting.

6.4 SSH Command Line

Selecting Command Line first shows the SSH credentials page. Enter an authorized username and password to create a secure terminal session; select Save this robot's password only if it should be retained on this controller. Opening the page neither connects nor runs a command. First-time users normally do not need this feature.

7. Firmware management and upgrade

Firmware Management on Device Home maintains the current robot. Firmware Upgrade on Home provides a batch-upgrade entry for multiple devices.

7.1 Firmware version and encryption requirement

When the new App detects a robot with legacy, unencrypted firmware, it shows an upgrade prompt and requires the firmware upgrade flow first. Complete the robot firmware upgrade before using connection, encryption, and sharing functions. Do not close the App, disconnect the network, or remove robot power during the upgrade.

7.2 Review upgrade packages

The page reads each package's current version, target version, and download size. Packages with an update indication can be upgraded separately or added to Upgrade Selected.

7.3 Confirm an upgrade

After selecting an individual package or Upgrade Selected, verify the packages, versions, and sizes. Start Upgrade submits a real upgrade task to the robot.

8. Remote assistance

Remote Assistance is available only when the robot is connected over Wi-Fi; it is not shown for Bluetooth direct connection.

8.1 Entry

1. Open the target robot's Device Home.
2. Select More (three dots) at top right.
3. Select Remote Assistance.

The App carries the current robot's address, display name, and serial number into the Remote Assistance page and tries to establish its network session. If no current robot is selected, the page shows LAN and historical device lists for selection.

8.2 Request assistance

The page has three stages:

1. Connect Robot: confirm the target is online and establish a WebSocket session.
2. Check Status: show device identity, robot connection state, and network connectivity checks.
3. Request Assistance: read and accept the authorization notice, select Request Assistance, and review requested, active, and closed state in the session panel.

After selecting Request Assistance, the App displays an authorization notice. It can authorize support staff to communicate via a reverse SSH tunnel, read necessary diagnostic information such as system logs, control state, and sensor data, and start or stop robot services within the authorized scope. A session is created only after selecting Agree and Request.

8.3 The robot maintains the session

Once authorized, the robot-side service starts the assistance channel. The App on the phone, tablet, or PC initiates authorization, shows session state, and provides a close entry. The session can survive App page changes and network reconnection; if the App restarts while the robot-side session is still valid, returning to Remote Assistance can recover its state.

The controller does not need to remain on the Remote Assistance page after the session is established. Keep network access available and avoid force-closing the App during assistance. Use the session's close action to end assistance; power-off or an explicit close on the robot destroys the channel.

When ready, the panel shows remaining time and provides Extend +30 minutes and Close Now. Ports, remaining time, and connection IDs are dynamic session information and must not be shared publicly.

9. Profile, About, and service pages

Profile on Home includes:

• Official website link and ticket entry. Tickets require sign-in and Local mode asks the user to sign in.
• Language switching.
• Settings and manual App-update checks.
• About VKBOTS: App version, open-source licenses, Privacy Policy, Terms of Service, export of personal data, and withdrawal of privacy consent.
• Signed-in users can sign out or cancel their account.

Developer mode is hidden by default. In the current implementation, repeatedly tapping the version number in About VKBOTS unlocks developer settings; use them only for development or maintenance.

9.1 Ticket service

Open Profile → Ticket Service. Tickets are a cloud-account service: Local mode shows that sign-in is required; after sign-in, users can view unread counts, create tickets, and communicate with support.

The ticket list shows ticket number, subject, category, linked robot, state, and last update time. A new support reply creates an unread indicator in Profile; opening a ticket marks it read.

To create a ticket, provide:

1. Issue category.
2. Subject and detailed description.
3. Contact email.
4. Related robot, selected from bound robots or entered by serial number.
5. Optional attachments such as photos or log files.

After submitting, use the ticket detail to check progress and messages, reply, and attach files. When the issue is resolved, the user can confirm closure.

10. Page coverage and access conditions

Current App routes also include sign-in, SMS verification, permission guidance, device binding, single-device OTA, batch OTA, device sharing management, Remote Assistance, an RL controller workspace, ticket list/create/detail, Privacy Policy, and Terms of Service pages.

These pages depend on sign-in state, device binding, network, robot capability, or Developer mode. For publication-quality screenshots of restricted pages, use a dedicated test account and an isolated robot; do not trigger binding, sharing, remote sessions, upgrades, or control actions on production robots.

For connection or upgrade issues, record the App version, robot name, network environment, and reproduction steps, then contact support through the ticket entry in Profile.

This document explains how a custom app can connect to and control RC ROS2 directly, as well as the interfaces exposed by RC over the local network and BLE. Local control does not depend on account login, SMS verification, or an app cloud service.

Suggested reading order

For the shortest path to a working controller:

1. Derive a deviceKey from the local password, or obtain ownerKeyHex from your customer service.
2. Bind once through BLE Provisioning or the encrypted Wi-Fi API in section 5.3.1.
3. Build the HMAC query and connect to ws://<robot>:8081/.
4. Send control.cmd_vel with flat fields in payload, then keep the link alive with control.heartbeat.

The Python walkthrough in section 8 follows this order. The HTTP map, navigation, and OTA APIs reuse the same key but use a different signature string.

1. Architecture and binding states

• Service credential mode: the app logs in to the customer service; the service issues token, ownerKeyHex, and the UID. Only binding fields are sent to the robot; the service signing secret is never released.
• Local password mode: the app does not log in or call any service. It derives the deviceKey locally and binds over BLE or encrypted Wi-Fi.
• After binding, normal WS, HTTP, and BLE control runs between the app and RC; it does not call the customer service for every command.
• The robot may still use its own robot_token for activation, heartbeat, and log upload. That cloud path is independent of app control.
• Local binding does not require a robot-side environment switch and has no temporary claim window.
• Neither an app access token nor the robot robot_token is accepted as an RC control signature.

RC has three persistent binding states:

Maintenance mode is not a fourth binding state. It is a time-limited authentication override that works while the robot is unbound, cloud, or local. It does not modify the original binding, and RC automatically falls back to the original authentication state when the maintenance credential becomes invalid.

2. BLE Provisioning protocol

2.1 Provisioning GATT

UUID base: …-b1a1-4003-8000-000000000000.

The legacy connectable BLE advertisement includes the complete Provisioning Service UUID 00000001-b1a1-4003-8000-000000000000, while the scan response carries the Complete Local Name. The app should filter by this UUID first, then connect, discover GATT, and send HELLO. The Control Service UUID is not advertised and must be obtained through GATT service discovery after connecting.

The default advertised name is BXI_<hostname>. The hostname is limited to letters, digits, -, and _, and the name is truncated after 29 UTF-8 bytes. Treat the name as display-only metadata, not device identity; use the serial number returned by HELLO_ACK as the authoritative identity.

Frame format:

[version u8=0x03][op u8][seq u8][TLV...]
Short TLV: [tag][len<=0xFE][value]
Long TLV: [tag][0xFF][len u16 little-endian][value]

2.2 HELLO_ACK

The app should send HELLO first and read the actual serial number and binding state from HELLO_ACK:

BIND_STATUS_GET returns BIND_STATUS with these fields:

3. Local password binding

3.1 Fixed identity and password derivation

Local binding uses the fixed owner UID:

ownerUid = 2147483646

The password must contain 8 to 64 printable ASCII characters, with every byte in the 0x20..0x7e range. Derive the 32-byte deviceKey as follows:

KDF        = PBKDF2-HMAC-SHA256
password   = UTF-8 password bytes
salt       = 16 cryptographically random bytes
iterations = 200000
dkLen      = 32 bytes
KDF ID     = 1

credentialId uniquely identifies this local binding and must contain 1 to 128 characters. It contains no secret and may be a UUID or an equivalent unique random string.

Store the derived deviceKey in platform secure storage such as Android Keystore, iOS Keychain, or Windows Credential Locker. Never put the password, derived key, or a maintenance credential in logs, analytics, or a plaintext settings file.

3.2 BIND_START

The app must first send HELLO and read the actual serial number from HELLO_ACK, then send:

BIND_START op=0x20
TLV 0x01 = empty; only cloud binding uses a binding credential
TLV 0x02 = credentialId UTF-8
TLV 0x03 = HELLO_ACK.sn UTF-8
TLV 0x04 = deviceKey raw bytes, exactly 32B
TLV 0x05 = bindMode u8 = 1 for a local-binding request
TLV 0x06 = ownerUid u64 LE = 2147483646
TLV 0x07 = KDF salt raw bytes, exactly 16B
TLV 0x08 = iterations u32 LE = 200000
TLV 0x09 = KDF ID u8 = 1

RC accepts this request only when the robot has been activated and is currently unbound. A local request cannot replace an existing cloud or local binding, and cloud synchronization does not overwrite a local binding.

On success, RC stores binding_mode=local, sync_state=local_only, and bind_method=ble_local_password_v1. BIND_OK returns the serial number, owner UID, credential ID, binding nonce, binding time, and key fingerprint, but never the key. Save the device relationship only after verifying that the response matches the current request.

Common BIND_FAIL codes:

3.3 Reconnecting to a locally bound robot

Another app reads the salt, iteration count, and KDF ID from HELLO_ACK or BIND_STATUS, derives the same deviceKey from the user-entered password, and compares the returned fingerprint. It must not save the credential or start control until that check succeeds.

The password and key are never uploaded to the cloud, so local mode has no cloud recovery path. If the password is lost, use a client that still holds the original key to authorize unbinding, or clear the local binding through a controlled maintenance process and bind again.

3.4 Unbinding and targeted cloud clearing

When the robot is bound, an owner holding the current deviceKey can send an authenticated BLE UNBIND:

UNBIND op = 0x23
TLV 0x01  = ts, Unix seconds, u64 little-endian
TLV 0x02  = mac, 16 bytes

payload = "unbind|" || UTF8(sn) || "|" || ts_le_8B
mac = HMAC-SHA256(deviceKeyRaw, payload)[0:16]

RC accepts requests within 60 seconds of the robot's current time. While bound, missing TLVs, an out-of-window timestamp, or an invalid HMAC is rejected silently without UNBIND_ACK; the sender must handle this as a timeout. The app currently waits five seconds by default. In the unbound/factory state, RC returns UNBIND_ACK directly. On success, RC deletes binding.json and clears the local sharing-grant records.

• Local-app unbinding does not create, remove, or synchronize any cloud user relationship.
• RC reports bindingMode in heartbeat requests and also reports localBindingCredentialId while locally bound.
• For an administrator-requested remote clear, RC requires both binding_mode=local and an exact match with the current credential ID. A stale command cannot delete a newer replacement binding.

4. HMAC authentication after binding

RC control authentication uses a credential UID, robot serial number, and 32-byte key. It does not accept an app access token and does not use the robot's robot_token. Normal control uses the owner credential in the binding record; maintenance control uses the temporary credential described in section 6.

4.1 WebSocket HMAC

message = ws|user_id|sn|ts|nonce
sig = Base64(HMAC-SHA256(deviceKeyRaw, UTF8(message)))

Connection query:

user_id=<UID>&client_id=<client-id>&sn=<SN>&ts=<Unix milliseconds>&nonce=<random value>&sig=<URL-encoded Base64 signature>

ws://<robot>:8081/?user_id=42&client_id=app&sn=BXI-A1&ts=...&nonce=...&sig=...
ws://<robot>:8081/ws/signaling?user_id=42&client_id=video_v1&sn=BXI-A1&ts=...&nonce=...&sig=...

The timestamp skew must not exceed 60 seconds. Use a new nonce for each connection. The serial number must match the binding record, and the UID must be present in the authorization list.

4.2 HTTP v2 HMAC

bodyHash = lowercaseHex(SHA256(exactRawBodyBytes))
message = http.v2|UPPER_METHOD|PATH|bodyHash|user_id|sn|ts|nonce
sig = Base64(HMAC-SHA256(deviceKeyRaw, UTF8(message)))

The request query contains:

auth_v=2&user_id=<UID>&sn=<SN>&ts=<Unix milliseconds>&nonce=<random value>&sig=<URL-encoded Base64 signature>

PATH excludes the query string. The SHA-256 hash must also be calculated for an empty body. Sign the exact final raw body bytes sent on the wire; do not reformat JSON after generating the signature.

4.3 BLE control HMAC

The protocol version is 0x03, and all multibyte fields use little-endian byte order:

22B header: <BBHffffH>
            ver, auth, seq, vx, vy, wz, height, buttons

24B header: <BBHffffHBB>
            base header + btn_slot + btn_val

tag = first8Bytes(HMAC-SHA256(deviceKeyRaw, headerBytes))
frame = headerBytes + tag

auth: 0 means no tag, 1 means HMAC4, and 2 means HMAC8. Use auth=2 in production. Maintain an increasing u16 seq for each BLE connection. RC uses a 0x8000 half-window for wraparound handling and replay prevention.

4.4 Offline guest sharing

The owner can issue a local BXIS1.<base64url(JSON)> share token. It lets a guest use WS, HTTP, and BLE without learning the owner's deviceKey. The payload fields are:

{
  "v": 1,
  "sn": "BXI-EXAMPLE-0001",
  "role": "co_owner",
  "iat": 1780000000,
  "exp": 1780000120,
  "epoch": 0,
  "jti": "unique random value for this token",
  "k": "64 hexadecimal characters encoding the subkey",
  "sig": "Base64 HMAC-SHA256 signature",
  "conn": {"i": "192.168.88.162", "p": 8081}
}

conn is an optional connection hint and is not signed. k is the connection subkey delivered to the guest. The robot does not trust this field directly; it independently derives the subkey from its local owner key and verifies the handshake signature:

shareKey = HMAC-SHA256(deviceKeyRaw, "bxi-share-key-v1|<epoch>")
tokenSig = Base64(HMAC-SHA256(shareKey,
           "bxishare.v1|<sn>|<role>|<iat>|<exp>|<epoch>|<jti>"))
subkey   = HMAC-SHA256(shareKey, "bxi-share-tx-v1|<jti>")

• For WS and HTTP, generate signatures as described in sections 4.1 and 4.2, but use subkey and include the complete share_token in the query.
• For BLE, first write a {user_id,sn,ts,nonce,sig,share_token} JSON proof to CONTROL_GUEST_AUTH. After it succeeds, use subkey for HMAC8 on that connection.
• epoch must equal share_epoch in the robot's binding.json. Incrementing the epoch lets the owner revoke every older share token at once.
• The robot registers the jti when the guest first connects before exp. A registered guest may reconnect during a sliding authorization period, currently 30 days by default and configurable through BXI_SHARE_GRANT_TTL_SEC. An expired token that was never registered is rejected.
• A share token contains the guest control subkey. Treat it like a password and never upload it to logs or analytics.

5. Interfaces exposed by RC ROS2

5.1 UDP local network discovery

The app broadcasts the following payload to UDP :8083:

{"type":"discover"}

RC broadcasts a beacon every two seconds and sends a unicast reply to discovery requests:

{
  "type": "beacon",
  "hostname": "robot_elf3_02",
  "port": 8081,
  "seq": 42,
  "sn": "BXI-EXAMPLE-0001",
  "pairing_protocol": 1
}

The beacon is for discovery only and does not prove the device's identity. Subsequent connections must still pass HMAC authentication.

pairing_protocol=1 means that the robot supports the encrypted Wi-Fi pairing protocol in section 5.3.1. LAN discovery may also open an unauthenticated one-shot probe at ws://<robot>:8081/?user_id=probe; RC returns {type:"welcome",user_id:"probe",session_id,hostname} and immediately closes the connection. A probe cannot send control commands.

5.2 WebSocket control

Standard message envelope:

{
  "type": "control.cmd_vel",
  "ts": 1780000000000,
  "seq": 1,
  "payload": {}
}

App → RC:

Velocity control fields must be flat members of payload:

{
  "type": "control.cmd_vel",
  "payload": {
    "vx": 0.2,
    "vy": 0.0,
    "wz": 0.1,
    "height": 1.0,
    "mode": "manual",
    "btn_1": 0,
    "btn_5": 1
  }
}

There is no control.acquire or control.release message. An authenticated client becomes the active controller when it sends control.cmd_vel. Disconnecting the control connection triggers a safe stop. The client should send a control frame or control.heartbeat at intervals shorter than 500 ms. A heartbeat creates a heartbeat_only ControlIntent: it refreshes the deadman timer without overwriting autonomous navigation with a zero-velocity command.

The gateway no longer implements a software E-stop or latched reset. Values mode=2 and safety_state=3 remain permanently unused; E-stop and freeze semantics belong entirely to the motion-control layer. The gateway retains only the connection deadman: after 1500 ms without a ControlIntent by default, it enters STATE_TIMEOUT=2 and zeros the command. Including the two-tick debounce and slew-rate deceleration, worst-case stopping time is approximately 2.1 seconds.

/ws/signaling accepts only offer, candidate, bye, and ping. Send logs.*, peek.*, power, and control commands through the regular / control channel.

Common RC → App messages:

The complete set of nav.* message types is:

nav.map                 nav.scan
nav.pose                nav.path.global
nav.costmap.global      nav.costmap.local
nav.footprint           nav.cloud
nav.status              nav.tour.status
nav.mapping.status      nav.runtime.status
nav.reloc_required

Grid and point-cloud payloads use gzip+base64. When a new control connection is established, the gateway replays the most recent navigation states that have latched semantics.

Digital-twin telemetry uses length-prefixed binary frames rather than JSON. The first byte is one of these tags:

5.3 HTTP REST (port 8082)

Except for CORS OPTIONS and the three exact /api/v1/pairing/* routes below, business routes use HTTP v2 HMAC. Pairing cannot use HTTP HMAC before a deviceKey exists, so section 5.3.1 protects it with an X25519 session and AES-256-GCM payloads:

Request-body limits depend on the route: 64 KB for regular and OTA routes, 8 MB for map and mapping routes, and 64 MB after decompressing a gzip grid. Oversized requests are rejected.

A map bundle always contains manifest.json, map.pcd, map.pgm, and map.yaml. A legacy_2d_only map containing only the old PGM/YAML format cannot be activated, used for navigation, or extended; it must be rebuilt with the 3D mapping flow. Extending a map creates an immutable child version and inherits the parent waypoints, regions, topology, and custom-route snapshots.

Route IDs must match [A-Za-z0-9_-]{1,64}. The default route continues to use the legacy /maps/{id}/waypoints endpoint; custom routes are stored under <id>.routes/<route_id>.json. The default route may be renamed but not deleted. Both tour/status and WS nav.tour.status include route_id; clients treat a missing field from old status payloads as default. When an old firmware returns 404 for the routes API, the new App uses only the default route.

The main fields returned by GET /api/v1/runtime/status and WS nav.runtime.status are:

current_mode, desired_mode, transition_id, active_map_id,
localized, fitness_score, inlier_ratio, driver_healthy, last_error

A 202 response from POST /api/v1/maps/{id}/activate means only that the runtime-mode transition was accepted; localization is not complete yet. The app must wait until active_map_id is correct and driver_healthy=true, and treat nav.reloc_required.required=false as the authoritative relocation-success signal. It must not send navigation goals or start a tour while localized=false.

5.3.1 Encrypted Wi-Fi pairing

Only the three exact method-and-path combinations below bypass HTTP v2 HMAC; other /api/v1/pairing/* requests do not receive the pairing exemption. Application payloads remain encrypted and authenticated.

Plaintext body for POST /api/v1/pairing/session:

For a bound session, auth is the lowercase hexadecimal HMAC-SHA256 result:

HMAC(deviceKey, "wifi-session-v1|" || mode || "|" ||
     client_public_key_bytes || "|" || client_nonce_bytes)

A successful response contains protocol, a 32-hex-character session_id, Base64 robot_public_key, Base64 robot_nonce, expires_at, a Base64 12-byte nonce, and ciphertext. Derive the session key as follows:

shared = X25519(client_private_key, robot_public_key)
session_key = HKDF-SHA256(
  IKM  = shared || PSK,
  salt = client_nonce || robot_nonce,
  info = "bxi-wifi-pairing-v1|" || hex_decode(session_id),
  len  = 32
)

Choose PSK as follows: use deviceKey for a bound non-recovery session; use the Base64-decoded signature bytes from the binding token for an unbound cloud session; use an empty value for an unbound local or read-only recovery session.

Requests and responses for POST /api/v1/pairing/bind and DELETE /api/v1/pairing/binding use this envelope:

{"session_id":"32 hex characters","nonce":"Base64 12 bytes","ciphertext":"Base64 AES-GCM ciphertext and tag"}

The AES-256-GCM plaintext must be a UTF-8 JSON object. RC serializes responses as compact canonical JSON with sorted keys. AAD must match these bytes exactly:

bxi.pairing.v1|<HTTP_METHOD>|<PATH>|<session_id>

Decrypted bind payloads:

• cloud: sn, credential_id, a 32-byte hexadecimal owner_key, and the complete token;
• local: sn, owner_uid, credential_id, a 32-byte hexadecimal owner_key, kdf_salt, kdf_iterations, and kdf_id.

The decrypted unbinding payload contains proof, the hexadecimal result of:

HMAC(deviceKey, "wifi-unbind-v1|" || session_id || "|" || sn)

Sessions expire after 60 seconds. A bind or binding request consumes the session, preventing replay.

5.4 BLE Control GATT

Send a 24-byte extended header to CONTROL_CMD. RC accepts the legacy 22-byte header without btn_slot and btn_val only for backward compatibility:

[ver u8=0x03][auth u8][seq u16 LE]
[vx f32 LE][vy f32 LE][wz f32 LE][height f32 LE]
[buttons u16 LE][btn_slot u8][btn_val u8][HMAC tag]

auth=0/1/2 means no tag, a 4-byte truncated HMAC-SHA256, or an 8-byte truncated HMAC-SHA256. The HMAC covers the complete 22- or 24-byte header. A bound robot requires auth=2 by default; an unbound factory-state robot accepts only auth=0. seq is a monotonically increasing u16 used for replay rejection. Use the buttons bitmap for regular buttons and btn_slot plus btn_val for multivalue actions.

CONTROL_MANIFEST and CONTROL_SM_STATE use chunked transfer with chunks of approximately 180 bytes:

[total_len:u16 little-endian][offset:u16 little-endian][chunk...]

Write each chunk into the receive buffer at offset, and parse the JSON only after all total_len bytes have arrived.

Status frame:

[ver u8=0x03][flags u8][safety u8]

flags: 0x01 RUNNING, 0x02 LOCKED, 0x04 FAILED, 0x08 PENDING, 0x10 UNAUTHORIZED, and 0x20 PREFLIGHT_CONFLICT. PREFLIGHT_CONFLICT means that RC found leftover robot processes before startup; the app should confirm with the user before resending a forced start action.

5.5 ROS 2 Offline TTS

bxi_offline_tts subscribes to /tts/say using std_msgs/msg/String. Plain text uses the female voice by default. To select a voice explicitly, set data to a JSON string.

# Female voice (default)
ros2 topic pub --once /tts/say std_msgs/msg/String "{data: 'Welcome to VKBOTS.'}"

# Female voice (explicit)
ros2 topic pub --once /tts/say std_msgs/msg/String \
  "data: '{\"text\":\"Welcome to VKBOTS.\",\"voice\":\"female\",\"speed\":1.0}'"

# Male voice
ros2 topic pub --once /tts/say std_msgs/msg/String \
  "data: '{\"text\":\"Welcome to VKBOTS.\",\"voice\":\"male\",\"speed\":1.0}'"

After playback succeeds or fails, the node publishes a std_msgs/msg/String JSON result on /tts/result:

{"text":"Welcome to VKBOTS.","success":true,"message":""}

A tour waypoint actions entry can also select the voice:

{"id":"say-welcome","type":"voice","content":"Welcome to VKBOTS.","voice":"male"}

Omitting voice selects female. Tour voice actions currently use a fixed speed=1.0.

6. Maintenance mode

Maintenance mode supports factory testing, repair, and on-site service. It works regardless of whether the robot is unbound, cloud-bound, or locally bound. It does not modify binding.json, cloud membership, or the original owner. The maintenance credential takes priority only for that maintenance session; after it becomes invalid, the robot continues using its original binding authentication.

6.1 Generate a credential on the robot

Use the deployment wrapper from the robot shell:

sudo /opt/bxi/bxi_rc_ros2/scripts/bxi_maintenance.sh enable
sudo /opt/bxi/bxi_rc_ros2/scripts/bxi_maintenance.sh enable --minutes 120

• The default lifetime is 1440 minutes, or 24 hours.
• The allowed range is 30 to 10080 minutes, with a maximum of 7 days.
• The command creates /var/lib/bxi/maintenance.json with mode 0600 and prints a text credential beginning with BXIM1. only once when it is created.
• When stdout is an interactive terminal and qrencode is installed, it also prints a complete ANSI UTF-8 QR code. The text credential is always printed.
• Transfer the complete credential to the app by protected copy or QR code. No account login, SMS verification, or cloud approval is required.

The wrapper uses /opt/bxi/bxi_rc_ros2 by default. CI or custom installations can override it with BXI_RC_ROS2_INSTALL_DIR. If the ROS2/install environment is already sourced, bxi-maintenance may also be run directly.

Status does not print the key again:

sudo /opt/bxi/bxi_rc_ros2/scripts/bxi_maintenance.sh status

Revoke it immediately:

sudo /opt/bxi/bxi_rc_ros2/scripts/bxi_maintenance.sh disable

Removing a maintenance code from an app only deletes that app's local copy. It does not revoke the robot-side credential. To revoke early, run disable on the robot or generate a new credential to replace the old one.

6.2 VKBOTSM1 credential

The credential format is:

BXIM1.<base64url(JSON, without padding)>

The decoded JSON contains:

{
  "version": 1,
  "credential_id": "32 lowercase hexadecimal characters",
  "user_id": 2147483645,
  "sn": "BXI-EXAMPLE-0001",
  "key_hex": "64 hexadecimal characters encoding a 32-byte key",
  "created_at": 1780000000,
  "expires_at": 1780007200
}

The app must strictly validate the prefix, exact field set, UID, serial number, key length, creation time, and expiry. The credential contains a control key and must be handled like a password: never upload it, log it, or keep it in long-term plaintext storage.

6.3 Maintenance authentication

WebSocket and HTTP use the exact HMAC formats in section 4 with the following values from the maintenance credential:

user_id = 2147483645
sn      = token.sn
key     = hexDecode(token.key_hex)

For BLE maintenance control, first write UTF-8 JSON to CONTROL_GUEST_AUTH. Its signature uses the WS message format:

{
  "maintenance": true,
  "user_id": "2147483645",
  "sn": "BXI-EXAMPLE-0001",
  "ts": "1780000000000",
  "nonce": "a new random value",
  "sig": "Base64 HMAC-SHA256 signature"
}

After connection-scoped maintenance authentication succeeds, send the HMAC8 control frames described in section 4.3 using the maintenance key. Existing WS and BLE maintenance sessions are invalidated when the credential expires, is deleted, or is replaced.

6.4 Permission boundary

A maintenance credential allows:

• motion control, state, video, and telemetry;
• log access, reboot, and shutdown;
• remote assistance;
• OTA and HTTP management operations;
• maps, navigation, mapping, and tours.

A maintenance credential does not allow:

• control.authz_set;
• device sharing or authorization-list changes;
• owner unbinding;
• creating, replacing, or changing a cloud or local binding.

7. Minimum integration flows

Local password binding:

1. Read the actual serial number, binding state, and KDF metadata from BLE HELLO_ACK.
2. Only for an unbound robot, ask the user to set a local password and generate a 16-byte salt.
3. Derive the key with PBKDF2, send the complete local BIND_START, and validate BIND_OK.
4. Save the serial number, BLE-device mapping, credential ID, and securely stored key only after binding succeeds.
5. Find the robot through a UDP beacon, BLE HELLO, or a previously saved address.
6. Generate WS, HTTP, or BLE HMAC authentication with the UID, serial number, and key.
7. Connect to :8081 for state and control; call :8082 when required, or send BLE HMAC8 control frames.

Maintenance access:

1. Generate a time-limited BXIM1 credential on the robot.
2. Import and validate it locally in the app without an app-cloud request.
3. Authenticate WS, HTTP, or BLE using the maintenance UID, serial number, and key.
4. Run sudo /opt/bxi/bxi_rc_ros2/scripts/bxi_maintenance.sh disable on the robot when service is complete.

8. Developer quick start

The examples use Python 3.10+ and the standard library for KDF, HMAC, and HTTP. Install websockets for the control connection. The same byte-level rules can be moved to Android, iOS, Flutter, or another client.

8.1 Derive the local device key

The local-password path does not call a customer service. The robot fixes the owner UID and KDF parameters; the app generates and stores the 16-byte salt with the binding record.

import hashlib


def device_key_from_password(password: str, salt_hex: str) -> bytes:
    raw = password.encode("utf-8")
    if not 8 <= len(raw) <= 64 or any(b < 0x20 or b > 0x7e for b in raw):
        raise ValueError("password must be 8..64 printable ASCII bytes")
    salt = bytes.fromhex(salt_hex)
    if len(salt) != 16:
        raise ValueError("salt must be 16 bytes")
    return hashlib.pbkdf2_hmac("sha256", raw, salt, 200_000, 32)


password = "my-robot-password"
salt_hex = "22" * 16  # Generate with secrets.token_bytes(16) in production
device_key = device_key_from_password(password, salt_hex)
print(device_key.hex())  # Example only; never log the real key

Send the resulting raw 32-byte key in the local BIND_START request, together with UID 2147483646, the salt, kdf_iterations=200000, and kdf_id=1. After BIND_OK, keep the key only in platform secure storage. The encrypted Wi-Fi flow can carry the same local-claim fields; see section 5.3.1. A mode=local,recover=true session is read-only and returns KDF metadata so a new client can verify the password before normal authentication.

8.2 Complete local bind for an unbound robot

Once the robot is activated and reachable on :8082, the local bind is just one encrypted bind request. If it has no IP yet, configure Wi-Fi first through BLE Provisioning (WIFI_SCAN / WIFI_JOIN). The following continues the Wi-Fi helper from section 5.3.1:

import secrets

# Uses open_session(), seal(), post(), and unseal() from your implementation
# of the encrypted session in section 5.3.1.

SN = "BXI-EXAMPLE-0001"  # Read from BLE HELLO_ACK
PASSWORD = "my-robot-password"
SALT = secrets.token_bytes(16)
CREDENTIAL_ID = secrets.token_urlsafe(24)

owner_key = device_key_from_password(PASSWORD, SALT.hex())
session_key, session_id, status = open_session(mode="local")
assert status == {"bound": False, "sn": SN, "binding_mode": "unbound"}

request = seal(session_key, "POST", PATH_BIND, session_id, {
    "sn": SN,
    "owner_uid": 2147483646,
    "credential_id": CREDENTIAL_ID,
    "owner_key": owner_key.hex(),
    "kdf_salt": SALT.hex(),
    "kdf_iterations": 200000,
    "kdf_id": 1,
})
result = unseal(session_key, "POST", PATH_BIND, session_id,
                post(PATH_BIND, request))
assert result["status"] == "bound" and result["sn"] == SN

Store owner_key only after checking the returned UID, serial number, credential ID, and fingerprint. The robot never returns the key. Do not log the password or key. Use this same key for the WS HMAC query in section 8.3.

8.3 Build the WS URL and an HTTP request

import base64
import hashlib
import hmac
import json
import secrets
import time
import urllib.request
from urllib.parse import urlencode

HOST = "192.168.88.162"
UID = "2147483646"
SN = "BXI-EXAMPLE-0001"
DEVICE_KEY = bytes.fromhex("11" * 32)  # Load from secure storage


def hmac_b64(message: str) -> str:
    return base64.b64encode(
        hmac.new(DEVICE_KEY, message.encode(), hashlib.sha256).digest()
    ).decode("ascii")


def ws_url(path: str = "/", client_id: str = "py_demo") -> str:
    ts = str(int(time.time() * 1000))
    nonce = secrets.token_urlsafe(18)
    query = {"user_id": UID, "client_id": client_id, "sn": SN,
             "ts": ts, "nonce": nonce,
             "sig": hmac_b64(f"ws|{UID}|{SN}|{ts}|{nonce}")}
    return f"ws://{HOST}:8081{path}?{urlencode(query)}"


def http_json(method: str, path: str, payload):
    method = method.upper()
    body = (b"" if payload is None else
            json.dumps(payload, ensure_ascii=False,
                       separators=(",", ":")).encode())
    ts = str(int(time.time() * 1000))
    nonce = secrets.token_urlsafe(18)
    digest = hashlib.sha256(body).hexdigest()
    message = f"http.v2|{method}|{path}|{digest}|{UID}|{SN}|{ts}|{nonce}"
    query = {"auth_v": "2", "user_id": UID, "sn": SN, "ts": ts,
             "nonce": nonce, "sig": hmac_b64(message)}
    request = urllib.request.Request(
        f"http://{HOST}:8082{path}?{urlencode(query)}",
        data=body if payload is not None else None,
        headers={"Content-Type": "application/json"}, method=method)
    with urllib.request.urlopen(request, timeout=10) as response:
        return json.loads(response.read())