Skip to main content

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​

FunctionWhat 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)​

CallOpening
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/kd can 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.