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 alsorun_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¶
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
- NiryoRobot.calibrate_auto()[source]¶
Start a automatic motors calibration if motors are not calibrated yet
- Return type
- NiryoRobot.need_calibration()[source]¶
Return a bool indicating whereas the robot motors need to be calibrate
- Return type
- NiryoRobot.get_learning_mode()[source]¶
Get learning mode state
- Returns
True
if learning mode is on- Return type
- NiryoRobot.set_arm_max_velocity(percentage_speed)[source]¶
Limit arm max velocity to a percentage of its maximum velocity
Joints & Pose¶
- NiryoRobot.get_joints()[source]¶
Get joints value in radians You can also use a getter
joints = robot.get_joints() joints = robot.joints
- 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
- 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)
- 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))
- NiryoRobot.move_linear_pose(*args)[source]¶
Move robot end effector pose to a (x, y, z, roll, pitch, yaw) pose with a linear trajectory
- NiryoRobot.shift_linear_pose(axis, shift_value)[source]¶
Shift robot end effector pose along one axis, with a linear trajectory
- NiryoRobot.jog_joints(*args)[source]¶
Jog robot joints’. Jog corresponds to a shift without motion planning. Values are expressed in radians.
- 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
- NiryoRobot.move_to_home_pose()[source]¶
Move to a position where the forearm lays on shoulder
- Return type
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
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
- 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
- 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
Trajectories¶
- NiryoRobot.execute_trajectory_from_poses(list_poses, dist_smoothing=0.0)[source]¶
Execute trajectory from list of poses
- 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
- NiryoRobot.execute_trajectory_saved(trajectory_name)[source]¶
Execute trajectory from Ned’s memory
- Return type
Tools¶
- 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
- 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
- NiryoRobot.open_gripper(speed=500)[source]¶
Open gripper associated to ‘gripper_id’ with a speed ‘speed’
- NiryoRobot.close_gripper(speed=500)[source]¶
Close gripper associated to ‘gripper_id’ with a speed ‘speed’
- NiryoRobot.setup_electromagnet(pin_id)[source]¶
Setup electromagnet on pin
- Parameters
pin_id (PinID) –
- Return type
- NiryoRobot.activate_electromagnet(pin_id)[source]¶
Activate electromagnet associated to electromagnet_id on pin_id
- Parameters
pin_id (PinID) –
- Return type
- NiryoRobot.deactivate_electromagnet(pin_id)[source]¶
Deactivate electromagnet associated to electromagnet_id on pin_id
- Parameters
pin_id (PinID) –
- Return type
- 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
- 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.
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
- NiryoRobot.digital_write(pin_id, digital_state)[source]¶
Set pin_id state to digital_state
- Parameters
pin_id (PinID) –
digital_state (PinState) –
- Return type
- 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
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: 1>)[source]¶
Run conveyor at id ‘conveyor_id’
- NiryoRobot.stop_conveyor(conveyor_id)[source]¶
Stop conveyor at id ‘conveyor_id’
- Parameters
conveyor_id (ConveyorID) –
- Return type
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
- 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.
- 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
- Returns
target_pose
- Return type
- NiryoRobot.get_target_pose_from_cam(workspace_name, height_offset=0.0, shape=<ObjectShape.ANY: 'ANY'>, color=<ObjectColor.ANY: '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
- 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: 'ANY'>, color=<ObjectColor.ANY: 'ANY'>)[source]¶
Picks the specified object from the workspace. This function has multiple phases:
1. detect object using the camera2. prepare the current tool for picking3. approach the object4. move down to the correct picking pose5. actuate the current tool6. lift the objectExample:
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
- 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
- Returns
object_found, object_shape, object_color
- Return type
(bool, ObjectShape, ObjectColor)
- NiryoRobot.detect_object(workspace_name, shape=<ObjectShape.ANY: 'ANY'>, color=<ObjectColor.ANY: '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
- 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
- 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.
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(value)[source]
Enumeration of Calibration Modes
- AUTO = 0
- MANUAL = 1
- class RobotAxis(value)[source]
Enumeration of Robot Axis : it used for Shift command
- X = 0
- Y = 1
- Z = 2
- ROLL = 3
- PITCH = 4
- YAW = 5
- class ToolID(value)[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(value)[source]
Enumeration of Pin Modes
- INPUT = 0
- OUTPUT = 1
- class PinState(value)[source]
Pin State is either LOW or HIGH
- LOW = 0
- HIGH = 1
- class PinID(value)[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(value)[source]
Enumeration of Conveyor IDs used for Conveyor control
- NONE = 0
- ID_1 = 12
- ID_2 = 13
- class ConveyorDirection(value)[source]
Enumeration of Conveyor Directions used for Conveyor control
- FORWARD = 1
- BACKWARD = -1
- class ObjectColor(value)[source]
Enumeration of Colors available for image processing
- RED = 'RED'
- BLUE = 'BLUE'
- GREEN = 'GREEN'
- ANY = 'ANY'
- class ObjectShape(value)[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