PyNiryo API Documentation

This file presents the different Command functions, Enums & Python object classes available with the API.

Command functions are used to deal directly with the robot. It could be move_joints(), get_hardware_status() vision_pick(), or also run_conveyor()
Enums are used to pass specific arguments to functions. For instance PinState, ConveyorDirection, …
Python object classes, as PoseObject, ease some operations

Command functions

This section references all existing functions to control your robot, which includes:

Moving the robot
Using Vision
Controlling Conveyor Belts
Playing with Hardware

All functions to control the robot are accessible via an instance of the class NiryoRobot

robot = NiryoRobot(<robot_ip_address>)

See examples on Examples: Basics

List of functions subsections:

TCP Connection 

NiryoRobot.connect(ip_address)[source]

Connect to the TCP Server

Parameters:: ip_address (str) – IP Address
Return type:: None

NiryoRobot.close_connection()[source]

Close connection with robot

Return type:: None

Main purpose functions 

NiryoRobot.calibrate(calibrate_mode)[source]

Calibrate (manually or automatically) motors. Automatic calibration will do nothing if motors are already calibrated

Parameters:: calibrate_mode (CalibrateMode) – Auto or Manual
Return type:: None

NiryoRobot.calibrate_auto()[source]

Start a automatic motors calibration if motors are not calibrated yet

Return type:: None

NiryoRobot.need_calibration()[source]

Return a bool indicating whereas the robot motors need to be calibrate

Return type:: bool

NiryoRobot.get_learning_mode()[source]

Get learning mode state

Returns:: True if learning mode is on
Return type:: bool

NiryoRobot.set_learning_mode(enabled)[source]

Set learning mode if param is True, else turn it off

Parameters:: enabled (bool) – True or False
Return type:: None

NiryoRobot.set_arm_max_velocity(percentage_speed)[source]

Limit arm max velocity to a percentage of its maximum velocity

Parameters:: percentage_speed (int) – Should be between 1 & 100
Return type:: None

NiryoRobot.set_jog_control(enabled)[source]

Set jog control mode if param is True, else turn it off

Parameters:: enabled (bool) – True or False
Return type:: None

static NiryoRobot.wait(duration)[source]

Wait for a certain time

Parameters:: duration (float) – duration in seconds
Return type:: None

Joints & Pose 

NiryoRobot.get_joints()[source]

Get joints value in radians You can also use a getter

joints = robot.get_joints()
joints = robot.joints

Returns:: List of joints value
Return type:: list[float]

NiryoRobot.get_pose()[source]

Get end effector link pose as [x, y, z, roll, pitch, yaw]. x, y & z are expressed in meters / roll, pitch & yaw are expressed in radians You can also use a getter

pose = robot.get_pose()
pose = robot.pose

Return type:: PoseObject

NiryoRobot.get_pose_quat()[source]

Get end effector link pose in Quaternion coordinates

Returns:: Position and quaternion coordinates concatenated in a list : [x, y, z, qx, qy, qz, qw]
Return type:: list[float]

NiryoRobot.move_joints(*args)[source]

Move robot joints. Joints are expressed in radians.

All lines of the next example realize the same operation:

robot.joints = [0.2, 0.1, 0.3, 0.0, 0.5, 0.0]
robot.move_joints([0.2, 0.1, 0.3, 0.0, 0.5, 0.0])
robot.move_joints(0.2, 0.1, 0.3, 0.0, 0.5, 0.0)

Parameters:: args (Union[list[float], tuple[float]]) – either 6 args (1 for each joints) or a list of 6 joints
Return type:: None

NiryoRobot.move_pose(*args)[source]

Move robot end effector pose to a (x, y, z, roll, pitch, yaw) pose. x, y & z are expressed in meters / roll, pitch & yaw are expressed in radians

All lines of the next example realize the same operation:

robot.pose = [0.2, 0.1, 0.3, 0.0, 0.5, 0.0]
robot.move_pose([0.2, 0.1, 0.3, 0.0, 0.5, 0.0])
robot.move_pose(0.2, 0.1, 0.3, 0.0, 0.5, 0.0)
robot.move_pose(PoseObject(0.2, 0.1, 0.3, 0.0, 0.5, 0.0))

Parameters:: args (Union[tuple[float], list[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.move_linear_pose(*args)[source]

Move robot end effector pose to a (x, y, z, roll, pitch, yaw) pose with a linear trajectory

Parameters:: args (Union[tuple[float], list[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.shift_pose(axis, shift_value)[source]

Shift robot end effector pose along one axis

Parameters:

axis (RobotAxis) – Axis along which the robot is shifted
shift_value (float) – In meter for X/Y/Z and radians for roll/pitch/yaw

Return type:

None

NiryoRobot.shift_linear_pose(axis, shift_value)[source]

Shift robot end effector pose along one axis, with a linear trajectory

Parameters:

axis (RobotAxis) – Axis along which the robot is shifted
shift_value (float) – In meter for X/Y/Z and radians for roll/pitch/yaw

Return type:

None

NiryoRobot.jog_joints(*args)[source]

Jog robot joints’. Jog corresponds to a shift without motion planning. Values are expressed in radians.

Parameters:: args (Union[list[float], tuple[float]]) – either 6 args (1 for each joints) or a list of 6 joints offset
Return type:: None

NiryoRobot.jog_pose(*args)[source]

Jog robot end effector pose Jog corresponds to a shift without motion planning Arguments are [dx, dy, dz, d_roll, d_pitch, d_yaw] dx, dy & dz are expressed in meters / d_roll, d_pitch & d_yaw are expressed in radians

Parameters:: args (Union[list[float], tuple[float]]) – either 6 args (1 for each coordinates) or a list of 6 offset
Return type:: None

NiryoRobot.move_to_home_pose()[source]

Move to a position where the forearm lays on shoulder

Return type:: None

NiryoRobot.go_to_sleep()[source]

Go to home pose and activate learning mode

Return type:: None

NiryoRobot.forward_kinematics(*args)[source]

Compute forward kinematics of a given joints configuration and give the associated spatial pose

Parameters:: args (Union[list[float], tuple[float]]) – either 6 args (1 for each joints) or a list of 6 joints
Return type:: PoseObject

NiryoRobot.inverse_kinematics(*args)[source]

Compute inverse kinematics

Parameters:: args (Union[tuple[float], list[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Returns:: List of joints value
Return type:: list[float]

Saved Poses 

NiryoRobot.get_pose_saved(pose_name)[source]

Get pose saved in from Ned’s memory

Parameters:: pose_name (str) – Pose name in robot’s memory
Returns:: Pose associated to pose_name
Return type:: PoseObject

NiryoRobot.save_pose(pose_name, *args)[source]

Save pose in robot’s memory

Parameters:: args (Union[list[float], tuple[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.delete_pose(pose_name)[source]

Delete pose from robot’s memory

Return type:: None

NiryoRobot.get_saved_pose_list()[source]

Get list of poses’ name saved in robot memory

Return type:: list[str]

Pick & Place 

NiryoRobot.pick_from_pose(*args)[source]

Execute a picking from a pose.

A picking is described as :

* going over the object
* going down until height = z
* grasping with tool
* going back over the object

Parameters:: args (Union[list[float], tuple[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.place_from_pose(*args)[source]

Execute a placing from a position.

A placing is described as :

* going over the place
* going down until height = z
* releasing the object with tool
* going back over the place

Parameters:: args (Union[list[float], tuple[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.pick_and_place(pick_pose, place_pos, dist_smoothing=0.0)[source]

Execute a pick then a place

Parameters:

pick_pose (Union[list[float], PoseObject]) – Pick Pose : [x, y, z, roll, pitch, yaw] or PoseObject
place_pos (Union[list[float], PoseObject]) – Place Pose : [x, y, z, roll, pitch, yaw] or PoseObject
dist_smoothing (float) – Distance from waypoints before smoothing trajectory

Return type:

None

Trajectories 

NiryoRobot.get_trajectory_saved(trajectory_name)[source]

Get trajectory saved in Ned’s memory

Returns:: Trajectory
Return type:: list[list[float]]

NiryoRobot.execute_trajectory_from_poses(list_poses, dist_smoothing=0.0)[source]

Execute trajectory from list of poses

Parameters:

list_poses (list[list[float]]) – List of [x,y,z,qx,qy,qz,qw] or list of [x,y,z,roll,pitch,yaw]
dist_smoothing (float) – Distance from waypoints before smoothing trajectory

Return type:

None

NiryoRobot.execute_trajectory_from_poses_and_joints(list_pose_joints, list_type=None, dist_smoothing=0.0)[source]

Execute trajectory from list of poses and joints

Parameters:

list_pose_joints (list[list[float]]) – List of [x,y,z,qx,qy,qz,qw] or list of [x,y,z,roll,pitch,yaw] or a list of [j1,j2,j3,j4,j5,j6]
list_type (list[string]) – List of string ‘pose’ or ‘joint’, or [‘pose’] (if poses only) or [‘joint’] (if joints only). If None, it is assumed there are only poses in the list.
dist_smoothing (float) – Distance from waypoints before smoothing trajectory

Return type:

None

NiryoRobot.execute_trajectory_saved(trajectory_name)[source]

Execute trajectory from Ned’s memory

Return type:: None

NiryoRobot.save_trajectory(trajectory_name, list_poses)[source]

Save trajectory in robot memory

Parameters:: list_poses (list[list[float]]) – List of [x,y,z,qx,qy,qz,qw] or list of [x,y,z,roll,pitch,yaw]
Return type:: None

NiryoRobot.delete_trajectory(trajectory_name)[source]

Delete trajectory from robot’s memory

Return type:: None

NiryoRobot.get_saved_trajectory_list()[source]

Get list of trajectories’ name saved in robot memory

Return type:: list[str]

Tools 

NiryoRobot.get_current_tool_id()[source]

Get equipped tool Id

Return type:: ToolID

NiryoRobot.update_tool()[source]

Update equipped tool

Return type:: None

NiryoRobot.grasp_with_tool()[source]

Grasp with tool | This action correspond to | - Close gripper for Grippers | - Pull Air for Vacuum pump | - Activate for Electromagnet

Return type:: None

NiryoRobot.release_with_tool()[source]

Release with tool | This action correspond to | - Open gripper for Grippers | - Push Air for Vacuum pump | - Deactivate for Electromagnet

Return type:: None

NiryoRobot.open_gripper(speed=500)[source]

Open gripper associated to ‘gripper_id’ with a speed ‘speed’

Parameters:: speed (int) – Between 100 & 1000
Return type:: None

NiryoRobot.close_gripper(speed=500)[source]

Close gripper associated to ‘gripper_id’ with a speed ‘speed’

Parameters:: speed (int) – Between 100 & 1000
Return type:: None

NiryoRobot.pull_air_vacuum_pump()[source]

Pull air of vacuum pump

Return type:: None

NiryoRobot.push_air_vacuum_pump()[source]

Push air of vacuum pump

Return type:: None

NiryoRobot.setup_electromagnet(pin_id)[source]

Setup electromagnet on pin

Parameters:: pin_id (PinID)
Return type:: None

NiryoRobot.activate_electromagnet(pin_id)[source]

Activate electromagnet associated to electromagnet_id on pin_id

Parameters:: pin_id (PinID)
Return type:: None

NiryoRobot.deactivate_electromagnet(pin_id)[source]

Deactivate electromagnet associated to electromagnet_id on pin_id

Parameters:: pin_id (PinID)
Return type:: None

NiryoRobot.enable_tcp(enable=True)[source]

Enables or disables the TCP function (Tool Center Point). If activation is requested, the last recorded TCP value will be applied. The default value depends on the gripper equipped. If deactivation is requested, the TCP will be coincident with the tool_link.

Parameters:: enable (Bool) – True to enable, False otherwise.
Return type:: None

NiryoRobot.set_tcp(*args)[source]

Activates the TCP function (Tool Center Point) and defines the transformation between the tool_link frame and the TCP frame.

Parameters:: args (Union[list[float], tuple[float], PoseObject]) – either 6 args (1 for each coordinates) or a list of 6 coordinates or a PoseObject
Return type:: None

NiryoRobot.reset_tcp()[source]

Reset the TCP (Tool Center Point) transformation. The TCP will be reset according to the tool equipped.

Return type:: None

NiryoRobot.tool_reboot()[source]

Reboot the motor of the tool equipped. Useful when an Overload error occurs. (cf HardwareStatus)

Return type:: None

Hardware 

NiryoRobot.set_pin_mode(pin_id, pin_mode)[source]

Set pin number pin_id to mode pin_mode

Parameters:

pin_id (PinID)
pin_mode (PinMode)

Return type:

None

NiryoRobot.digital_write(pin_id, digital_state)[source]

Set pin_id state to digital_state

Parameters:

pin_id (PinID)
digital_state (PinState)

Return type:

None

NiryoRobot.digital_read(pin_id)[source]

Read pin number pin_id and return its state

Parameters:: pin_id (PinID)
Return type:: PinState

NiryoRobot.get_hardware_status()[source]

Get hardware status : Temperature, Hardware version, motors names & types …

Returns:: Infos contains in a HardwareStatusObject
Return type:: HardwareStatusObject

NiryoRobot.get_digital_io_state()[source]

Get Digital IO state : Names, modes, states

Returns:: List of DigitalPinObject instance
Return type:: list[DigitalPinObject]

Conveyor 

NiryoRobot.set_conveyor()[source]

Activate a new conveyor and return its ID

Returns:: New conveyor ID
Return type:: ConveyorID

NiryoRobot.unset_conveyor(conveyor_id)[source]

Remove specific conveyor.

Parameters:: conveyor_id (ConveyorID) – Basically, ConveyorID.ONE or ConveyorID.TWO

NiryoRobot.run_conveyor(conveyor_id, speed=50, direction=ConveyorDirection.FORWARD)[source]

Run conveyor at id ‘conveyor_id’

Parameters:

conveyor_id (ConveyorID)
speed (int)
direction (ConveyorDirection)

Return type:

None

NiryoRobot.stop_conveyor(conveyor_id)[source]

Stop conveyor at id ‘conveyor_id’

Parameters:: conveyor_id (ConveyorID)
Return type:: None

NiryoRobot.control_conveyor(conveyor_id, control_on, speed, direction)[source]

Control conveyor at id ‘conveyor_id’

Parameters:

conveyor_id (ConveyorID)
control_on (bool)
speed (int) – New speed which is a percentage of maximum speed
direction (ConveyorDirection) – Conveyor direction

Return type:

None

NiryoRobot.get_connected_conveyors_id()[source]

Returns:: List of the connected conveyors’ ID
Return type:: list[ConveyorID]

Vision 

NiryoRobot.get_img_compressed()[source]

Get image from video stream in a compressed format. Use uncompress_image from the vision package to uncompress it

Returns:: string containing a JPEG compressed image
Return type:: str

NiryoRobot.set_brightness(brightness_factor)[source]

Modify video stream brightness

Parameters:: brightness_factor (float) – How much to adjust the brightness. 0.5 will give a darkened image, 1 will give the original image while 2 will enhance the brightness by a factor of 2.
Return type:: None

NiryoRobot.set_contrast(contrast_factor)[source]

Modify video stream contrast

Parameters:: contrast_factor (float) – While a factor of 1 gives original image. Making the factor towards 0 makes the image greyer, while factor>1 increases the contrast of the image.
Return type:: None

NiryoRobot.set_saturation(saturation_factor)[source]

Modify video stream saturation

Parameters:: saturation_factor (float) – How much to adjust the saturation. 0 will give a black and white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.
Return type:: None

NiryoRobot.get_image_parameters()[source]

Get last stream image parameters: Brightness factor, Contrast factor, Saturation factor.

Brightness factor: How much to adjust the brightness. 0.5 will give a darkened image, 1 will give the original image while 2 will enhance the brightness by a factor of 2.

Contrast factor: A factor of 1 gives original image. Making the factor towards 0 makes the image greyer, while factor>1 increases the contrast of the image.

Saturation factor: 0 will give a black and white image, 1 will give the original image while 2 will enhance the saturation by a factor of 2.

Returns:: Brightness factor, Contrast factor, Saturation factor
Return type:: float, float, float

NiryoRobot.get_target_pose_from_rel(workspace_name, height_offset, x_rel, y_rel, yaw_rel)[source]

Given a pose (x_rel, y_rel, yaw_rel) relative to a workspace, this function returns the robot pose in which the current tool will be able to pick an object at this pose.

The height_offset argument (in m) defines how high the tool will hover over the workspace. If height_offset = 0, the tool will nearly touch the workspace.

Parameters:

workspace_name (str) – name of the workspace
height_offset (float) – offset between the workspace and the target height
x_rel (float) – x relative pose (between 0 and 1)
y_rel (float) – y relative pose (between 0 and 1)
yaw_rel (float) – Angle in radians

Returns:

target_pose

Return type:

PoseObject

NiryoRobot.get_target_pose_from_cam(workspace_name, height_offset=0.0, shape=ObjectShape.ANY, color=ObjectColor.ANY)[source]

First detects the specified object using the camera and then returns the robot pose in which the object can be picked with the current tool

Parameters:

workspace_name (str) – name of the workspace
height_offset (float) – offset between the workspace and the target height
shape (ObjectShape) – shape of the target
color (ObjectColor) – color of the target

Returns:

object_found, object_pose, object_shape, object_color

Return type:

(bool, PoseObject, ObjectShape, ObjectColor)

NiryoRobot.vision_pick(workspace_name, height_offset=0.0, shape=ObjectShape.ANY, color=ObjectColor.ANY)[source]

Picks the specified object from the workspace. This function has multiple phases:

detect object using the camera 
prepare the current tool for picking 
approach the object 
move down to the correct picking pose 
actuate the current tool 
lift the object

Example:

robot = NiryoRobot(ip_address="x.x.x.x")
robot.calibrate_auto()
robot.move_pose(<observation_pose>)
obj_found, shape_ret, color_ret = robot.vision_pick(<workspace_name>,
                                                    height_offset=0.0,
                                                    shape=ObjectShape.ANY,
                                                    color=ObjectColor.ANY)

Parameters:

workspace_name (str) – name of the workspace
height_offset (float) – offset between the workspace and the target height
shape (ObjectShape) – shape of the target
color (ObjectColor) – color of the target

Returns:

object_found, object_shape, object_color

Return type:

(bool, ObjectShape, ObjectColor)

NiryoRobot.move_to_object(workspace_name, height_offset, shape, color)[source]

Same as get_target_pose_from_cam but directly moves to this position

Parameters:

workspace_name (str) – name of the workspace
height_offset (float) – offset between the workspace and the target height
shape (ObjectShape) – shape of the target
color (ObjectColor) – color of the target

Returns:

object_found, object_shape, object_color

Return type:

(bool, ObjectShape, ObjectColor)

NiryoRobot.detect_object(workspace_name, shape=ObjectShape.ANY, color=ObjectColor.ANY)[source]

Detect object in workspace and return its pose and characteristics

Parameters:

workspace_name (str) – name of the workspace
shape (ObjectShape) – shape of the target
color (ObjectColor) – color of the target

Returns:

object_found, object_pose, object_shape, object_color

Return type:

(bool, PoseObject, str, str)

NiryoRobot.get_camera_intrinsics()[source]

Get calibration object: camera intrinsics, distortions coefficients

Returns:: camera intrinsics, distortions coefficients
Return type:: (list[list[float]], list[list[float]])

NiryoRobot.save_workspace_from_robot_poses(workspace_name, pose_origin, pose_2, pose_3, pose_4)[source]

Save workspace by giving the poses of the robot to point its 4 corners with the calibration Tip. Corners should be in the good order. Markers’ pose will be deduced from these poses

Poses should be either a list [x, y, z, roll, pitch, yaw] or a PoseObject

Parameters:

workspace_name (str) – workspace name, maximum lenght 30 char.
pose_origin (Union[list[float], PoseObject])
pose_2 (Union[list[float], PoseObject])
pose_3 (Union[list[float], PoseObject])
pose_4 (Union[list[float], PoseObject])

Return type:

None

NiryoRobot.save_workspace_from_points(workspace_name, point_origin, point_2, point_3, point_4)[source]

Save workspace by giving the points of worskpace’s 4 corners. Points are written as [x, y, z] Corners should be in the good order.

Parameters:

workspace_name (str) – workspace name, maximum lenght 30 char.
point_origin (list[float])
point_2 (list[float])
point_3 (list[float])
point_4 (list[float])

Return type:

None

NiryoRobot.delete_workspace(workspace_name)[source]

Delete workspace from robot’s memory

Parameters:: workspace_name (str)
Return type:: None

NiryoRobot.get_workspace_ratio(workspace_name)[source]

Get workspace ratio from robot’s memory

Parameters:: workspace_name (str)
Return type:: float

NiryoRobot.get_workspace_list()[source]

Get list of workspaces’ name store in robot’s memory

Return type:: list[str]

Enums

Enums are used to pass specific parameters to functions.

For instance, shift_pose() will need a parameter from RobotAxis enum

robot.shift_pose(RobotAxis.Y, 0.15)

List of enums:

CalibrateMode
RobotAxis
ToolID
PinMode
PinState
PinID
ConveyorID
ConveyorDirection
ObjectColor
ObjectShape

class CalibrateMode(*values)[source]

Enumeration of Calibration Modes

AUTO = 0

MANUAL = 1

class RobotAxis(*values)[source]

Enumeration of Robot Axis : it used for Shift command

X = 0

Y = 1

Z = 2

ROLL = 3

PITCH = 4

YAW = 5

class ToolID(*values)[source]

Enumeration of Tools IDs

NONE = 0

GRIPPER_1 = 11

GRIPPER_2 = 12

GRIPPER_3 = 13

ELECTROMAGNET_1 = 30

VACUUM_PUMP_1 = 31

class PinMode(*values)[source]

Enumeration of Pin Modes

INPUT = 0

OUTPUT = 1

class PinState(*values)[source]

Pin State is either LOW or HIGH

LOW = 0

HIGH = 1

class PinID(*values)[source]

Enumeration of Robot Pins

GPIO_1A = 0

GPIO_1B = 1

GPIO_1C = 2

GPIO_2A = 3

GPIO_2B = 4

GPIO_2C = 5

class ConveyorID(*values)[source]

Enumeration of Conveyor IDs used for Conveyor control

NONE = 0

ID_1 = 12

ID_2 = 13

class ConveyorDirection(*values)[source]

Enumeration of Conveyor Directions used for Conveyor control

FORWARD = 1

BACKWARD = -1

class ObjectColor(*values)[source]

Enumeration of Colors available for image processing

RED = 'RED'

BLUE = 'BLUE'

GREEN = 'GREEN'

ANY = 'ANY'

class ObjectShape(*values)[source]

Enumeration of Shapes available for image processing

SQUARE = 'SQUARE'

CIRCLE = 'CIRCLE'

ANY = 'ANY'

Python object classes

Special objects

class PoseObject(x, y, z, roll, pitch, yaw)[source]

Pose object which stores x, y, z, roll, pitch & yaw parameters

copy_with_offsets(x_offset=0.0, y_offset=0.0, z_offset=0.0, roll_offset=0.0, pitch_offset=0.0, yaw_offset=0.0)[source]

Create a new pose from copying from copying actual pose with offsets

Return type:: PoseObject

to_list()[source]

Return a list [x, y, z, roll, pitch, yaw] corresponding to the pose’s parameters

Return type:: list[float]

class HardwareStatusObject(rpi_temperature, hardware_version, connection_up, error_message, calibration_needed, calibration_in_progress, motor_names, motor_types, motors_temperature, motors_voltage, hardware_errors)[source]: Object used to store every hardware information

class DigitalPinObject(pin_id, name, mode, state)[source]: Object used to store information on digital pins