The CLinkbot Class¶

( since version 3.1.0 )

The linkbot3.CLinkbot class is an alternative to the linkbot3.Linkbot class. The API style is more closely aligned to the API style used by the C-STEM Ch Linkbot binding, popular in some schools which are a part of the C-STEM program <http://c-stem.ucdavis.edu>.

Note that the documentation lists all of the member functions in a PEP8 compliant format, using all lower-case and underscores. However, there is an internal mechanism that allows camel-humped member functions to be used too, which is the style of the original C-STEM API.

For instance, the documentation lists a function called:

linkbot3.drive_to_nb()

For each function name like this, there also exists an undocumented member function:

linkbot3.driveToNB()

which is the original C-STEM naming style of the function.

Blocking versus Non-Blocking Movement Functions¶

The C-STEM API uses the suffix “nb” (or “NB”) to denote a “non-blocking” movement function. The non-blocking movement functions return before the motion in question is finished. For instance, the following two snippets of code are identical:

import linkbot3 as linkbot
l = linkbot.CLinkbot('ABCD') # My robot's ID is "ABCD"
l.move_nb(90, 90, 90) # Begin moving each motor 90 degrees
l.move_wait()         # Wait for the motion to complete
l.set_led_color(255, 0, 0)  # Change the LED color

and:

import linkbot3 as linkbot
l = linkbot.CLinkbot('ABCD') # My robot's ID is "ABCD"
l.move(90, 90, 90) # Move each motor 90 degrees AND wait for motion to finish
l.set_led_color(255, 0, 0) # Change the LED color

CLinkbot API Documentation¶

class linkbot3.CLinkbot(serial_id)¶

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.

drive_angle(angle)¶

Drive the motors of a 2-wheeled Linkbot by “angle” degrees.

(Since v3.1.11)

Parameters:	angle (float) – An angle in degrees.

drive_angle_nb(angle)¶

Drive the motors of a 2-wheeled Linkbot by “angle” degrees.

(Since v3.1.11)

This is the non-blocking version of linkbot3.CLinkbot.drive_angle().

Parameters:	angle (float) – An angle in degrees.

drive_backward(angle)¶

Drive the motors of a 2-wheeled Linkbot backward by “angle” degrees.

(Since v3.1.11)

Parameters:	angle (float) – An angle in degrees.

drive_backward_nb(angle)¶

Drive the motors of a 2-wheeled Linkbot backward by “angle” degrees.

(Since v3.1.11)

This is the non-blocking version of linkbot3.CLinkbot.drive_backward().

Parameters:	angle (float) – An angle in degrees.

drive_distance(distance, radius)¶

Drive the motors of a 2-wheeled Linkbot to move forward by “distance”

(Since v3.1.11)

Parameters:	distance (float) – A distance. The units used here can be any unit of length, as long as the same units are used for the “radius” parameter. radius (float) – The radius of the Linkbot’s wheels. The units of radius can be anything as long as they are the same units as those used for the “distance” parameter.

drive_distance_nb(distance, radius)¶

Drive the motors of a 2-wheeled Linkbot to move forward by “distance”

(Since v3.1.11)

This is the non-blocking version of linkbot3.CLinkbot.drive_distance().

Parameters:	distance (float) – A distance. The units used here can be any unit of length, as long as the same units are used for the “radius” parameter. radius (float) – The radius of the Linkbot’s wheels. The units of radius can be anything as long as they are the same units as those used for the “distance” parameter.

drive_forever_nb()¶

Drive the motors of a 2-wheeled Linkbot forward ad-infinitum

(Since v3.1.11)

This non-blocking function will make a 2-wheeled Linkbot-I begin driving forward. It will remain driving forward until it receives other movement commands.

drive_forward(angle)¶

Drive the motors of a 2-wheeled Linkbot forward by “angle” degrees.

(Since v3.1.11)

Parameters:	angle (float) – An angle in degrees.

drive_forward_nb(angle)¶

Drive the motors of a 2-wheeled Linkbot forward by “angle” degrees.

(Since v3.1.11)

This is the non-blocking version of linkbot3.CLinkbot.drive_forward().

Parameters:	angle (float) – An angle in degrees.

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: CLinkbot.drive()

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

drive_joint_nb(joint, angle)¶: Non-blocking version of Linkbot.drive_joint()

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: CLinkbot.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)

drive_joint_to_nb(joint, angle)¶: Non-blocking version of CLinkbot.drive_joint_to()

drive_nb(j1, j2, j3, mask=7)¶: Non blocking version of CLinkbot.drive().

drive_time(seconds)¶

Drive the motors of a 2-wheeled Linkbot forward for a set amount of time.

(Since v3.1.11)

Parameters:	seconds (float) – The number of seconds to drive the motors.

drive_time_nb(seconds)¶

Drive the motors of a 2-wheeled Linkbot forward for a set amount of time.

(Since v3.1.11)

This is the non-blocking version of linkbot3.CLinkbot.drive_time().

Parameters:	seconds (float) – The number of seconds to drive the motors.

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.

drive_to_nb(j1, j2, j3, mask=7)¶: Non-blocking version of linkbot3.CLinkbot.drive_to()

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.

get_battery_voltage()¶: Get the robot’s current battery voltage

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)

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()

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)

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 CLinkbot.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.

move_continuous(mask=7)¶

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

Begin moving the joint at whatever speed the joint was last set to with the setJointSpeeds() function.

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 CLinkbot.set_joint_speed() or other speed setting functions. See also: CLinkbot.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)

move_joint_nb(joint, angle)¶: Non-blocking version of CLinkbot.move_joint()

move_joint_smooth(joint, angle)¶

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

See CLinkbot.move_smooth()

move_joint_smooth_nb(joint, angle)¶: Non-blocking version of Linkbot.move_joint_smooth()

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 CLinkbot.set_joint_speed() or other speed setting functions. The ‘angle’ parameter is the absolute position you want the motor to move to. See also: CLinkbot.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)

move_joint_to_nb(joint, angle)¶: Non-blocking version of Linkbot.move_joint_to()

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.

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)

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)

move_smooth_nb(j1, j2, j3, mask=7)¶: Non-blocking version of Linkbot.move_smooth()

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).

move_smooth_to_nb(j1, j2, j3, mask=7)¶: Non-blocking version of move_smooth_to()

move_to(j1, j2, j3, mask=7)¶: Move a Linkbot’s joints to specified degree locations.

move_to_nb(j1, j2, j3, mask=7)¶: Non-blocking version of CLinkbot.move_to()

move_wait(mask=7)¶: Wait for all masked joints (all joints by default) to stop moving.

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.

set_joint_acceleration(joint, alpha)¶

Set a single joint’s acceleration value.

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

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.

set_joint_deceleration(joint, alpha)¶

Set a single joint’s deceleration value.

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

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.

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)

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))).

set_led_color(r, g, b)¶

Set the LED color on the robot.

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.

set_motor_powers(power1, power2, power3, mask=7)¶

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.

stop(mask=7)¶: Immediately stop and relax all joints on the Linkbot.

stop_joint(joint)¶: Stop a single joint on the robot, immediately making the joint coast.

The CLinkbot Class¶

Blocking versus Non-Blocking Movement Functions¶

CLinkbot API Documentation¶

Table Of Contents

Previous topic

Next topic

This Page