The Linkbot Class

This class allows you to control all major peripherals on the Linkbot, such as the built-in buzzer, multi-color, LED, motors, and more.

class linkbot.Linkbot(serialId='LOCL')

Bases: linkbot._linkbot.Linkbot

The Linkbot class.

Create a new Linkbot object by specifying the robot’s Serial ID in the constructor. For instance:

import linkbot
myLinkbot = linkbot.Linkbot('ABCD')

The previous snippet of code creates a new variable called “myLinkbot” which is connected to a physical robot with the serial ID “ABCD”. Once a Linkbot is connected, you may use member functions to control the robot. For instance, to move motors 1 and 3 90 and -90 degrees, respectively:

myLinkbot.move(90, 0, -90)

Note: As of version 2.3.6, all of the method names in the Linkbot class have been modified from the old camelHump style names to PEP8 compliant names. For instance, the function:

myLinkbot.moveJointToNB(1, 90)

is now:

myLinkbot.move_joint_to_nb(1, 90)

The old function names still work for backwards compatibility, but are not included in the documentation.

class ButtonEvent

Bases: object

DOWN = 1

UP = 0

class Linkbot.FormFactor

Bases: object

I = 0

L = 1

T = 2

class Linkbot.JointStates

Bases: object

FAIL = 3

HOLD = 1

MOVING = 2

STOP = 0

lock()

set_moving(mask)

set_state(index, state)

state(index)

states()

unlock()

wait(timeout=None)

Linkbot.accelerometer_event_cb(x, y, z, timestamp)

Linkbot.button_event_cb(*args, **kwargs)

Linkbot.connect(serialId=None)

Connect to the robot. (DEPRECATED)

This function is no longer required to form a connection with a Linkbot. All connection now happens in __init__(). Calling this function does nothing, but it is kept here for backwards-compatability purposes.

Parameters:serialId (str) – (optional): The serial ID may be specified here or in the Linkbot constructor. If specified in both locations, the one specified here will override the one specified in the constructor.

Linkbot.disable_accelerometer_events()

Make the robot stop reporting accelerometer change events.

Linkbot.disable_button_events()

Make the robot stop reporting button change events.

Linkbot.disable_encoder_events()

Make the robot stop reporting encoder change events.

Linkbot.disable_joint_events()

Make the robot stop reporting joint status change events.

Linkbot.drive(j1, j2, j3, mask=7)

Move a robot’s motors using the on-board PID controller.

This is the fastest way to get a Linkbot’s motor to a particular angle position. The “speed” setting of the joint is ignored during this motion.

Parameters:

• j1 (float) – Relative angle in degrees to move the joint. If a joint is currently at a position of 30 degrees and a 90 degree drive is issued, the final position of the joint will be at 120 degrees. Parameters j2 and j3 are similar for joints 2 and 3.
• mask (int) – (optional) A bitmask to specify which joints to move. The robot will only move joints where (mask&(1<<(joint-1))) is true.

Linkbot.drive_joint(joint, angle)

Move a single motor using the on-board PID controller.

This is the fastest way to drive a single joint to a desired position. The “speed” setting of the joint is ignored during the motion. See also: Linkbot.drive()

Parameters:

• joint (int) – The joint to move.
• angle (float) – A relative angle in degrees to move the joint.

Linkbot.drive_joint_nb(joint, angle)

Non-blocking version of Linkbot.drive_joint()

Linkbot.drive_joint_to(joint, angle)

Move a single motor using the on-board PID controller.

This is the fastest way to drive a single joint to a desired position. The “speed” setting of the joint is ignored during the motion. See also: Linkbot.drive()

Parameters:

• joint (int) – The joint to move.
• angle (float) – An absolute angle in degrees to move the joint.

Example:

robot.driveJointTo(1, 20)
# Joint 1 is now at the 20 degree position.
# The next line of code will move joint 1 10 degrees in the negative
# direction.
robot.drive_joint_to(1, 10)

Linkbot.drive_joint_to_nb(joint, angle)

Non-blocking version of Linkbot.drive_joint_to()

Linkbot.drive_nb(j1, j2, j3, mask=7)

Non blocking version of Linkbot.drive().

Linkbot.drive_to(j1, j2, j3, mask=7)

Move a robot’s motors using the on-board PID controller.

This is the fastest way to get a Linkbot’s motor to a particular angle position. The “speed” setting of the joint is ignored during this motion.

Parameters:

• j1 (float) – Absolute angle in degrees to move the joint. If a joint is currently at a position of 30 degrees and a 90 degree drive is issued, the joint will move in the positive direction by 60 degrees. Parameters j2 and j3 are similar for joints 2 and 3.
• mask (int) – (optional) A bitmask to specify which joints to move. The robot will only move joints where (mask&(1<<(joint-1))) is true.

Linkbot.drive_to_nb(j1, j2, j3, mask=7)

Non-blocking version of Linkbot.drive_to()

Linkbot.enable_accelerometer_events(cb=None)

Make the robot begin reporting accelerometer change events. To handle these events, a callback function may be specified by the “cb” parameter, or the member function “accelerometer_event_cb()” may be overridden.

Parameters:cb (function(x, y, z, timestamp)) – (optional) A callback function that will be called when accelerometer events are received. The callback function prototype should be cb(x, y, z, timestamp)

Linkbot.enable_button_events(cb=None)

Make the robot begin button events.

Make the robot begin reporting button events. To handle the events, a callback function may be specified by the “cb” parameter, or the member function “button_event_cb()” may be overridden.

Parameters:cb (function(buttonNo, buttonState, timestamp)) – (optional) A callback function with the prototype cb(ButtonNo, buttonState, timestamp)

Linkbot.enable_encoder_events(granularity=20.0, cb=None)

Make the robot begin reporting encoder events.

Make the robot begin reporting joint encoder events. To handle these events, a callback function may be specified by the “cb” parameter, or the member function “encoder_event_cb()” may be overridden.

Parameters:

• granularity (float) – (optional) The granularity of the reported encoder events, in degrees. For example, setting the granularity to “10.0” means the robot will report an encoder event for every 10 degrees that a joint is rotated.
• cb (function(joint, angle, timestamp)) – (optional) The callback function to handle the event. The function prototype should be cb(joint, angle, timestamp)

Linkbot.enable_joint_events(cb=None)

Linkbot.encoder_event_cb(joint, angle, timestamp)

Linkbot.get_accelerometer()

Get the current accelerometer values for 3 primary axes

Return type:(number, number, number) Returned values are expressed in “G’s”, where one G is equivalent to one earth-gravity, or 9.81 m/s/s.

Linkbot.get_accelerometer_data()

Linkbot.get_battery_voltage()

Get the robot’s current battery voltage

Linkbot.get_form_factor()

Get the robot’s form factor

Return type:linkbot.Linkbot.FormFactor.[I|L|T]

Linkbot.get_hw_version()

Linkbot.get_joint_angle(joint)

Get the current angle for a particular joint

Parameters:joint (int) – The joint number of robot.

Example:

# Get the joint angle for joint 1
angle = robot.get_joint_angle(1)

Linkbot.get_joint_angles()

Get the current joint angles of the robot.

Return type:(number, number, number) Returned values are in degrees. The three values indicate the joint angles for joints 1, 2, and 3 respectively. Values for joints which are not movable (i.e. joint 2 on a Linkbot-I) are always zero.

Example:

j1, j2, j3 = robot.get_joint_angles()

Linkbot.get_joint_safety_angles()

Linkbot.get_joint_safety_thresholds()

Linkbot.get_joint_speed(joint)

Get the current speed for a joint

Parameters:joint (int) – A joint number. Return type:float (degrees/second)

Example:

# Get the joint speed for joint 1
speed = robot.get_joint_speed(1)

Linkbot.get_joint_speeds()

Linkbot.get_joint_states()

Linkbot.get_led_color()

Linkbot.get_serial_id()

Linkbot.get_versions()

Linkbot.joint_event_cb(joint, state, timestamp)

Joint event callback function.

This function is called when the state of joint changes. For instance, if a moving joint stops, this callback function is invoked.

This function is used internally by the move_wait() function and overriding this function is not recommended.

Linkbot.move(j1, j2, j3, mask=7)

Move the joints on a robot and wait until all movements are finished.

Move a robot’s joints at the constant velocity previously set by a call to Linkbot.set_joint_speed() or similar functions.

Parameters:j1 (float) – An angle in degrees. The joint moves this amount from wherever the joints are currently positioned.

Example:

robot.move(90, 0, -90) # Drives Linkbot-I forward by turning wheels
                       # 90 degrees.

Linkbot.move_continuous(dir1, dir2, dir3, mask=7)

This function makes the joints on a robot begin moving continuously, “forever”.

Parameters:dir1 (Linkbot.JointStates) –

These parameters should be members of the Linkbot.JointStates class. They should be one of

• Linkbot.JointStates.STOP : Stop and relax the joint wherever it is.
• Linkbot.JointStates.HOLD : Stop and make the joint stay at its current position.
• Linkbot.JointStates.MOVING : Begin moving the joint at whatever speed the joint was last set to with the setJointSpeeds() function.

Linkbot.move_joint(joint, angle)

Move a single motor using the on-board constant velocity controller.

Move a single joint at the velocity last set by Linkbot.set_joint_speed() or other speed setting functions. See also: Linkbot.move()

Parameters:

• joint (int) – The joint to move.
• angle (float) – A relative angle in degrees to move the joint.

Example:

# The following code moves joint 1 90 degrees, and then moves joint
# 3 90 degrees after joint 1 has stopped moving.
robot.move_joint(1, 90)
robot.move_joint(3, 90)

Linkbot.move_joint_accel(joint, acceleration, angle)

Linkbot.move_joint_accel_nb(joint, acceleration, angle)

Linkbot.move_joint_nb(joint, angle)

Non-blocking version of Linkbot.move_joint()

Linkbot.move_joint_smooth(joint, angle)

Move a single joint using the “Smooth” motor controller.

See Linkbot.move_smooth()

Linkbot.move_joint_smooth_nb(joint, angle)

Non-blocking version of Linkbot.move_joint_smooth()

Linkbot.move_joint_to(joint, angle)

Move a single motor using the on-board constant velocity controller.

Move a single joint at the velocity last set by Linkbot.set_joint_speed() or other speed setting functions. The ‘angle’ parameter is the absolute position you want the motor to move to. See also: Linkbot.move()

Parameters:

• joint (int) – The joint to move.
• angle (float) – A relative angle in degrees to move the joint.

Example:

# The following code moves joint 1 to the 90 degree position, and 
# then moves joint3 to the 90 degree position after joint 1 has 
# stopped moving.
robot.move_joint_to(1, 90)
robot.move_joint_to(3, 90)

Linkbot.move_joint_to_nb(joint, angle)

Non-blocking version of Linkbot.move_joint_to()

Linkbot.move_joint_wait(joint)

Wait for a single joint to stop moving.

This function blocks until the joint specified by the parameter joint stops moving.

Parameters:joint (int) – The joint to wait for.

Linkbot.move_nb(j1, j2, j3, mask=7)

Non-blocking version of Linkbot.move()

Example:

# The following code makes a Linkbot-I change its LED color to red 
# and then blue while it is rolling forward.
robot.move_nb(90, 0, -90)
robot.set_led_color(255, 0, 0)
time.sleep(0.5)
robot.set_led_color(0, 0, 255)

Linkbot.move_smooth(j1, j2, j3, mask=7)

Move joints with smooth acceleration and deceleration.

The acceleration and deceleration can be set with the functions Linkbot.set_joint_accelerations() and Linkbot.set_joint_decelerations(). The maximum velocity the joint will travel at during the motion can be set with the Linkbot.set_joint_speeds() family of functions.

Parameters:j1 (float) – Number of degrees to move joint 1. Similar for j2 and j3.

Example:

# Move joint 1 720 degrees, accelerating at 45 deg/sec, traveling at
# a maximum speed of 90 deg/sec, and decelerating at 120 deg/sec at
# the end of the motion.
robot.set_joint_accelerations(45, 45, 45)
robot.set_joint_speeds(90, 90, 90)
robot.set_joint_decelerations(120, 120, 120)
robot.move_smooth(720, 0, 0)

Linkbot.move_smooth_nb(j1, j2, j3, mask=7)

Non-blocking version of Linkbot.move_smooth()

Linkbot.move_smooth_to(j1, j2, j3, mask=7)

Move joints with smooth acceleration and deceleration.

The acceleration and deceleration can be set with the functions Linkbot.set_joint_accelerations() and Linkbot.set_joint_decelerations().

Parameters:j1 (float) – The position to move joint 1 to (in degrees).

Linkbot.move_smooth_to_nb(j1, j2, j3, mask=7)

Non-blocking version of move_smooth_to()

Linkbot.move_to(j1, j2, j3, mask=7)

Move a Linkbot’s joints to specified degree locations.

Linkbot.move_to_nb(j1, j2, j3, mask=7)

Non-blocking version of Linkbot.move_to()

Linkbot.move_wait(mask=7)

Wait for all masked joints (all joints by default) to stop moving.

Linkbot.record_angles_begin()

Begin recording a Linkbot’s joint angles.

This function tells the Linkbot to begin recording any changes to its joint angles. The recorded data can be retrieved with the function Linkbot.record_angles_end() .

Linkbot.record_angles_end()

Stop recording a Linkbot’s joint angles and return the results.

Return type:((times,), [[j1_angles,], [j2_angles,], [j3_angles,]])

Linkbot.reset()

Linkbot.reset_to_zero()

Linkbot.reset_to_zero_nb()

Linkbot.set_buzzer_frequency(freq)

Set the Linkbot’s buzzer frequency. Setting the frequency to zero turns off the buzzer.

Parameters:freq (int) – The frequency to set the buzzer, in Hertz.

Linkbot.set_joint_acceleration(joint, alpha)

Set a single joint’s acceleration value.

See Linkbot.set_joint_accelerations() and Linkbot.move_smooth() .

Linkbot.set_joint_accelerations(alpha1, alpha2, alpha3, mask=7)

Set the rate at which joints should accelerate during “smoothed” motions, such as “move_smooth”. Units are in deg/sec/sec.

Linkbot.set_joint_deceleration(joint, alpha)

Set a single joint’s deceleration value.

See Linkbot.set_joint_decelerations() and Linkbot.move_smooth() .

Linkbot.set_joint_decelerations(alpha1, alpha2, alpha3, mask=7)

Set the rate at which joints should decelerate during “smoothed” motions, such as “move_smooth”. Units are in deg/sec/sec.

Linkbot.set_joint_safety_angles(t1=10.0, t2=10.0, t3=10.0, mask=7)

Linkbot.set_joint_safety_thresholds(t1=100, t2=100, t3=100, mask=7)

Linkbot.set_joint_speed(joint, speed)

Set the speed for a single joint on the robot.

Parameters:

• JointNo – The joint to set the speed. Should be 1, 2, or 3.
• speed (float) – The new speed of the joint, in degrees/second.

Example:

# Set the joint speed for joint 3 to 100 degrees per second
robot.set_joint_speed(3, 100)

Linkbot.set_joint_speeds(s1, s2, s3, mask=7)

Set the joint speeds for all of the joints on a robot.

Parameters:

• s1 (float) – The speed, in degrees/sec, to set the first joint. Parameters s2 and s3 are similar for joints 2 and 3.
• mask (int) – (optional) A bitmask to specify which joints to modify the speed. The speed on the robot’s joint is only changed if (mask&(1<<(joint-1))).

Linkbot.set_led_color(r, g, b)

Set the LED color on the robot.

Linkbot.set_motor_power(joint, power)

Apply a direct power setting to a motor

Parameters:

• joint (int (1,3)) – The joint to apply the power to
• power (int (-255,255)) – The power to apply to the motor. 0 indicates no power

(full stop), negative number apply power to turn the motor in the negative direction.

Linkbot.set_motor_powers(power1, power2, power3)

Apply a direct power setting to all motors

Parameters:power (int (-255,255)) – The power to apply to the motor. 0 indicates no power

(full stop), negative number apply power to turn the motor in the negative direction.

Linkbot.stop(mask=7)

Immediately stop and relax all joints on the Linkbot.

Linkbot.stop_joint(joint)

Stop a single joint on the robot, immediately making the joint coast.

Linkbot.test_cb()