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:
Main purpose functions¶
- class NiryoRobot(ip_address=None)[source]
- 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
- calibrate_auto()[source]
Start a automatic motors calibration if motors are not calibrated yet
- Return type
- need_calibration()[source]
Return a bool indicating whereas the robot motors need to be calibrate
- Return type
- get_learning_mode()[source]
Get learning mode state
- Returns
Trueif learning mode is on- Return type
- set_learning_mode(enabled)[source]
Set learning mode if param is
True, else turn it off
- set_arm_max_velocity(percentage_speed)[source]
Limit arm max velocity to a percentage of its maximum velocity
- set_jog_control(enabled)[source]
Set jog control mode if param is True, else turn it off
Joints & Pose¶
- class NiryoRobot(ip_address=None)[source]
- get_joints()[source]
Get joints value in radians You can also use a getter
joints = robot.get_joints() joints = robot.joints
- 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
- get_pose_quat()[source]
Get end effector link pose in Quaternion coordinates
- 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)
- 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))
- move_linear_pose(*args)[source]
Move robot end effector pose to a (x, y, z, roll, pitch, yaw) pose with a linear trajectory
- shift_pose(axis, shift_value)[source]
Shift robot end effector pose along one axis
- shift_linear_pose(axis, shift_value)[source]
Shift robot end effector pose along one axis, with a linear trajectory
- jog_joints(*args)[source]
Jog robot joints’. Jog corresponds to a shift without motion planning. Values are expressed in radians.
- 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
- forward_kinematics(*args)[source]
Compute forward kinematics of a given joints configuration and give the associated spatial pose
Saved Poses¶
Pick & Place¶
- class NiryoRobot(ip_address=None)[source]
- 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
- 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
- pick_and_place(pick_pose, place_pos, dist_smoothing=0.0)[source]
Execute a pick then a place
- Parameters
- Return type
Trajectories¶
- class NiryoRobot(ip_address=None)[source]
- get_trajectory_saved(trajectory_name)[source]
Get trajectory saved in Ned’s memory
- execute_trajectory_saved(trajectory_name)[source]
Execute trajectory from Ned’s memory
- Return type
- execute_trajectory_from_poses(list_poses, dist_smoothing=0.0)[source]
Execute trajectory from list of poses
- save_trajectory(trajectory_name, list_poses)[source]
Save trajectory in robot memory
Tools¶
- class NiryoRobot(ip_address=None)[source]
- get_current_tool_id()[source]
Get equipped tool Id
- Return type
ToolID
- 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
- 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
- open_gripper(speed=500)[source]
Open gripper associated to ‘gripper_id’ with a speed ‘speed’
- close_gripper(speed=500)[source]
Close gripper associated to ‘gripper_id’ with a speed ‘speed’
- setup_electromagnet(pin_id)[source]
Setup electromagnet on pin
- Parameters
pin_id (PinID) –
- Return type
- activate_electromagnet(pin_id)[source]
Activate electromagnet associated to electromagnet_id on pin_id
- Parameters
pin_id (PinID) –
- Return type
- deactivate_electromagnet(pin_id)[source]
Deactivate electromagnet associated to electromagnet_id on pin_id
- Parameters
pin_id (PinID) –
- Return type
- 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
- set_tcp(*args)[source]
Activates the TCP function (Tool Center Point) and defines the transformation between the tool_link frame and the TCP frame.
- reset_tcp()[source]
Reset the TCP (Tool Center Point) transformation. The TCP will be reset according to the tool equipped.
- Return type
Hardware¶
- class NiryoRobot(ip_address=None)[source]
- 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
- digital_write(pin_id, digital_state)[source]
Set pin_id state to digital_state
- Parameters
pin_id (PinID) –
digital_state (PinState) –
- Return type
- digital_read(pin_id)[source]
Read pin number pin_id and return its state
- Parameters
pin_id (PinID) –
- Return type
PinState
- get_hardware_status()[source]
Get hardware status : Temperature, Hardware version, motors names & types …
- Returns
Infos contains in a HardwareStatusObject
- Return type
HardwareStatusObject
Conveyor¶
- class NiryoRobot(ip_address=None)[source]
- set_conveyor()[source]
Activate a new conveyor and return its ID
:return : New conveyor ID :rtype: ConveyorID
- unset_conveyor(conveyor_id)[source]
Remove specific conveyor.
- Parameters
conveyor_id (ConveyorID) – Basically, ConveyorID.ONE or ConveyorID.TWO
- run_conveyor(conveyor_id, speed=50, direction=<ConveyorDirection.FORWARD: 1>)[source]
Run conveyor at id ‘conveyor_id’
- stop_conveyor(conveyor_id)[source]
Stop conveyor at id ‘conveyor_id’
- Parameters
conveyor_id (ConveyorID) –
- Return type
- control_conveyor(conveyor_id, control_on, speed, direction)[source]
Control conveyor at id ‘conveyor_id’
Vision¶
- class NiryoRobot(ip_address=None)[source]
- get_img_compressed()[source]
Get image from video stream in a compressed format. Use
uncompress_imagefrom the vision package to uncompress it- Returns
string containing a JPEG compressed image
- Return type
- set_brightness(brightness_factor)[source]
Modify video stream brightness
- set_contrast(contrast_factor)[source]
Modify video stream contrast
- set_saturation(saturation_factor)[source]
Modify video stream saturation
- 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.
- 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
PoseObject
- 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)
- 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)
- 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)
- detect_object(workspace_name, shape=<ObjectShape.ANY: 'ANY'>, color=<ObjectColor.ANY: 'ANY'>)[source]
Detect object in workspace and return its pose and characteristics
- get_camera_intrinsics()[source]
Get calibration object: camera intrinsics, distortions coefficients
- 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
- 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.
- delete_workspace(workspace_name)[source]
Delete workspace from robot’s memory
- get_workspace_ratio(workspace_name)[source]
Get workspace ratio from robot’s memory
Enums¶
Enums are used to pass specific parameters to functions.
For instance, change_tool()
will need a parameter from
ToolID enum
robot.change_tool(ToolID.GRIPPER_1)
List of enums:
CalibrateModeRobotAxisToolIDPinModePinStatePinIDConveyorIDConveyorDirectionObjectColorObjectShape
- 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
- 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
- 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