The Linkbot Peripherals¶

This section describes how to access all of the Linkbots peripherals, such as its its motors, LED, buzzer, buttons, accelerometer, and I2C expansion port.

Accelerometer¶

A Linkbot’s accelerometer object can be accessed via the “accelerometer” member of the AsyncLinkbot class. For instance,

import linkbot3 as linkbot

# This is my accelerometer event callback. Whenever the Linkbot detects that
# the accelerometer has moved, this callback is executed.
def cb(x, y, z, timestamp):
    print('Accel event: ', x, y, z, timestamp)

l = linkbot.Linkbot('ZRG6')
print('Current accelerometer values: ', l.accelerometer.values())
print('Current X axis value: ', l.accelerometer.x())
print('Current Y axis value: ', l.accelerometer.y())
print('Current Z axis value: ', l.accelerometer.z())
print('Enabling accelerometer events...')
l.accelerometer.set_event_handler(cb)
input('Accelerometer events enabled. Try moving the Linkbot. Press "Enter" to '
      'continue.')
print('Disabling accelerometer events...')
l.accelerometer.set_event_handler()

class linkbot3.peripherals.Accelerometer(linkbot_parent)¶

set_event_handler(callback=None, granularity=0.05)¶

Set the event handler for accelerometer events.

Parameters:	callback – function(x, y, z, timestamp_millis)

values()¶

Get the current accelerometer values.

Returns:	The x, y, and z axis accelererations in units of standard Earth G’s, as well as a timestamp in milliseconds from the robot.
Return type:	(float, float, float, int)

x()¶

Get the current x axis value.

Return type:	float
Returns:	The acceleration along the “X” axis in units of Earth gravitational units (a.k.a. G’s)

y()¶

Get the current y axis value.

Return type:	float
Returns:	The acceleration along the “Y” axis in units of Earth gravitational units (a.k.a. G’s)

z()¶

Get the current y axis value.

Return type:	float
Returns:	The acceleration along the “Z” axis in units of Earth gravitational units (a.k.a. G’s)

Battery¶

Get a Linkbot’s current battery voltage or percentage level.

import linkbot3 as linkbot

l = linkbot.Linkbot('ZRG6')
print('Battery voltage: ', l.battery.voltage())
print('Battery level: ', l.battery.percentage())

class linkbot3.peripherals.Battery(linkbot_parent)¶

percentage()¶

Return an estimated battery percentage.

This function estimates the battery charge level based on the current voltage of the battery. The battery voltage discharge curve is highly non-linear, and this function uses three cubic curve-fit equations to generate a “best guess” of the battery level as a percentage.

See https://docs.google.com/spreadsheets/d/1nZYGi2s-gs6waFfvLNPQ9SBCAgTuzwL0sdIo_FG3BQA/edit?usp=sharing for the formula, charts, and graphs.

Returns:	A value from 0 to 100 representing the charge of the battery.
Return type:	float

voltage()¶

Get the current battery voltage.

Returns:	The battery voltage.
Return type:	float

Buttons¶

A Linkbot’s button functions can be overridden from their default functions. The power button can also be overridden, but the robot will still turn off if the button is held for more than 2 seconds. The power-off button functionality cannot be overridden. For example,

import linkbot3 as linkbot

# This is my button event callback. Whenever the Linkbot detects that
# a button has been pressed or released, this callback is executed.
def cb(*args):
    print('Button event: ', args)

l = linkbot.Linkbot('ZRG6')
l.buttons.set_event_handler(cb)
input('Button events enabled. Try moving pressing some buttons. Press "Enter" to '
      'continue.')
print('Disabling button events...')
l.buttons.set_event_handler()

class linkbot3.peripherals.Button(linkbot_parent)¶

a()¶

Get the current state of the ‘A’ button.

Return type:	int
Returns:	either `linkbot3.peripherals.Button.UP` or `linkbot3.peripherals.Button.DOWN`

b()¶

Get the current state of the ‘B’ button.

Return type:	int
Returns:	either `linkbot3.peripherals.Button.UP` or `linkbot3.peripherals.Button.DOWN`

pwr()¶

Get the current state of the power button.

Return type:	int
Returns:	either `linkbot3.peripherals.Button.UP` or `linkbot3.peripherals.Button.DOWN`

set_event_handler(callback=None, **kwargs)¶

Set a callback function to be executed when there is a button press or release.

Parameters:	callback – func(buttonNo(int), buttonDown(bool), timestamp) -> None

values()¶

Get the current button values

Return type:	Return type is (int, int, int), indicating the button state for the power, A, and B buttons, respectively. The button state is one of either Button.UP or Button.DOWN.

Buzzer¶

The Linkbot’s buzzer can play tones ranging from low buzzes to frequencies higher than most humans can perceive.

import linkbot3 as linkbot
import time

# My Linkbot's ID is 'ZRG6'
l = linkbot.Linkbot('ZRG6')

# Emit a tone at 440 Hz for 1 second
l.buzzer.set_frequency(440)
time.sleep(1)
l.buzzer.set_frequency(0)

class linkbot3.peripherals.Buzzer(linkbot_parent)¶

frequency()¶

Get the current buzzer frequency.

Return type:	float
Returns:	The frequency in Hz.

set_frequency(frequency)¶

Set the buzzer frequency.

Parameters:	frequency (float) – A frequency in Hz. A value of 0 turns the buzzer off.

Multi-Color LED¶

Control a Linkbot’s LED color through this interface.

import linkbot3 as linkbot
import math
import time

# My Linkbot's ID is 'ZRG6'
l = linkbot.Linkbot('ZRG6')

start_time = time.time()
# Run a loop for 10 seconds
while (time.time()-start_time) < 10:
    # Modulate each color channel using a sin wave
    r = 127+128*math.sin(2*time.time())
    g = 127+128*math.sin(2*time.time() + 2*math.pi/3)
    b = 127+128*math.sin(2*time.time() + 4*math.pi/3)
    l.led.set_color(int(r), int(g), int(b))

class linkbot3.peripherals.Led(linkbot_parent)¶

color()¶

Get the current led color.

Returns:	Red, green, blue color intensities. Each intensity is an integer from 0 to 255.
Return type:	(int, int, int)

set_color(r, g, b)¶

Set the led color.

The parameters `r`, `g`, and `b` are integer values from 0 to 255 representing the intensity of the red, green, and blue LED’s, respectively.

set_color_code(code)¶

Set the led color via a HTML style color code string.

The code string must start with a hash character (#) and contain six hexadecimal digits, such as: ‘#FFCE00’.

Motor¶

class peripherals.Motor.Controller¶

ACCEL = 4¶

CONST_VEL = 2¶

PID = 1¶

SMOOTH = 3¶

class peripherals.Motor.State¶

COAST = 0¶

ERROR = 4¶

HOLD = 1¶

MOVING = 2¶

class peripherals.Motor(*args, **kwargs)¶

accel()¶

Get the acceleration setting of a motor

Return type:	float
Returns:	The acceleration setting in units of deg/s/s

angle()¶

Get the current motor angle of a motor

Return type:	float
Returns:	The current angle in degrees.

begin_accel(timeout, v0=0.0, state_on_timeout=0)¶

Cause a motor to begin accelerating indefinitely.

The joint will begin accelerating at the acceleration specified previously by linkbot3.peripherals.Motor.accel(). If a timeout is specified, the motor will transition states after the timeout expires. The state the motor transitions to is specified by the parameter `state_on_timeout`.

If the robot reaches its maximum speed, specified by the function linkbot3.peripherals.Motor.set_omega(), it will stop accelerating and continue at that speed until the timeout, if any, expires.

Parameters:	timeout (float) – Seconds to wait before robot transitions states. v0 (float) – Initial velocity in deg/s state_on_timeout (`linkbot3.peripherals.Motor.State`) – End state after timeout

begin_move(timeout=0, forward=True, state_on_timeout=0)¶

Begin moving motor at constant velocity

The joint will begin moving at a constant velocity previously set by linkbot3.peripherals.Motor.set_omega().

Parameters:	timeout (float) – After `timeout` seconds, the motor will transition states to the state specified by the parameter `state_on_timeout`. forward (bool) – Whether to move the joint in the positive direction (True) or negative direction (False). state_on_timeout (`linkbot3.peripherals.Motor.State`) – State to transition to after the motion times out.

controller()¶

The movement controller.

This property controls the strategy with which the motors are moved. Legal values are:

linkbot3.peripherals.Motor.Controller.PID: Move the motors directly with the internal PID controller. This is typically the fastest way to get a motor from one position to another. The motor may experience some overshoot and underdamped response when moving larger distances.
linkbot3.peripherals.Motor.Controller.CONST_VEL: Move the motor at a constant velocity. This motor controller attemts to accelerate and decelerate a motor infinitely fast to and from a constant velocity to move the motor from one position to the next. The velocity can be controlled by setting the property omega.
linkbot3.peripherals.Motor.Controller.SMOOTH: Move the motor with specified acceleration, maximum velocity, and deceleration. For this type of movement, access maximum velocity with property omega, acceleration with property accel, and deceleration with property decel.

decel()¶

Get the deceleration setting of a motor

Return type:	float
Returns:	The deceleration setting in units of deg/s/s

move(angle, relative=True, wait=True)¶

Move the motor.

Parameters:

angle (float) – The angle to move the motor.
relative (bool) – Determines if the motor should move to an absolute position or perform a relative motion. For instance, if the motor is currently at a position of 45 degrees, performing a relative move of 90 degrees will move the motor to 135 degrees, while doing an absolute move of 90 degrees will move the motor forward by 45 degrees until it reaches the absolute position of 90 degrees.
wait (bool) –
Indicate whether the function should wait for the movement to finish before returning or not. For example, the following two snippets of code yield identical robot behavior:
```
my_linkbot.motors[0].move(90, wait=True)
```
and:
```
my_linkbot.motors[0].move(90, wait=False)
my_linkbot.motors[0].move_wait()
```

move_wait()¶

Wait for the motor to stop moving.

This function blocks until the motor is either in a `COAST` state or `HOLD` state.

omega()¶

Get the rotational velocity setting of a motor

Return type:	float
Returns:	The speed setting of the motor in deg/s

set_accel(value)¶

Set the acceleration of a motor.

See linkbot3.peripherals.Motor.accel()

set_controller(value)¶

Set the motor controller.

See linkbot3.peripherals.Motor.controller()

set_decel(value)¶

Set the motor deceleration.

See linkbot3.peripherals.Motor.decel()

set_event_handler(callback=None, granularity=2.0)¶

Set a callback function to be executed when the motor angle values on the robot change.

Parameters:	callback – func(angle, timestamp) -> None granularity – float . The callback will only be called when a motor moves away from its current position by more than ‘granularity’ degrees.

set_omega(value)¶

Set the motor’s velocity.

See linkbot3.peripherals.Motor.omega()

set_power(power)¶

Set the motor’s power.

Motors¶

class peripherals.Motors(linkbot_parent, motor_class=<class 'linkbot3.peripherals.Motor'>)¶

angles()¶

Get the current joint angles and a timestamp from the robot.

Returns:	(a1, a2, a3, timestamp) where the three angles are in degrees and the timestamp is an integer representing the number of milliseconds the Linkbot has been online when this function was executed.
Return type:	(float, float, float, int)

begin_move(mask=7, timeouts=(0, 0, 0), forward=(True, True, True), states_on_timeout=(0, 0, 0), wait=True)¶

Begin moving motors at constant velocity

The joint will begin moving at a constant velocity previously set by linkbot3.async.peripherals.Motor.set_omega().

Parameters:

timeout ((float, float, float)) – After `timeout` seconds, the motor will transition states to the state specified by the parameter `state_on_timeout`.
forward ((bool, bool, bool)) – Whether to move the joint in the positive direction (True) or negative direction (False).
state_on_timeout ((linkbot3.peripherals.Motor.State,)*3) – State to transition to after the motion times out.

move(angles, *args, *, mask=7, relative=True, timeouts=None, states_on_timeout=None, wait=True)¶

Move a Linkbot’s joints.

Parameters:

angles ([float, float, float]) – A list of angles in degrees
mask –
Which joints to actually move. Valid values are:
- 1: joint 1
- 2: joint 2
- 3: joints 1 and 2
- 4: joint 3
- 5: joints 1 and 3
- 6: joints 2 and 3
- 7: all 3 joints
relative (bool) – This flag controls whether to move a relative distance from the motor’s current position or to an absolute position.
timeouts ([float, float, float]) – Sets timeouts for each motor’s movement, in seconds. If the timeout expires while the motor is in motion, the motor will transition to the motor state specified by the states_on_timeout parameter.
wait – Indicate whether this function should return when the motion starts or when the motion finishes. If this is set to `True`, this function will block until the motion completely finishes. If set to `False`, this function will return immediately after receiving confirmation from the robot that the joint has begun moving.

move_wait(mask=7)¶

Wait for motors to stop moving.

This function returns when the Linkbot’s motors stop moving. The mask argument is similar to the mask argument in linkbot3.peripherals.Motors.move().

reset()¶

Reset the revolution-counter on the Linkbot.

When a Linkbot’s motor turns more than 360 degrees, the motor’s reported angle does not wrap back around to zero. For instance, if a motor is rotated ten times, retrieving the motor angle would yield a value of something like 3600 degrees. Similarly, if a motor is currently at 3600 degrees and it receives an instruction to move to an absolute position of 0 degrees, the motor will “wind down” backwards ten full rotations.

This function resets the internal counter on the Linkbot that stores multiple revolutions on the robot. For instance, if the robot angle is currently 3610, after a `reset()`, the motor will report to be at an angle of 10 degrees.

set_event_handler(callback=None, granularity=2.0)¶

Set an event handler for all motors. The event handler will be invoked when a motor angle value changes by more than the amount specified by “granularity”.

Parameters:	callback – async func(encoder_number, angle, timestamp) -> None granularity – float . The callback will only be called when a motor moves away from its current position by more than ‘granularity’ degrees.

set_powers(powers, mask=7)¶

Set the PWM duty cycle on the Linkbot’s motors

Parameters:	powers – A list of powers ranging in value from -255 to 255 mask – Which joints to actually move. Valid values are: 1: joint 1 2: joint 2 3: joints 1 and 2 4: joint 3 5: joints 1 and 3 6: joints 2 and 3 7: all 3 joints

stop(mask=7)¶

Immediately stop all motors.

Parameters:	mask – See `linkbot3.peripherals.Motors.move()`

Peripheral¶

The parent class for (most) Linkbot peripherals.

class linkbot3.peripherals.Peripheral(async_proxy, loop)¶

The parent class for (most) Linkbot peripherals.

set_event_handler(callback=None, **kwargs)¶

Set an event handler for a peripheral.

The event handler will call the callback function when the peripheral senses any changes to its state. For instance, if the peripheral is the accelerometer, the callback will be invoked whenever the accelerometer values change. If the peripheral is the buttons, the callback will be invoked whenever a button is depressed or released.

The arguments passed to the callback vary from peripheral to peripheral. See the peripheral’s documentation for callback arguments.

The Linkbot Peripherals¶

Accelerometer¶

Battery¶

Buttons¶

Buzzer¶

Multi-Color LED¶

Motor¶

Motors¶

Peripheral¶

Table Of Contents

Previous topic

Next topic

This Page