Note: Extension parts are not included in the package of CyberPi. To use the functions of extension parts, you need to purchase the corresponding kits or packs.

Pocket Shield


Pocket shield can supply power for CyberPi and enables CyberPi to connect to motors, servos, and LED strips. In addition, Pocket Shield provides digital and analog interfaces for driving Arduino modules.


The cyberpi.pocket module provides APIs for Pocket Shield.


Interfaces


Pocket Shield provides two DC motor interfaces and two digital servo interfaces, where the digital servo interfaces can be used to connect LED strips and Arduino sensors.

image.png

Driving motors

cyberpi.pocket.motor_add(power, port)

Changes the output power of the motor connected to the specified port

Parameters:

Setting range:

all

m1

m2

M1

M2

1

2


cyberpi.pocket.motor_set(power, port)

Sets the output power of the motor connected to the specified port

Parameters:

When power > 0, the output shaft of the motor rotates counterclockwise; and when power < 0, the output shaft rotates clockwise. This may not be true for all the motors due to the features of motors. Some motors may require large start current and therefore can't work when power is low.

Setting range:

all

m1

m2

M1

M2

1

2


cyberpi.pocket.motor_get(port)

Obtains the output power of the motor connected to the specified port

Parameter:

Setting range:

all

m1

m2

M1

M2

1

2

A float value ranging from -100 to 100 is returned, in percentage.


cyberpi.pocket.motor_drive(power1, power2)

Sets the power output of the motors connected to ports M1 and M2

This API is used to set the power output of the motors connected to M1 and M2 and thus can synchronize the motion of the two motors.

Parameters:


cyberpi.pocket.motor_stop(port)

Sets the power output of the motor connected to the specified port to zero

Parameter:

Setting range:

all

m1

m2

M1

M2

1

2


Driving servos

cyberpi.pocket.servo_add(angle, port)

Changes the angle of the servo connected to the specified port

If the API pocket.servo_set(angle, port) has not been used before, when this API is executed, the servo rotates to the psition of 20 degrees first and then rotates by the degrees set in this API.

Parameters:

setting range: -180–+180, in degrees

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.servo_set(angle, port)

Sets the angle of the servo connected to the specified port

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.servo_get(port)

Obtains the angle set for the servo connected to the specified port

The servo can't detect the angle itself, and therefore, if the API pocket.servo_release(port) is executed or the servo is rotated manually, the angle obtained may not be the accurate one.

Parameter:

Setting range:

s1

s2

S1

S2

1

2

An int value ranging from 0 to 180 is returned, in degrees.


cyberpi.pocket.servo_release(port)

Releases the angle of the servo connected to the specified port

When this API is executed, the output shaft of the servo is no longer locked until the API pocket.servo_add(angle, port) or pocket.servo_set(angle, port) is executed.

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.servo_drive(angle1, angle2)

Sets the angles of the servos connected to ports S1 and S2

This API is used to set the angles of the servos connected to S1 and S2 and thus can synchronize the motion of the two servos.

Parameters:


Driving LED strips

cyberpi.pocket.led_on(r,g,b, id, port)

Lights up the LEDs on the LED strip or ring connected to the specified port in the specified color(s)

Parameters:

r: int , intensity of the red color; setting range: 0 - 255

r: str, full name or abbreviation of a color; the following describes colors and their abbreviations:


red r
orange o
yellow y
green g
cyan c
blue b
purple p
white w
black k


id: str, only the value all is valid

id: int, setting range: 1-36, indicating the position of the LED to be lit up

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_show(color, port)

Sets the color(s) of all LEDs on the LED strip or ring connected to the specified port

red, r

green, g

blue, b

yellow, y

cyan, c

purple, p

white, w

orange, o

black, k

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_move(step, cycle, port)

Makes the colors of the LEDs on the LED strip connected to the specified port roll from left to right by the specified number of positions

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_off(id = "all", port)

Turns off the specified LED(s) on the LED strip or ring connected to the specified port

Parameters:

id: int, setting range: 1-36, indicating the position of the LED to be turned off

id: str, only the value all is valid

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_add_bri(brightness, port)

Changes the brightness of the LED strip or ring connected to the specified port of Pocket Shield

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_set_bri(brightness, port)

Sets the brightness of the LED strip or ring connected to the specified port of Pocket Shield

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.led_get_bri(port)

Obtains the brightness of the LED strip or ring connected to the specified port of Pocket Shield

Parameter:

Setting range:

all

s1

s2

S1

S2

1

2


Pin extension

cyberpi.pocket.write_digital(val, port)

Sets the digital input for the specified pin(s)

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.read_digital(port)

Obtains the digital input at the specified pin

Parameter:

Setting range:

s1

s2

S1

S2

1

2

An int value ranging from 0 to 1 is returned, where 0 indicates a low electrical level and 1 indicates a high electrical level.


cyberpi.pocket.set_pwm(duty, frequency, port)

Sets the specified pin(s) to output PWM signals with the specified frequency and duty cycle

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


cyberpi.pocket.read_analog(port)

Obtains the voltage at the specified pin

Parameter:

Setting range:

s1

s2

S1

S2

1

2

A float value ranging from 0 to 5 is returned, in volts.

mBot2 Shield

enAsset 4@2x-8.png

Motion

APIs described in this section are provided for mBot2 to implement common motion control. Ensure that you have built mBot2 when you use these APIs. You can control the motion of mBot2 by using these APIs only when it is built with the 180 encoder motors, wheels, and tires delivered with it.


mbot2.forward(speed = 50, t)

Moves mBot2 forward at the specified speed

Parameters:

If you set speed to a negative value, mBot2 moves backward.

The default value is "null".

When t is float, it indicates the duration mBot2 keeps moving forward, ranging from 0 to ﹢∞, in seconds.

When t is "null", it indicates that mBot2 keeps moving forward at the specified speed until it receives a command instructing it to stop moving forward.


mbot2.backward(speed = 50, t)

Moves mBot2 backward at the specified speed

Parameters:

If you set speed to a negative value, mBot2 moves forward.

The default value is "null".

When t is float, it indicates the duration mBot2 keeps moving backward, ranging from 0 to ﹢∞, in seconds.

When t is "null", it indicates that mBot2 keeps moving backward at the specified speed until it receives a command instructing it to stop moving backward.


mbot2.turn_left(speed = 50, t)

Turns mBot2 left at the specified speed

Parameters:

If you set speed to a negative value, mBot2 turns right.

The default value is "null".

When t is float, it indicates the duration mBot2 keeps turning left, ranging from 0 to ﹢∞, in seconds.

When t is "null", it indicates that mBot2 keeps turning left at the specified speed until it receives a command instructing it to stop turning left.


mbot2.turn_right(speed = 50, t)

Turns mBot2 right at the specified speed

Parameters:

If you set speed to a negative value, mBot2 turns left.

The default value is "null".

When t is float, it indicates the duration mBot2 keeps turning right, ranging from 0 to ﹢∞, in seconds.

When t is "null", it indicates that mBot2 keeps turning right at the specified speed until it receives a command instructing it to stop turning right.


mbot2.straight(distance, speed = 50)

Moves mBot2 forward the specified distance

To ensure the accuracy of the distance mBot2 moves, it moves at the preset speed when this API is executed. When this API is executed, mBot2 keeps moving forward until it moves the specified distance or another API is executed. For example, when mbot2.stop() is executed, mBot2 stops moving.

Parameters:

If you set distance to a negative value, mBot2 moves backward.

The default value is 50. If you set speed to a negative value, the speed is the absolute value of the value you set.


mbot2.turn(angle, speed = 50)

Turns mBot2 clockwise the specified angle

To ensure the accuracy of the angle mBot2 turns, it moves at the preset speed when this API is executed. When this API is executed, mBot2 keeps turning clockwise until it turns the specified angle or another API is executed. For example, when mbot2.stop() is executed, mBot2 stops turning.

Parameters:

If you set angle to a negative value, mBot2 turns counterclockwise.

The default value is 50. If you set speed to a negative value, mBot turns counterclockwise.


mbot2.drive_power(EM1_power, EM2_power)

Sets the power of the two encoder motors, EM1 (connected to the left wheel of mBot2 by default) and EM2 (connected to the right wheel by default)

This API is used to ensure the synchronization of the two encoder motors.

Parameters:

If you set this parameter to a positive value, the output shaft of EM1 rotates counterclockwise.

If you set this parameter to a positive value, the output shaft of EM2 rotates counterclockwise.


mbot2.drive_speed(EM1_speed, EM2_speed)

Sets the rotating speed of the two encoder motors, EM1 (connected to the left wheel of mBot2 by default) and EM2 (connected to the right wheel by default)

This API is used to ensure the synchronization of the two encoder motors.

Parameters:

If you set this parameter to a positive value, the output shaft of EM1 rotates counterclockwise.

If you set this parameter to a positive value, the output shaft of EM2 rotates counterclockwise.


mbot2.EM_stop(port = "all")

Stops the rotating of the encoder motor connected to the specified port

Parameter:

port: float or str, port to which the encoder motor is connected

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


Driving encoder motors

mBot2 is equipped with two encoder motors, which provide strong and accurate power output for mBot2. Note that the rotating speed of the encoder motors may be lower than the one you set if their load is too heavy.


mbot2.EM_set_power(power, port)

Sets the power of the encoder motor connected to the specified port

Parameters:

If you set this parameter to a positive value, the output shaft of EM1 rotates counterclockwise.

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


mbot2.EM_set_speed(speed, port)

Sets the rotating speed of the encoder motor connected to the specified port

Parameters:

If you set this parameter to a positive value, the output shaft of EM1 rotates counterclockwise.

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


mbot2.EM_turn(angle, speed, port)

Sets the angle the encoder motor connected to the specified port turns counterclockwise

When this API is executed, the thread is block until the encoder motor turns the specified angle or the stop() command is received.

Parameters:

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


mbot2.EM_get_angle(port)

Obtains, in real time, the angle the encoder motor connected to the specified port turns counterclockwise

mBot2 resets the angles of the encoder motors when it starts. The number of degrees increases when an encoder motor turns counterclockwise and decreases when the encoder motor turns clockwise.

Parameter:

You can set this parameter to one of the following values:

"em1"

"em2"

"EM1"

"EM2"

1

2

An int value ranging from -∞ to +∞ is returned, in degrees.


mbot2.EM_get_speed(port)

Obtains, in real time, the rotating speed of the encoder motor connected to the specified port when it turns counterclockwise

The rotating speed of the encoder motor may be lower than the set speed when the load is too heavy or may be higher than the set speed due to the action of external force.

Parameter:

You can set this parameter to one of the following values:

"em1"

"em2"

"EM1"

"EM2"

1

2

An int value ranging from -∞ to +∞ is returned, in degrees.


mbot2.EM_get_power(port)

Obtains, in real time, the power of the encoder motor connected to the specified port

Parameter:

You can set this parameter to one of the following values:

"em1"

"em2"

"EM1"

"EM2"

1

2

An int value ranging from -100 to +100 is returned, in percentage.


mbot2.EM_reset_angle(port)

Resets the angle of the encoder motor(s) connected to the specified port(s)

Parameter:

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


mbot2.EM_lock(is_lock = False, port)

Enables the self-locking function of the encoder motor connected to the specified port

When the self-locking function is enabled, the encoder motor attempts to go back to the original position after its motion. This function is disabled by default.

Parameters:

The default value is "False" .

The default value is "all". You can set this parameter to one of the following values:

"all"

"em1"

"em2"

"ALL"

"EM1"

"EM2"

1

2


Driving DC motors

mbot2.motor_add(power, port)

Increases the power output of the motor connected to the specified port

Parameters:

You can set this parameter to one of the following values:

"all"

"m1"

"m2"

"M1"

"M2"

1

2


mbot2.motor_set(power, port)

Sets the rotating speed of the motor connected to the specified port

Parameters:

Parameters:

When power > 0, the output shaft of the motor rotates counterclockwise; and when power < 0, the output shaft rotates clockwise. This may not be true for all the motors due to the features of motors. Some motors may require large start current and therefore can't work when power is low.

Setting range:

all

m1

m2

M1

M2

1

2


mbot2.motor_get(port)

Obtains the power of the motor connected to the specified port

Parameter:

Setting range:

m1

m2

M1

M2

1

2


A float value ranging from -100 to 100 is returned, in percentage.


mbot2.motor_drive(power1, power2)

Sets the power output of the motors connected to ports M1 and M2

This API is used to set the power output of the motors connected to M1 and M2 and thus can synchronize the motion of the two motors.

Parameters:


mbot2.motor_stop(port)

Sets the power output of the motor connected to the specified port to zero

Parameter:

Setting range:

all

m1

m2

M1

M2

1

2


Driving servos


mbot2.servo_add(angle, port)

Changes the angle of the servo connected to the specified port

If the API mbot2.servo_set(angle, port) has not been used before, when this API is executed, the servo rotates to the psition of 20 degrees first and then rotates by the degrees set in this API.

Parameters:

setting range: -180–+180, in degrees

Setting range:

all

s1

s2

s3

s4

S1

S2

S3

S4

1

2

3

4


mbot2.servo_set(angle, port)

Sets the angle of the servo connected to the specified port

Parameters:

Setting range:

all

s1

s2

s3

s4

S1

S2

S3

S4

1

2

3

4


mbot2.servo_get(port)

Obtains the angle set for the servo connected to the specified port

The servo can't detect the angle itself, and therefore, if the API mbot2.servo_release(port) is executed or the servo is rotated manually, the angle obtained may not be the accurate one.

Parameter:

Setting range:

s1

s2

s3

s4

S1

S2

S3

S4

1

2

3

4

An int value ranging from 0 to 180 is returned, in degrees.


mbot2.servo_release(port)

Releases the angle of the servo connected to the specified port

When this API is executed, the output shaft of the servo is no longer locked until the API mbot2.servo_add(angle, port) or mbot2.servo_set(angle, port) is executed.

Setting range:

all

s1

s2

s3

s4

S1

S2

S3

S4

1

2

3

4


mbot2.servo_drive(angle1, angle2, angle3, angle4)

Sets the angles of the servos connected to ports S1, S2, S3, and S4

This API is used to set the angles of the servos connected to S1, S2, S3, and S4, and thus can synchronize the motion of the servos.

Parameters:


Driving LED strips

mbot2.led_on(r,g,b, id = "all", port)

Lights up the LEDs on the LED strip or ring connected to the specified port in the specified color(s)

Parameters:

r: int , intensity of the red color; setting range: 0 - 255

r: str, full name or abbreviation of a color; the following describes colors and their abbreviations:

red r
orange o
yellow y
green g
cyan c
blue b
purple p
white w
black k


id: str, only the value all is valid

id: int, setting range: 1-36, indicating the position of the LED to be lit up

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.led_show(color, port)

Sets the color(s) of all LEDs on the LED strip or ring connected to the specified port

red, r

green, g

blue, b

yellow, y

cyan, c

purple, p

white, w

orange, o

black, k

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.led_move(step, cycle, port)

Makes the colors of the LEDs on the LED strip connected to the specified port roll from left to right by the specified number of positions

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


For example:

Set the initial colors of the LEDs on an LED strip (12 RGB LEDs) to "r o y y y y y y y y y g", as shown in the following figure.

image.png

Then, set step to 2 and cycle to 4.

The LED strip is lit up as follows.

灯带动画效果.gif

mbot2.led_off(id = "all", port)

Turns off the specified LED(s) on the LED strip or ring connected to the specified port

Parameters:

id: int, setting range: 1-36, indicating the position of the LED to be turned off

id: str, only the value all is valid

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.led_add_bri(brightness, port)

Changes the brightness of the LED strip or ring connected to the specified port

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.led_set_bri(brightness, port)

Sets the brightness of the LED strip or ring connected to the specified port

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.led_get_bri(port)

Obtains the brightness of the LED strip or ring connected to the specified port

Parameter:

Setting range:

s1

s2

S1

S2

1

2


Pin extension


mbot2.write_digital(val, port )

Sets the digital input for the specified pin(s)

Parameters:

False/0: low-level input

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.read_digital(port)

Obtains the digital input at the specified pin

Parameter:

Setting range:

s1

s2

S1

S2

1

2

An int value ranging from 0 to 1 is returned, where 0 indicates a low electrical level and 1 indicates a high electrical level.


mbot2.set_pwm(duty, frequency, port)

Sets the specified pin(s) to output PWM signals with the specified frequency and duty cycle

Parameters:

Setting range:

all

s1

s2

S1

S2

1

2


mbot2.read_analog(port)

Obtains the voltage at the specified pin

Parameter:

Setting range:

s1

s2

S1

S2

1

2

A float value ranging from 0 to 5 is returned, in volts.