API documentation

Button	A button (power, bluetooth, left, right) of a hub block including button lights.
ColorSensor	A color sensor connected to a hub block.
DistanceSensor	A distance sensor connected to a hub block.
ForceSensor	A force sensor connected to a hub block.
Hub	Connection related functionality of a hub block (no sensors, buttons, light matrix aso.).
LightMatrix	The light matrix of a hub block.
MotionSensor	Motion sensor integrated into a hub block.
Motor	A motor connected to a hub block.

class Button(hub, which)

A button (power, bluetooth, left, right) of a hub block including button lights.

Initialization

Prepare hub for button usage.

Parameters:

hub (Hub) – Hub object the button belongs to. ‘param str which: Button identifier ('POWER', 'CONNECT', 'LEFT', 'RIGHT’)

set_color(color)

Set the button light’s color.

Parameters:

color (int) – 0 turns off the light. Values 1 to 10 select one of the hub’s predefined colors.

is_down()

Returns number of milliseconds the button is down for.

Return int:

Button down time in milliseconds. If button isn’t down, 0 is returned.

class ColorSensor(hub, port)

A color sensor connected to a hub block.

Initialization

Prepare hub for usage of a color sensor.

Parameters:

• hub (Hub) – Hub object the color sensor is connected to.

• port (str) – Identifier of the hub port the sensor is connected to (one of 'A', 'B', 'C', 'D', 'E', 'F').

get_raw_color()

Read color and intensity without additional scaling.

Return (int, int, int, int):

Tuple (R, G, B, intensity) of ints in 0-1023.

get_color()

Read color and intensity and scale values to 0-255.

Return (int, int, int, int):

Tuple (R, G, B, intensity) of ints in 0-255.

class DistanceSensor(hub, port)

A distance sensor connected to a hub block.

Initialization

Prepare hub for usage of a distance sensor.

Parameters:

• hub (Hub) – Hub object the distance sensor is connected to.

• port (str) – Identifier of the hub port the sensor is connected to (one of 'A', 'B', 'C', 'D', 'E', 'F').

lights_off()

Turn all lights of the sensor off.

get_distance()

Read distance in millimeters.

Return int:

Distance in millimeters. -1 indicates an invalid measurement.

set_pixel(pos, intensity)

Set intensity of a distance sensor’s light.

Each of the four lights is indentified by an int in 0…3:

• 0 is left top,

• 1 is left botton,

• 2 is right top,

• 3 is right bottom.

Parameters:

• pos (int) – Identifier of the light (0…3).

• intensity (int) – Intensity of the light (0…100).

class ForceSensor(hub, port)

A force sensor connected to a hub block.

Initialization

Prepare hub for usage of a force sensor.

Parameters:

• hub (Hub) – Hub object the force sensor is connected to.

• port (str) – Identifier of the hub port the sensor is connected to (one of 'A', 'B', 'C', 'D', 'E', 'F').

get_raw()

Read raw data.

Return int:

Force read from sensor.

class Hub(port)

Connection related functionality of a hub block (no sensors, buttons, light matrix aso.).

Initialization

Connect host to the hub’s Python interpreter.

Parameters:

port (str) – Device name of the hub at the host machine (e.g. /dev/ttyACM0).

disconnect()

Close serial connection to hub.

write(text)

Send one or multiple lines of text to the hub’s Python interpreter (almost) as is.

Parameters:

text (str) – String to send to the hub.

If text does not end with '\n', then '\n' will be appended before sending. In addition, the hub’s interactive Python interpreter uses '\r\n' for line breaks. Thus, '\n' is replaced by '\r\n' before sending.

Note

Due to the interpreter’s autoindentation feature this method is not suitable for sending code blocks with identation. Instead, use cmd to send code blocks.

readline()

Read one line from the hub’s Python interpreter.

Return str:

Text read from hub without trailing line break.

readlines()

Read all available lines from hub.

Hub line breaks ('\r\n') are replaced by '\n'.

Return str:

Text read from hub.

cmd(code)

Send Python code to the hub.

Waits until interpreter asks for next command and returns output shown by the interpreter.

Parameters:

code (str) – Python code to execute on the hub.

Return [str]:

All outputs produced by the code (list of lines).

list_devices()

List IDs of devices connected to the hub.

Each device type has a unique ID. With this method the port a device is connected to can be identified at runtime.

Return dict(str=int):

Dictionary with keys 'A', 'B', 'C', 'D', 'E', 'F' and integer values representing device IDs. 0 indicates that no device is connect to the port.

class LightMatrix(hub)

The light matrix of a hub block.

Initialization

Prepare hub for light matrix usage.

Parameters:

hub (Hub) – Hub object the light matrix belongs to.

clear()

Clear light matrix (turn all pixels off).

show_image(img)

Show an image.

Parameters:

img (str) – Image to show. The string has to contain 5 lines, each with 5 characters. Allowed characters are 0-9 and X corresponding to intensity levels 0%-90% and 100%, respectively.

set_pixel(x, y, b)

Set brightness of pixel.

Parameters:

• x (int) – x-position of pixel.

• y (int) – y-position of pixel.

• b (int) – brightness level (0-100).

class MotionSensor(hub, up='BUTTONS')

Motion sensor integrated into a hub block.

Initialization

Prepare hub for using the motion sensor.

Parameters:

• hub (Hub) – Hub object the motion sensor belongs to.

• up (str) – Side of hub block facing upwards (used for relative angle measurements, see reset for details).

reset(up='BUTTONS')

Tell the motion sensor which side of the hub block faces upwards and that current yaw angle is zero. Yaw, pitch, role angles returned by get_orientation will be relative to these settings.

Parameters:

up (str) – Side of hub block to be considered facing upwards. One of 'BUTTONS', 'BATTERY', 'USB', 'SPEAKER', 'ACE', 'BDF', each referring to one side of the hub block.

get_orientation()

Read yaw, pitch and role angles of hub block in 3d space.

Return (float, float, float):

yaw, pitch and role angles in degrees from -180 to 180.

To make clear how angles are to be interpreted, assume the hub block rests on a table with the side defined as facing upwards (cf. reset) facing upwards. Further assume you are sitting at the table looking at the following side of the hub block:

• speaker side, if buttons side or battery side or ACE side or BDF side faces upwards,

• buttons side, if USB side faces upwards,

• battery side, if speaker side faces upwards.

We introduce the following coordinate system:

• One axis is normal to the hub’s upward facing side and points upwards. This is the yaw axis.

• One axis lies in the table plan and points to the left from your point of view. This is the pitch axis.

• One axis lies in the table plan and points away from you. This is the role axis.

Note that is constitudes a left-handed coordinate system with axis sequence yaw, pitch, role.

Take two instances of the coordinate system. One is fixed to the hub (axis labels y, p, r) and one is fixed to the table (axis labels Y, P, R). Initially both coordinate systems coincide. After rotating the hub in arbitrary directions the relation between both coordinate systems can be described (up to translations) by three angles:

• The yaw angle is the angle between R-axis and projection of the r-axis onto the P-R-plane. Alternatively, we may say that yaw is rotation around the Y-axis. Looking in opposite direction of the Y-axis (that is, looking down onto the table) counterclockwise rotation yields positive angles.

• The pitch angle is the angle between P-R-plan and r-axis. Alternatively, we may say that pitch is rotation around the p-axis. Looking along the p-axis clockwise rotation yields positive angle.

• The role angle is the angle between P-R-plan and p-axis. Alternatively, we may say that role is rotation around the r-axis. Looking along the r-axis clockwise rotation yields positive angle.

get_angular_velocity()

Read angular velocity.

For interpretation of angles take the coordinate system y, p, r defined in get_orientation for buttons side facing upwards. Angular velocities are positive if angles described there increase.

Return (float, float, float):

Angular velocity for rotation around axes r, p, y in degrees per second.

get_acceleration()

Read acceleration.

For interpretation of accelerations take the coordinate system y, p, r defined in get_orientation for buttons side facing upwards. Accelerations are positive in direction of the axes.

Return (float, float, float):

Acceleration in r, p, y direction in G. Note that even if the hub doesn’t move, values aren’t all zero due to gravitation.

class Motor(hub, port, lock=False, speed=50, acc=100, dec=100)

A motor connected to a hub block.

Initialization

Prepare hub for motor usage and set motor settings.

Parameters:

• hub (Hub) – Hub object the force sensor is connected to.

• port (str) – Identifier of the hub port the sensor is connected to (one of 'A', 'B', 'C', 'D', 'E', 'F').

• lock (bool) – Hold position (True) or don’t lock position (False).

• speed (float) – Default speed in percent of maximum speed.

• acc (float) – Default acceleration in percent of maximum acceleration.

• dec (float) – Default deceleration in percent of maximum deceleration.

start(speed=None, acc=None)

Start the motor.

Parameters:

• speed (float) – Speed in percent of maximum speed (sign is direction of rotation). If None, default speed is used.

• acc (float) – Acceleration in percent of maximum acceleration. If None, default acceleration is used.

stop(lock=None)

Stop the motor by turning off power (no controlled deceleration).

Until speed is 0 the locking flag corresponds to braking.

Parameters:

lock (bool) – Lock position after stopping? If None, default behavior is used.

run_degrees(degrees, speed=None, acc=None, dec=None, lock=None, wait=False)

Run motor for number of degrees.

Direction of rotation can be flipped via sign of speed or sign of degrees.

Parameters:

• degrees (float) – Number of degrees to run.

• speed (float) – Speed in percent of maximum speed. If None, default speed is used.

• acc (float) – Acceleration in percent of maximum acceleration. If None, default acceleration is used.

• dec (float) – Deceleration in percent of maximum deceleration. If None, default deceleration is used.

• lock (bool) – Lock position after stopping? If None, default behavior is used.

• wait (book) – Wait until motor has reached stop position or return immediately?

get_position()

Read current position in degrees.

Return int:

Current position in degrees.