north_c9.controller¶
C9Controller¶
-
class
north_c9.controller.C9Controller(connection: ftdi_serial.Serial = None, address: Optional[int] = 1, device: ftdi_serial.Device = None, device_serial: str = None, device_number: int = None, home: bool = False, connect: bool = True, write_timeout: float = 0.5, read_timeout: float = 0.5, retry_timeout: float = 0.5, lock_timeout: float = 120, move_wait_delay: float = 0.1, move_wait_scale: float = 0.8, move_prediction: bool = True, retries: int = 10, command_delay: float = 0.0015, debug_protocol: bool = False, paused: bool = False, use_joystick: bool = True, ignore_missing_joystick: bool = True, verbose=False)¶ C9Controller is the main class used to communicate with the North C9
Create an instance of C9Controller.
- Parameters
connection – optional Serial connection to use for communication (a Serial connection will be created if needed)
device – optional Serial Device to use when creating the Serial connection
device_serial – serial number of the FTDI device to connect to, will connect to first device if not given
device_number – index of the FTDI serial device to connect to, device_serial should be used when possible
home – home the robot connected to the C9, defaults to False
connect – send a ping command after creation to check C9 controller connection
write_timeout – timeout to use when writing data to the serial connection, defaults to 0.5s
read_timeout – timeout to use when reading data from the serial connection, defaults to 0.5s
retry_timeout – amount of time to wait between retrying failed commands, defaults to 0.5s
lock_timeout – the amount of idle time needed to trigger a deadlock error
move_wait_delay – an estimate of the delay in sending a command to the C9, used for movement duration prediction
move_wait_scale – a percentage used to scale the estimated movement duration to ensure we undershoot it
move_prediction – enable move prediction, defaults to True. This will sleep while the robot is moving to reduce protocol chatter
retries – the number of times to retry a failed command, defaults to 10
command_delay – the delay between sending a command and releasing the lock for threading
debug_protocol – use the simpler debug protocol without CRCs if True. This is needed when connecting to a C9 using the USB port
paused – pause sending commands if True, will resume when paused is reset to False
use_joystick – create a joystick instance if True, defaults to True
ignore_missing_joystick – ignore errors from missing joysticks
-
AXIS_CAROUSEL= 4¶ Carousel axis number
-
AXIS_COLUMN= 3¶ Column axis number
-
AXIS_ELBOW= 1¶ Elbow axis number
-
AXIS_GRIPPER= 0¶ Gripper axis number
-
AXIS_SHOULDER= 2¶ Shoulder axis number
-
BIAS_CLOSEST= 2¶ Bias arm by keeping new positions as close to the old position as possible, avoids large elbow swings
-
BIAS_MAX_SHOULDER= 1¶ Bias arm position to keep the shoulder away from the center
-
BIAS_MIN_SHOULDER= 0¶ Bias arm position to keep the shoulder near the center
-
address(new_address: int = None) → int¶ Return the address of the connected C9 controller, changing it to a new address if given
- Parameters
new_address – optional new address to use for C9 controller
- Returns
address of connected C9 controller
-
analog(pin: int) → float¶ Get the voltage on an analog input pin
- Parameters
pin – analog pin number
- Returns
voltage
-
analog_inputs(pins: List[int] = [], all: bool = False) → List[float]¶ Get the value of the given analog inputs
- Parameters
pins – analog input pins
all – get value of all analog inputs
- Returns
list of analog input values
-
axes_moving(axes: List[int]) → List[bool]¶ Returns a list of moving statuses for the given axes (True if moving)
- Parameters
axes – list of axis numbers
- Returns
list of axis moving states
-
axis_current(axis: int, max_current: Optional[int] = None, max: bool = False) → int¶ Return the actual or max current for the given axis, setting the max current if given
- Parameters
axis – axis number
max_current – optional new max current value
max – return max current instead of actual if True
- Returns
actual or max current
-
axis_error(axis: int) → str¶ Return the fault error code for the given axis
- Parameters
axis – axis to check for errors
- Returns
axis error code (0000 if no error)
-
axis_errors() → Dict[int, int]¶ Return a list of axis fault errors
- Returns
list of (<axis number>, <fault code>) tuples, empty if no faults
-
axis_moving(axis: int) → bool¶ Returns given axis moving state
- Parameters
axis – axis number
- Returns
axis moving state (True if moving)
-
axis_position(axis: int, units: bool = False, motor: bool = False) → float¶ Return the position of the given axis
- Parameters
axis – axis number
units – use units instead of counts for positions if True
motor – find actual position from motor controller instead of internal C9 value
- Returns
axis position
-
axis_positions(*axes, units: bool = False, motor: bool = False) → List[float]¶ Return a list of current positions for the given axes
- Parameters
axes – axes to find positions for
units – use units instead of counts for positions if True
motor – find actual position from motor controller instead of internal C9 value
- Returns
list of axis positions
-
axis_state(axis: int) → int¶ Return the state of the given axis
- Parameters
axis – axis to check
- Returns
state of axis (-1 if in fault state)
-
axis_velocity(axis: int) → float¶ Return the actual (not the target) velocity of the given axis
- Parameters
axis – axis number
- Returns
axis velocity in counts / s
-
carousel(index: int, wait: bool = True, carousel: int = 0)¶ Move attached carousels to the given index position (0 is the “home” position)
- Parameters
index – carousel index
wait – wait for carousel to stop (defaults to True)
carousel – carousel index (defaults to 0)
-
cartesian_position(retries: Optional[int] = None) → List[float]¶ Return the x, y, z position of the N9
- Returns
list containing x, y and z positions in mm
-
com(port: int, baudrate: int = 9600) → ftdi_serial.Serial¶ Create a new Serial class instance for the given aux COM port
- Parameters
port – COM port to proxy serial data to
baudrate – baudrate to use for COM port proxy
- Returns
Serial instance
-
com_flush(port: int)¶ Flush the input buffer for the given aux COM port
- Parameters
port – COM port to flush
-
com_init(port: int, baudrate: int)¶ Initialize an aux COM port on the C9 with the given baudrate
- Parameters
port – COM port to initialize (matches COM number labelled on C9)
baudrate – baudrate to to use (eg. 9600)
-
com_read(port: int, num_bytes: int = -1, timeout=1000) → bytes¶ Read bytes from the given aux COM port
- Parameters
port – COM port to read from
num_bytes – optional number of bytes to read (defaults to -1, which reads all bytes in input buffer)
- Returns
bytes of data read from COM port
-
com_rx_size(port: int, retries: int = 5) → int¶ Return the number of characters in the given aux COM port input buffer
- Parameters
port – COM port to check
- Returns
number of characters in input buffer
-
com_write(port: int, data: bytes)¶ Write data to the given aux COM port
- Parameters
port – COM port to write to
data – data to write
-
digital(pin: int) → bool¶ Get the state of a digital input
- Parameters
pin – digital input pin
- Returns
digital input state
-
digital_inputs(pins: List[int] = [], all: bool = False) → List[bool]¶ Get the state of the given digital inputs
- Parameters
pins – digital input pins
all – get state of all digital inputs
- Returns
list of digital input states
-
elbow_bias(bias: Optional[int] = None) → int¶ Change the elbow bias of the N9
- Parameters
bias – bias to use, one of: C9Controller.BIAS_MIN_SHOULDER, C9Controller.BIAS_MAX_SHOULDER, C9Controller.BIAS_CLOSEST
- Returns
current elbow bias
-
elbow_length(length: Optional[float] = None) → float¶ Change the length of the last robot link, used for moving the robot probe
- Parameters
length – length offset
- Returns
current length offset
-
halt(*axes)¶ Halts the given axes which immediately turns off the axis motors :param axes: axes to halt, at least one axis required
-
home(*axes, if_needed: bool = True, skip: bool = False, timeout: int = 240, double_home: bool = False)¶ Homes the robot or axes connected to the C9 controller. If no axes are given, the main axes / robot will be homed. :param axes: axes to home, will home all main axes / robot if none given :param if_needed: only home if the connected C9 hasn’t homed since power on :param skip: skip actual homing (WARNING: never use this) :param timeout: home timeout
-
info() → str¶ Returns the firmware name and version of the connected C9 controller
-
move(axis_positions: Dict[int, float], velocity: Optional[int] = None, acceleration: Optional[int] = None, relative: bool = False, units: bool = False, wait: bool = True) → List[float]¶ Move axes to a relative or absolute position
- Parameters
axis_positions – dictionary mapping axis numbers to target positions
velocity – optional velocity during movement in counts / s
acceleration – optional acceleration during movement in counts / s^2
relative – use relative movements if True (defaults to False or absolute movements)
units – positions are in units instead of counts (defaults to False)
wait – wait for axes to stop moving (defaults to True)
- Returns
list of final axis positions after move
-
move_arm(x: Optional[float] = None, y: Optional[float] = None, z: Optional[float] = None, gripper: Optional[float] = None, velocity: Optional[float] = None, acceleration: Optional[float] = None, elbow_bias: Optional[int] = None, relative: bool = False, wait: bool = True) → List[int]¶ Move robot arm to a cartesian position, most positions are optional and the minimum number of axes will be moved
- Parameters
x – optional x position in mm (x and y must be set as a pair)
y – optional y position in mm (x and y must be set as a pair)
z – optional z position in mm
gripper – optional gripper position in degrees
velocity – optional velocity during move in counts / s
acceleration – optional acceleration during move in counts / s^2
relative – perform a relative movement if True (defaults to False)
wait – wait for movement to complete if True (defaults to False)
- Returns
final positions of main axes after move
-
move_axis(axis: int, position: float, velocity: Optional[int] = None, acceleration: Optional[int] = None, relative: bool = False, units: bool = False, wait: bool = True) → float¶ Moves an axis to an absolute or relative position
- Parameters
axis – axis number
position – target position
velocity – optional velocity to use during move
acceleration – optional acceleration to use during move
relative – use relative movement if True (defaults to False)
units – position is in units instead of counts if True (defaults to False)
wait – wait for axis to stop moving if True (defaults to True)
- Returns
final position after move
-
output(output: int, state: Optional[bool] = None) → bool¶ Get or set the state of given output
- Parameters
output – output number
state – optional output state (True is on)
- Returns
output state
-
output_toggle(output: int) → bool¶ Toggle the state of the given output
- Parameters
output – output number
- Returns
output state
-
outputs(pins: List[int] = [], all: bool = False) → List[bool]¶ Get the state for the given output pins
- Parameters
pins – output pin numbers
all – get state of all outputs
- Returns
bool list of output states
-
ping(timeout: float = 1.0, retries: int = 5)¶ Sends a ping to the C9 controller, used to test connection
-
recap(pitch_mm: float, rotations: float = 1.5) → List[float]¶ Perform a recap movement. This will spin the gripper clockwise for the given number of rotations while moving the z axis downwards at a rate matching the thread pitch (the cap displacement after one rotation).
The robot arm should be moved to the position returned from uncap before recapping, with the gripper still gripping the cap.
- Parameters
pitch_mm – thread pitch in mm of the cap (this is the displacement after one rotation)
rotations – the number of rotations needed to uncap, defaults to 1.5
- Returns
position of the arm after recapping
-
speed(velocity: Optional[int] = None, acceleration: Optional[int] = None) → Tuple[int, int]¶ Get or sets the default velocity and acceleration for movements
- Parameters
velocity – optional velocity in counts / s
acceleration – optional acceleration in counts / s^2
-
spin_axis(*axes, velocity: Optional[int] = None, acceleration: Optional[int] = None, stop: bool = False)¶ Start (or stop) spinning axes
- Parameters
axes – axis numbers to spin
velocity – velocity of spin
acceleration – acceleration during spin
stop – stops spin instead of starting if True (defaults to False)
-
spin_axis_stop(*axes)¶ Stop spinning axes
- Parameters
axes – axis numbers to stop
-
swap_elbow()¶ Move the N9 to same effector position but with a different elbow position, changing elbow bias if needed
-
uncap(pitch_mm: float, rotations: float = 1.5) → List[float]¶ Perform an uncap movement. This will spin the gripper counter-clockwise for the given number of rotations while moving the z axis upwards at a rate matching the thread pitch (the cap displacement after one rotation).
The arm should be in a position with the gripper closed on the cap before uncap is called.
The position returned should be saved for recapping.
- Parameters
pitch_mm – thread pitch in mm of the cap (this is the displacement after one rotation)
rotations – the number of rotations needed to uncap, defaults to 1.5
- Returns
position of the arm after uncapping, this is the position needed for recapping
-
use_probe(probe: bool = True, probe_offset: float = 41.5)¶ Use the robot probe when moving
- Parameters
probe – use probe if True (defaults to True)
probe_offset – elbow length offset for probe (defaults to 41.5)
-
wait_for_axes(axes, poll_interval=0.01, verbose: bool = False)¶ Pauses until the given axes have stopped moving
- Parameters
axes – list of axes numbers to wait for
poll_interval – axis moving polling interval (defaults to 0.01 sec)
verbose – controller verbosity while polling axes (defaults to False)
-
wait_for_axis(axis, poll_interval=0.01, verbose: bool = False)¶ Pause until the given axis has stopped moving
- Parameters
axis – axis number
poll_interval – axis moving polling interval (defaults to 0.01 sec)
verbose – controller verbosity while polling axes (defaults to False)
-
wait_for_main_axes()¶ Pause until main axes / robot has stopped moving
-
weigh_scale(tare: bool = False) → float¶ Returns a measurement (in mg) from the attached weigh scale
- Parameters
tare – tare the scale before measuring if True (default is False)
- Returns
weight in mg