Robot¶

class pyniryo_nate.components.Robot(http_client: HttpClient, mqtt_client: MqttClient, correlation_id: str)[source]¶

Bases: BaseAPIComponent

Robot component for controlling robot movements and accessing robot state.

This component provides methods for: - Getting and monitoring joint positions - Moving the robot using joints, poses, waypoints, or trajectories - Managing frames and coordinate systems - Controlling robot execution (pause, resume, stop) - Jogging in manual mode

Moving the arm is direct control, which the robot accepts only when its key selector is on manual, with one exception for the program it is running. See Direct control.

Methods

`close`	Close the component and release any resources if needed.
`delete_tcp_frame`	Delete a tool center point frame created with `set_tcp_frame()`.
`execute_trajectory`	Execute a pre-computed trajectory on the robot.
`executor_status`	Get the current status of the trajectory executor.
`get_all_frames`	Get all frames defined in the robot.
`get_commands`	Returns the 5 latest commands sent by the client.
`get_configuration`	Get the robot's configuration including joint limits and PID parameters.
`get_control_mode`	Get the current control mode of the robot.
`get_frame_pose`	Get the current pose of a specific frame.
`get_joints`	Get the current joint positions of the robot.
`get_next_trajectory_waypoint`	Get the next waypoint of the trajectory currently being executed.
`get_target_speed`	Get the current target speed factor of the robot.
`get_urdf`	Get the robot's URDF (Unified Robot Description Format) description.
`jog_cartesian`	Move the active tool center point continuously at the given velocities.
`jog_cartesian_increment`	Move the active tool center point once by the given increment.
`jog_joints`	Move the joints continuously at the given velocities.
`jog_joints_increment`	Move each joint once by the given increment.
`jog_mode`	Context manager to temporarily set the robot in jog mode.
`move`	Low-level move: move the robot according to the provided target.
`move_joints`	High-level move: move the robot to the given joint positions, through `POST /api/robot/waypoints`.
`move_pose`	High-level move: move the robot to the given Cartesian pose, through `POST /api/robot/waypoints`.
`on_control_mode`	Set the callback to call when the control mode of the robot changes.
`on_frame_pose`	Set a callback to be called when the pose of a specific frame is received.
`on_jog_limit_violation`	Set the callback to call when the jog controller refuses a position increment for ending past the travel it allows on a joint, see `jog_joints_increment()`.
`on_joints`	Set the callback to call when the robot's joint positions are received.
`on_led_ring`	Set the callback to call when the light ring at the base of the robot changes.
`on_move_feedback`
`on_speed_factor`	Set the callback to call when the speed factor the robot currently applies changes.
`on_target_speed_factor`	Set the callback to call when the robot's target speed factor changes.
`pause`	Pause the current trajectory execution.
`resume`	Resume a paused trajectory execution.
`set_control_mode`	Set the control mode of the robot.
`set_frame`
`set_target_speed`	Set the target speed factor of the robot.
`set_tcp_frame`	Create or replace a tool center point frame, attached to the flange.
`stop`	Stop the current trajectory execution.
`stop_jog`	Stop the current continuous jog command.

Parameters:

http_client (HttpClient)
mqtt_client (MqttClient)
correlation_id (str)

get_joints() → Joints[source]¶

Get the current joint positions of the robot.

Returns:: The current joint positions as a Joints object.
Return type:: Joints

on_joints(callback: Callable[[Joints], None]) → Callable[[], None][source]¶

Set the callback to call when the robot’s joint positions are received.

Parameters:: callback (Callable[[Joints], None]) – The callback function that takes a Joints parameter.
Return type:: Callable[[], None]

get_all_frames() → List[str][source]¶

Get all frames defined in the robot.

Returns:: A list of frame IDs.
Return type:: List[str]

get_frame_pose(frame_id: str) → Pose[source]¶

Get the current pose of a specific frame.

Parameters:: frame_id (str) – The ID of the frame to retrieve.
Returns:: The current pose of the frame as a Pose object.
Return type:: Pose

set_tcp_frame(frame_id: str, transform: Pose) → None[source]¶

Create or replace a tool center point frame, attached to the flange.

Parameters:

frame_id (str) – The name of the frame, a ROS name token (letters, digits and underscores, not starting with a digit) of at most 36 characters.
transform (Pose) – The transform of the frame from the flange.

Raises:

ClientError – If the name is refused, or another workstation holds the robot (code == 'robot_held').

Return type:

None

delete_tcp_frame(frame_id: str) → None[source]¶

Delete a tool center point frame created with set_tcp_frame().

Parameters:: frame_id (str) – The name of the frame.
Raises:: ClientError – If the name is not a ROS name token, or another workstation holds the robot (code == 'robot_held').
Return type:: None

set_frame(frame_id: str, transform: Pose) → None[source]¶

Deprecated since version use: set_tcp_frame instead. set_frame name is too ambiguous and doesn’t reflect the fact that it only allows to set the TCP frame. It will be removed in a future release.

Parameters:

frame_id (str)
transform (Pose)

Returns:

Return type:

None

on_frame_pose(frame_id: str, callback: Callable[[Pose], None]) → Callable[[], None][source]¶

Set a callback to be called when the pose of a specific frame is received.

Parameters:

frame_id (str) – The ID of the frame to subscribe to.
callback (Callable[[Pose], None]) – The callback function that takes a Pose parameter.

Return type:

Callable[[], None]

move_joints(*joints: float | Joints) → MoveCommand[source]¶

High-level move: move the robot to the given joint positions, through POST /api/robot/waypoints. This covers POST /api/robot/joints, which the client does not expose separately.

For full trajectory control (custom planners, blending radii, multi-waypoint paths, etc.), use the low-level move() method with Waypoint objects instead.

Direct control: the key selector must be on manual, or the caller must be a program the robot is running, see Direct control.

Parameters:: joints (float | Joints) – Target joint positions in radians. Can be passed as individual floats (e.g. move_joints(0, 0, 0, 0, 0, 0)) or as a single Joints object (e.g. move_joints(Joints(0, 0, 0, 0, 0, 0))).
Returns:: A MoveCommand to track the movement progress.
Raises:: ClientError – If the robot refuses the move because its key selector is on automatic.
Return type:: MoveCommand

move_pose(*pose: float | Pose, frame_id: str | None = None, reference_frame: str | None = None, linear: bool = False) → MoveCommand[source]¶

High-level move: move the robot to the given Cartesian pose, through POST /api/robot/waypoints. This covers POST /api/robot/frames/{frame_id}/pose, which the client does not expose separately.

For full trajectory control (blending radii, velocity/acceleration factors, multi-waypoint paths, etc.), use the low-level move() method with Waypoint objects instead.

Direct control: the key selector must be on manual, or the caller must be a program the robot is running, see Direct control.

Parameters:

pose (float | Pose) – Target pose. Can be a single Pose object, or a flat sequence of floats interpreted by Pose.from_sequence() — 6 floats for (x, y, z, roll, pitch, yaw) or 7 floats for (x, y, z, qx, qy, qz, qw).
frame_id (str | None) – The frame to bring to the pose (e.g. 'eef_tcp', 'tool0'). If None, the robot’s default tool center point is used.
reference_frame (str | None) – The frame the pose is expressed in. If None, the robot’s base frame is used.
linear (bool) – If True, use linear interpolation (Planner.LIN) for a straight-line path. If False (default), use point-to-point planning (Planner.PTP).

Returns:

A MoveCommand to track the movement progress.

Raises:

ClientError – If the robot refuses the move because its key selector is on automatic.

Return type:

MoveCommand

Low-level move: move the robot according to the provided target.

This is the most flexible move method, giving full control over waypoints, planners, blending radii, velocity/acceleration factors, and multi-waypoint trajectories. If joints and pose are both provided in the same Waypoint, joints take priority.

Direct control: the key selector must be on manual, or the caller must be a program the robot is running, see Direct control.

Parameters:

target (Pose | Joints | Waypoint | list[Pose | Joints | Waypoint]) – The target to reach. Can be Joints, Pose, Waypoint, or a list of these types.
add_start (bool) – Whether to automatically prepend the current robot position as the first waypoint.
timeout (float) – Maximum time in seconds to wait before considering the move failed, counted from the moment the command is sent. Zero or a negative value means no timeout.
on_feedback (Callable[[MoveFeedback], None] | None) – Optional callback to receive MoveFeedback during the movement.

Returns:

A MoveCommand to track the movement progress.

Raises:

ClientError – If the robot refuses the move because its key selector is on automatic.

Return type:

MoveCommand

execute_trajectory(trajectory: list[JointsStamped], timeout: float = -1, on_feedback: Callable[[MoveFeedback], None] | None = None) → MoveCommand[source]¶

Execute a pre-computed trajectory on the robot.

Direct control: the key selector must be on manual, or the caller must be a program the robot is running, see Direct control.

Parameters:

trajectory (list[JointsStamped]) – The trajectory to execute. For example a trajectory generated by the motion planner.
timeout (float) – Maximum time to wait before considering a trajectory command failed.
on_feedback (Callable[[MoveFeedback], None] | None) – Optional callback to receive feedback during the trajectory.

Returns:

A MoveCommand object to track the progress of the movement.

Raises:

ClientError – If the robot refuses the move because its key selector is on automatic.

Return type:

MoveCommand

get_commands() → list[MoveCommand][source]¶

Returns the 5 latest commands sent by the client.

Returns:: A list of maximum 5 MoveCommand objects.
Return type:: list[MoveCommand]

get_urdf() → Element[source]¶

Get the robot’s URDF (Unified Robot Description Format) description.

Returns:: The root XML element of the URDF document.
Return type:: Element

get_configuration() → RobotConfiguration[source]¶

Get the robot’s configuration including joint limits and PID parameters.

Returns:: The robot configuration.
Return type:: RobotConfiguration

get_control_mode() → ControlMode[source]¶

Get the current control mode of the robot.

Returns:: The current control mode (TRAJECTORY, JOG, or SPEED).
Return type:: ControlMode

set_control_mode(mode: ControlMode) → None[source]¶

Set the control mode of the robot.

Direct control: the key selector must be on manual, or the caller must be a program the robot is running, see Direct control.

Parameters:

mode (ControlMode) – The control mode to set (TRAJECTORY, JOG, or SPEED).

Raises:

RuntimeError – If the mode could not be set.
ClientError – If the robot refuses the change because its key selector is on automatic.

Return type:

None

jog_mode() → Generator[None, Any, None][source]¶

Context manager to temporarily set the robot in jog mode. The robot will be set back to its previous control mode when exiting the context.

This context manager only sets the control mode, so it is not the guard it looks like. From an outside script it raises on automatic, on entry, and a key turned to automatic during the block makes the exit raise too, leaving the robot in jog mode. From a program it opens without a word, and the jog commands inside the block are then dropped in silence. See Direct control.

Usage: ``` with robot.jog_mode():

# Do something in jog mode …

# Back to previous control mode ```

Raises:: ClientError – If the robot refuses to set the mode because its key selector is on automatic.
Return type:: Generator[None, Any, None]

stop_jog() → None[source]¶

Stop the current continuous jog command. The robot must be in jog mode for this to work. An incremental jog is not affected and runs to completion.

Direct control: the key selector must be on manual, with no exception for a running program. On automatic the robot drops the command and answers nothing, see Direct control.

Return type:: None

jog_joints(velocity: Joints) → None[source]¶

Move the joints continuously at the given velocities. The robot must be in jog mode for this to work.

The robot decelerates to a stop when the command is not renewed within 50 ms, or on stop_jog(). See jog_joints_increment() for a one-shot move by an increment.

Direct control: the key selector must be on manual, with no exception for a running program. On automatic the robot drops the command and answers nothing, see Direct control.

Parameters:: velocity (Joints) – The joint velocities of the jog command (in rad/s).
Return type:: None

jog_joints_increment(increment: Joints) → None[source]¶

Move each joint once by the given increment. The robot must be in jog mode for this to work.

The motion runs to completion, stop_jog() does not interrupt it. An increment whose end lands past the travel the jog controller allows is refused whole and nothing moves; the controller keeps a margin on each side of a joint limit and reports that travel, see on_jog_limit_violation(). A single command carrying both an increment and velocities moves by the increment. See jog_joints() for a continuous move at a given velocity.

Direct control: the key selector must be on manual, with no exception for a running program. On automatic the robot drops the command and answers nothing, see Direct control.

Parameters:: increment (Joints) – The joint increments of the jog command (in rad), counted from the current joint positions.
Return type:: None

jog_cartesian(linear_velocity: list[float], angular_velocity: list[float], frame_id: str | None = None) → None[source]¶

Move the active tool center point continuously at the given velocities. The robot must be in jog mode for this to work.

The robot decelerates to a stop when the command is not renewed within 50 ms, or on stop_jog(). See jog_cartesian_increment() for a one-shot move by an increment.

Direct control: the key selector must be on manual, with no exception for a running program. On automatic the robot drops the command and answers nothing, see Direct control.

Parameters:

linear_velocity (list[float]) – The linear velocity of the jog command in m/s. It should be a list of 3 floats representing the velocity in the x, y and z directions.
angular_velocity (list[float]) – The angular velocity of the jog command in rad/s. It should be a list of 3 floats representing the angular velocity around the x, y and z axes.
frame_id (str | None) – The frame whose axes the velocities are expressed in, one of the names returned by get_all_frames(). Only its orientation is used. If not specified, the velocities read in the axes of the active tool center point.

Return type:

None

jog_cartesian_increment(linear_increment: list[float], angular_increment: list[float], frame_id: str | None = None) → None[source]¶

Move the active tool center point once by the given increment. The robot must be in jog mode for this to work.

The motion runs to completion, stop_jog() does not interrupt it. An increment whose path crosses a joint limit or a singularity is refused whole and nothing moves. See jog_cartesian() for a continuous move at a given velocity.

Direct control: the key selector must be on manual, with no exception for a running program. On automatic the robot drops the command and answers nothing, see Direct control.

Parameters:

linear_increment (list[float]) – The linear increment of the jog command in m, counted from the current position. It should be a list of 3 floats representing the increment in the x, y and z directions.
angular_increment (list[float]) – The angular increment of the jog command in rad, counted from the current orientation. It should be a list of 3 floats representing the angular increment around the x, y and z axes.
frame_id (str | None) – The frame whose axes the increments are expressed in, one of the names returned by get_all_frames(). Only its orientation is used. If not specified, the increments read in the axes of the active tool center point.

Return type:

None

executor_status() → TrajectoryExecutorStatus[source]¶

Get the current status of the trajectory executor.

Returns:: The current status of the trajectory executor.
Return type:: TrajectoryExecutorStatus

get_next_trajectory_waypoint() → JointsStamped | None[source]¶

Get the next waypoint of the trajectory currently being executed.

Returns:: The next waypoint, or None if there is no active trajectory or no more waypoints.
Return type:: JointsStamped | None

pause() → None[source]¶

Pause the current trajectory execution.

Return type:: None

stop() → None[source]¶

Stop the current trajectory execution.

Return type:: None

resume() → None[source]¶

Resume a paused trajectory execution.

Return type:: None

get_target_speed() → float[source]¶

Get the current target speed factor of the robot. The speed factor is a multiplier applied to the robot’s maximum speed, allowing you to slow down or speed up movements without changing the underlying trajectories. :return: The target speed factor.

Return type:: float

set_target_speed(factor: float) → float[source]¶

Set the target speed factor of the robot. :param factor: A factor comprised between 0 and 1. A factor of 1 means the robot will move at its maximum speed, while a factor of 0.5 means the robot will move at half of its maximum speed. Setting the speed factor does not change the underlying trajectories, it only scales the speed at which they are executed. :return: The target speed factor the robot applied. :raises ClientError: If another workstation holds the robot (code == 'robot_held').

Parameters:: factor (float)
Return type:: float

on_speed_factor(callback: Callable[[float], None]) → Callable[[], None][source]¶

Set the callback to call when the speed factor the robot currently applies changes. It follows the target set by set_target_speed(), capped by the safety chain.

Parameters:: callback (Callable[[float], None]) – The callback function that takes the new speed factor.
Return type:: Callable[[], None]

on_target_speed_factor(callback: Callable[[float], None]) → Callable[[], None][source]¶

Set the callback to call when the robot’s target speed factor changes.

Parameters:: callback (Callable[[float], None]) – The callback function that takes the new target speed factor.
Return type:: Callable[[], None]

on_control_mode(callback: Callable[[ControlMode], None]) → Callable[[], None][source]¶

Set the callback to call when the control mode of the robot changes.

Parameters:: callback (Callable[[ControlMode], None]) – The callback function that takes the new ControlMode.
Return type:: Callable[[], None]

on_led_ring(callback: Callable[[LedRing], None]) → Callable[[], None][source]¶

Set the callback to call when the light ring at the base of the robot changes. The state is retained, so the callback receives the current one as soon as the subscription is in place, once the robot has reported a first state.

Parameters:: callback (Callable[[LedRing], None]) – The callback function that takes the new LedRing rendering.
Return type:: Callable[[], None]

on_jog_limit_violation(callback: Callable[[JogLimitViolation], None]) → Callable[[], None][source]¶

Set the callback to call when the jog controller refuses a position increment for ending past the travel it allows on a joint, see jog_joints_increment(). The report is not retained: subscribe before sending the increment.

Parameters:: callback (Callable[[JogLimitViolation], None]) – The callback function that takes the JogLimitViolation.
Return type:: Callable[[], None]

on_move_feedback(command_id: str, callback: Callable[[MoveFeedback], None]) → Callable[[], None][source]¶

Parameters:

command_id (str)
callback (Callable[[MoveFeedback], None])

Return type:

Callable[[], None]