C++ API: ulixarm_cpp
#include <ulixarm_cpp/ulixarm.hpp>
ulixarm::UlixArm robot(/*gripper=*/true);
Vectors are ulixarm::Joints (Eigen::Matrix<double, 6, 1>, one value per joint, J1 to J6).
Angles in rad, torques in Nm. Errors are thrown as exceptions; robot.log_errors(e) prints the
full chain of causes. Not installed yet? See Getting Started.
Source: github.com/itacarobotics/ulixarm_cpp.
The API is the same as in Python; this page focuses on the C++ specifics.
Overview
| Function | What it does |
|---|---|
| Setup | |
UlixArm(gripper, camera, urdf_path) | Create the robot object and load its model |
connect(port) | Open the USB connection |
disconnect() | Close the connection (motors keep the last command) |
enable() | Power the motors on |
disable() | Power the motors off ⚠️ the arm falls |
| Motion | |
control(q, dq, tau, kp, kd, gravity) | Send one impedance command to the 6 joints |
hold() | Keep the current pose |
| State | |
refresh() | Read fresh motor data without moving |
get_q(), get_dq(), get_tau() | Joint positions, velocities, torques |
get_tmos(), get_trot() | Motor temperatures |
| Gripper | |
open(), open_width(m), open_ratio(r) | Open the gripper |
close(), close(f) | Close the gripper with a grip strength |
| Errors | |
log_errors(e) | Print an exception and its nested causes |
Setup
UlixArm()
explicit UlixArm(bool gripper = true, bool camera = false, const std::string& urdf_path = "");
Creates the robot object and loads the model used for gravity compensation. Does not talk to the
hardware yet. Set gripper and camera to match what is mounted. gripper=false, camera=true
throws std::invalid_argument.
The URDF is taken from the first location that exists:
urdf_path, $ULIXARM_DESCRIPTION_PATH/urdf/, the install prefix, then the source tree.
connect(port)
Opens the USB connection (e.g. "/dev/ttyACM0") and checks that every motor is correctly configured.
disconnect()
Closes the connection. The motors stay enabled and keep the last command: call hold() before.
enable()
Powers the motors on. Call it only with the arm in the resting position: until the first
control() or hold(), the motors apply no holding torque.
disable()
Powers the motors off. The arm falls under its own weight: move it to the resting position first.
Motion
control()
void control(const Joints& q_target, const Joints& dq_target, const Joints& tau_target,
const Joints& kp, const Joints& kd, bool gravity);
Sends one command to the six joints and reads back their state. Each joint behaves like a spring-damper pulled toward the target:
tau = kp * (q_target - q) + kd * (dq_target - dq) + tau_target [+ gravity torque]
Call it in a loop. Rejected (exception) if a target is outside the joint limits, if a joint with
kp > 0 would jump more than 0.2 rad, or if a motor is above 90 °C. Its success path does not
allocate, so it is suitable for realtime loops. It does not move the gripper.
Example: move joint 1 by 0.5 rad, smoothly
using ulixarm::Joints;
const Joints q0 = robot.get_q();
Joints goal = q0;
goal[0] += 0.5;
const Joints kp = Joints::Constant(20.0);
const Joints kd = Joints::Constant(1.0);
const Joints zero = Joints::Zero();
const int steps = 500; // small steps, never > 0.2 rad
for (int i = 0; i <= steps; ++i)
{
const double s = double(i) / steps;
robot.control(q0 + s * (goal - q0), zero, zero, kp, kd, /*gravity=*/true);
}
hold()
Keeps the arm at its current pose with predefined gains. Use it after enable(), before
disconnect() and whenever you stop sending commands. Not monitored: drift is not detected.
State
refresh()
Reads the latest motor data without commanding. Needed only at start-up.
get_q(), get_dq(), get_tau()
Joint positions [rad], velocities [rad/s] and torques [Nm] from the last feedback. Throw if the data is older than 500 ms.
get_tmos(), get_trot()
Driver (MOSFET) and motor winding temperatures [°C]. Commands are rejected above 90 °C, with a warning from 70 °C.
Gripper
open(), open_width(m), open_ratio(r)
| Call | Opening |
|---|---|
open() | default, 80 % |
open_width(m) | m metres between the fingers, 0.0 to 0.090 |
open_ratio(r) | fraction, 0.0 (closed) to 1.0 (fully open) |
close(), close(f)
Closes until the fingers meet the object, with strength f from 0.0 (gentle) to 1.0 (maximum).
The default is 0.5. The motors must be enabled.
Example: pick an object
#include <chrono>
#include <thread>
using namespace std::chrono_literals;
robot.open_width(0.06); // 6 cm, a bit wider than the object
std::this_thread::sleep_for(1s);
// ... move the arm around the object with control() ...
robot.close(0.4); // moderate grip
std::this_thread::sleep_for(1s);
The gripper functions do not block: wait (or keep calling control()) while the fingers move.
Errors
log_errors(e)
try { robot.connect("/dev/ttyACM0"); robot.enable(); }
catch (const std::exception& e) { robot.log_errors(e); return 1; }
Limitations and known risks
- No brakes.
disable(), a power cut or the emergency stop make the arm fall. - Motors keep the last command after your program stops or crashes. If it was torque-only
(
kp = 0), the arm is not held. - No collision detection, neither with itself nor with the environment.
- Gains are not checked. High
kp/kdcan make the arm oscillate or move violently: start low (e.g.kp = 20,kd = 1) and increase gradually. hold()is not a safety function: drift is not detected.- The limits above are software checks, not certified safety functions. The technical manual takes precedence.
- Gripper payload is 0.3 kg; always test that the grasp is secure.