:::info 注意：你需要额外购买包含扩展板的扩展包或套装来获得相应的扩展板以使用这些功能。 :::

为了让您更好的阅读此API文档，我们对API的可使用场景（Python３与MicroPython）进行了标识。Python3 对应的是童芯派在线模式的编程，MicroPython对应的是上传模式的编程。
支持Python 3 的标识：
支持MicroPython 的标识：
注意：在Python3在线模式下调用mBot2相关的API，需要新增cyberpi前缀才能够进行使用。比如：cyberpi.mbot2.forward()

掌上扩展板

掌上扩展板是为童芯派供电，并使其能够驱动电机、舵机、灯带，标准扩展板还提供了必要的数字、模拟接口用以驱动 Arduino 硬件。 cyberpi.pocket 模块中包含了掌上扩展板的相关 API。

端口示意

掌上扩展板有 2 个直流电机接口和 2 个数字舵机接口，且数字舵机接口支持连接灯带和 Arduino 传感器。

电机驱动

**cyberpi.pocket.motor_add(power, port)**
增加对应端口的电机动力输出。参数：

power float，有效范围 -200~200%，表示电机增加的动力大小。
port int 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

**cyberpi.pocket.motor_set(power, port)**
设置对应端口电机转动的速度。参数：

power float，有效范围 -100~100%，表示电机设置的动力大小。其中，当 power > 0 时，电机输出轴逆时针转动，反之顺时针转动，但根据连接的电机的特性不同该情况，可能存在差异。另外，一些电机的启动电流较大，在 power 值较低的情况下可能无法转动。
port int 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

**cyberpi.pocket.motor_get(port)**
获得对应端口输出的动力大小。参数：

port int 或 str，有效值为 "m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。返回 float，可能的值为 -100~100%。

**cyberpi.pocket.motor_drive(power1, power2)**
同时设置 M1 端口与 M2 端口上的电机动力输出，该指令主要是为了使得两个电机动作同步。参数：

power1 float，有效范围 "-100~100"%，表示 M1 端口的电机动力输出。
power2 float，有效范围 "-100~100"%，表示 M2 端口的电机动力输出。

**cyberpi.pocket.motor_stop(port)**
将对应端口输出的动力大小变为0。参数：

port float 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

示例程序

import cyberpi
import time
cyberpi.pocket.motor_stop('m1')
while True:
    if cyberpi.controller.is_press("a"):
        cyberpi.pocket.motor_set(100,'m1')
        time.sleep(0.3)
    if cyberpi.controller.is_press('b'):
        cyberpi.pocket.motor_stop('m1')
        time.sleep(0.3)

舵机驱动

**cyberpi.pocket.servo_add(angle, port)**
增加指定端口设置的舵机度数，若之前未执行过 pocket.servo_set(angle, port)，则执行该 API 时，舵机会转动到 20°。参数：

angle int，有效范围 "-180~180"°，表示舵机增加的度数。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.servo_set(angle, port)**
设置指定端口的舵机度数。参数：

angle int，有效范围 "0~180"°，表示舵机设置的度数。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.servo_get(port)**
获得指定端口的舵机设置度数。由于数字舵机本身不带度数检测，故若舵机执行了 pocket.servo_release(port)，或被强行扭动，该读值将失去其准度。参数：

port int 或 str，有效值为 "s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

返回 int，可能的值为 0~180°。

**cyberpi.pocket.servo_release(port)**
释放指定端口的舵机度数，此时舵机的输出轴将不再被锁死，直到执行了 pocket.servo_add(angle, port) 或 pocket.servo_set(angle, port)。

port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.servo_drive(angle1, angle2)**
同时设置 S1 端口与 S2 端口上的舵机角度，该指令主要是为了使得两个舵机动作同步。参数：

angle1 int，有效范围 "0~180"°，表示 S1 端口的舵机设置角度。
angle2 int，有效范围 "0~180"°，表示 S2 端口的舵机设置角度。

灯带驱动

**cyberpi.pocket.led_on(r,g,b, id, port)**
点亮指定端口上连接的 LED灯带/灯环。参数：

r int 或 str。 r 为 int 时，有效范围是 0~255，表示 LED 灯的红色色值。 r 为 str 时，表示颜色名称或缩写。颜色名称及其缩写对照表：
```
红 red r
橙 orange o
黄 yellow y
绿 green g
青 cyan c
蓝 blue b
紫 purple p
白 white w
黑 black k
```
g int，有效范围是 0~255，表示 LED 灯的绿色色值。
b int，有效范围是 0~255，表示 LED 灯的蓝色色值。
id int 或 strid 为 str 时，有效值为"all"，此时设置所有灯珠的颜色。 id 为 int 时，有效范围为1-36，此时设置对应位置的灯珠的颜色。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.led_show(color, port)**
设置对应端口整条灯带上每一颗灯的颜色，参数：

color str，其格式需满足其格式需满足 “color1 color2 color3 color4 color5 color6 color7 color8 color9 color10 ... color36” ，其中colorx为 red/green/blue/yellow/cyan/purple/white/orange/black 或是其缩写 r/g/b/y/c/p/w/o/k。颜色字符间以单个空格隔开。当颜色个数大于 36 时将被截断成 36 个。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.led_move(step, cycle, port)**
将灯带从左向右滚动对应格数。参数：

step int，有效范围 -36~36，表示灯带向右移动的格数。
cycle int，有效范围 1~36，表示灯带循环滚动的范围。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

例如，将灯带（12 RGB 灯）的初始颜色设置为“r o y y y y y y y y y g”，如下所示：

则将 step 设置为 2， cycle 设置为 4 之后，灯带显示效果如下：

**cyberpi.pocket.led_off(id = "all", port)**
熄灭指定位置的灯珠。参数：

id int 或 str，默认值 "all"
id 为 int 时，有效范围 1~36，对应熄灭指定位置的灯珠。
id 为 str 时，有效范围 "all"，表示熄灭所有的灯珠。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.led_add_bri(brightness, port)**
增加掌上扩展板指定端口上 LED 灯带/灯环的显示亮度。参数：

brightness int，有效范围 -100~100%，表示掌上扩展板指定端口上 LED 灯带/灯环亮度增加的百分比。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.led_set_bri(brightness, port)**
设置掌上扩展板指定端口上 LED 灯带/灯环的显示亮度。参数：

brightness int，有效范围 0~100%，表示掌上扩展板指定端口上 LED 灯带/灯环设置亮度的百分比。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.led_get_bri(port)**
获取掌上扩展板指定端口上 LED 灯带/灯环的显示亮度。参数：

port int 或 str，有效值为 "s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

引脚扩展

**cyberpi.pocket.write_digital(val, port )**
在指定引脚写入数字量。参数：

port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.read_digital(port)**
获得指定引脚的数字信号。参数：

port int 或 str，有效值为 "s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

返回 int，可能的范围为 0：表示低电平；1：表示高电平。

**cyberpi.pocket.set_pwm(duty, frequency, port)**
在指定引脚设置输出特定频率和占空比的 PWM 信号。参数：

duty int，有效范围为 0~100%，表示占空比。
frequency int，有效范围为1~2000Hz。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

**cyberpi.pocket.read_analog(port)**
获得指定引脚的电压值。参数：

port int 或 str，有效值为 "s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。

返回 float，可能的值为 0~5V。

mBot2 扩展板

注意：在Python3在线模式下调用mBot2相关的API，需要新增cyberpi前缀才能够进行使用。比如：cyberpi.mbot2.forward()

运动

mBot2 封装了一些 API 用于实现一些常用的运动控制，使用下述 API 时，需要保证 mBot2 处于基础的搭建形态，即使用180编码电机作为左右动力轮，并配套使用默认的轮毂及轮胎。否则，将无法实现下述 API 的效果。

**mbot2.forward(speed = 50, t)**
mBot2 以指定速度向前移动。参数：

speed float，有效范围 -200~200 RPM，表示 mBot2 前进时编码电机的转速大小。负数时，mBot2 会向反方向运动。
t float 或 str，默认值为 "null" ，t 为 float 时，有效范围 0~﹢∞ 秒，表示 mBot2 持续前进的时间；当 t = "null" 时，表示 mBot2 持续以设定转速前进，直至收到停止指令。

**mbot2.backward(speed = 50, t)**
mBot2 以指定速度向后移动。参数：

speed float，有效范围 -200~200 RPM，表示 mBot2 后退时编码电机的转速大小。负数时，mBot2 会向反方向运动。
t float 或 str，默认值为 "null" ，t 为 float 时，有效范围 0~﹢∞ 秒，表示 mBot2 持续后退的时间；当 t = "null" 时，表示 mBot2 持续以设定转速后退，直至收到停止指令。

**mbot2.turn_left(speed = 50, t)**
mBot2 以指定速度向左转动。参数：

speed float，有效范围 -200~200 RPM，表示 mBot2 左转时编码电机的转速大小。负数时，mBot2 会向反方向运动。
t float 或 str，默认值为 "null" ，t 为 float 时，有效范围 0~﹢∞ 秒，表示 mBot2 持续左转的时间；当 t = "null" 时，表示 mBot2 持续以设定转速左转，直至收到停止指令。

**mbot2.turn_right(speed = 50, t)**
mBot2 以指定速度向右转动。参数：

speed float，有效范围 -200~200 RPM，表示 mBot2 右转时编码电机的转速大小。负数时，mBot2 会向反方向运动。
t float 或 str，默认值为 "null" ，t 为 float 时，有效范围 0~﹢∞ 秒，表示 mBot2 持续右转的时间；当 t = "null" 时，表示 mBot2 持续以设定转速右转，直至收到停止指令。

**mbot2.straight(distance, speed = 50)**
mBot2 向前直行指定距离。为保证直行距离精度，mBot2 执行该 API 的转速被设定为固定的值，mBot2 将持续前进直至达到指定距离或收到其他 API ，如 mbot2.stop() 会使该动作被中断。参数：

distance float，表示直行前进的距离，单位 cm。当该值为负数时，mBot2 会后退。
speed float，默认值 50，有效范围 0~200 RPM，表示 mBot2 直行时编码电机的转速大小。speed 为负值时，以速度的绝对值进行移动。

**mbot2.turn(angle, speed = 50)**
mBot2 顺时针转动指定角度。为保证转动效果，mBot2 执行该 API 的转速被设定为固定的值，mBot2 将持续转动直至转动到指定角度或收到其他 API ，如 mbot2.stop() 使该动作被中断。参数：

angle int，表示顺时针转动的角度值，当该值为负数时，mBot2 会逆时针旋转。
speed float，默认值 50，有效范围 0~200 RPM，表示 mBot2 旋转时编码电机的转速大小。

**mbot2.drive_power(EM1_power, EM2_power)**
同时设置 mBot2 编码电机 EM1（默认为左轮）、EM2（默认为右轮）的转动速度。该API主要用于确保左右编码电机的动作同步。参数：

EM1_power float，有效范围 -100~100 %，表示设置 mBot2 编码电机 EM1（默认为左轮）的动力大小。当参数值为正值时，编码电机输出轴以逆时针转动。
EM2_power float，有效范围 -100~100 %，表示设置 mBot2 编码电机 EM2（默认为右轮）的动力大小。当参数值为正值时，编码电机输出轴以逆时针转动。

示例程序

import cyberpi
speed = 50
cyberpi.audio.set_vol(10)
while True:
    if cyberpi.controller.is_press('a'):
        cyberpi.audio.play_until('switch')
        cyberpi.mbot2.drive_power(speed, speed)
    if cyberpi.controller.is_press("b"):
        cyberpi.audio.play_until('switch')
        cyberpi.mbot2.drive_power(0, 0)

**mbot2.drive_speed(EM1_speed, EM2_speed)**
同时设置 mBot2 编码电机 EM1（默认为左轮）、EM2（默认为右轮）的转动速度。该积木块主要用于确保左右编码电机的动作同步。参数：

EM1_speed float，有效范围 -200~200 RPM，表示编码电机接口 EM1 设置的电机转速。当参数值为正值时，编码电机输出轴以逆时针转动。
EM2_speed float，有效范围 -200~200 RPM，表示编码电机接口 EM2 设置的电机转速。当参数值为正值时，编码电机输出轴以逆时针转动。

**mbot2.EM_stop(port = "all")**
停止对应接口的编码电机。参数：
port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

编码电机

mBot2 带有两个编码电机，为机器人提供强大且精准的动力输出。需要注意，当编码电机承受较大负载时，其实际转动速度将可能小于被设定的值。

**mbot2.EM_set_power(power, port)**
设置 mBot2 编码电机接口动力大小。参数：

power float，有效范围 -100~100 %，表示设置 mBot2 编码电机 EM1（默认为左轮）的动力大小。当参数值为正值时，编码电机输出轴以逆时针转动。
port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

**mbot2.EM_set_speed(speed, port)**
设置 mBot2 编码电机接口旋转转速。参数：

speed float，有效范围 -200~200 RPM，表示设置 mBot2 编码电机 EM1（默认为左轮）的转速大小。当参数值为正值时，编码电机输出轴以逆时针转动。
port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

**mbot2.EM_turn(angle, speed, port)**
设置 mBot2 对应编码电机接口逆时针旋转过的角度，该 API 将持续阻塞线程，直至编码电机完成对应角度旋转或收到 stop() 指令，参数：

angle int , 有效范围为任意整数，表示对应编码电机逆时针需要转过的度数。
speed float，有效范围 0~200 RPM，表示设置 mBot2 编码电机逆时针转动的转速大小。
port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

**mbot2.EM_get_angle(port)**
获得编码电机的实时角度，mBot2 在开机时会重置编码电机转过的角度，编码电机逆时针旋转时，转过的度数会增加，反之，转过的度数会减小。参数：

port float 或 str，有效值为 em1"/"em2"/"EM1"/"EM2"/1/2，表示对应的端口。

返回 int，可能的范围为 -∞~+∞°。

**mbot2.EM_get_speed(port)**
获得对应编码电机的实时逆时针转速，该转速可能因为负载过重而低于被设定的转速，或因为外力作用而检测到额外的转速。参数：

port float 或 str，有效值为 em1"/"em2"/"EM1"/"EM2"/1/2，表示对应的端口。

返回 int，可能的范围为 -∞~+∞RPM。

**mbot2.EM_get_power(port)**
获得对应编码电机实时动力。参数：

port float 或 str，有效值为 em1"/"em2"/"EM1"/"EM2"/1/2，表示对应的端口。

返回 int，可能的范围为 -100~100%。

**mbot2.EM_reset_angle(port)**
重置对应编码电机转过的角度。参数：

port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

**mbot2.EM_lock(is_lock = False, port)**
开启编码电机的自锁功能，开启后，编码电机将在运动完成后尽可能保持在原有位置上。（该功能默认关闭）参数：

is_lock **bool** ，默认值为 **False**，表示对应编码电机接口的编码电机是否开启自锁功能。
port float 或 str，默认值为 “all”，有效值为 "all"/em1"/"em2"/"ALL"/"EM1"/"EM2"/1/2，表示对应的端口。

电机驱动

**mbot2.motor_add(power, port)**
增加对应端口的电机动力输出。参数：

power float，有效范围 -200~200%，表示电机增加的动力大小。
port int 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

**mbot2.motor_set(power, port)**
设置对应端口电机转动的速度。参数：

power float，有效范围 -100~100%，表示电机设置的动力大小。其中，当 power > 0 时，电机输出轴逆时针转动，反之顺时针转动，但根据连接的电机的特性不同该情况，可能存在差异。另外，一些电机的启动电流较大，在 power 值较低的情况下可能无法转动。
port int 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

**mbot2.motor_get(port)**
获得对应端口输出的动力大小。参数：

port float 或 str，有效值为 "m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

返回 float，可能的值为 -100~100%。

**mbot2.motor_drive(power1, power2)**
同时设置 M1 端口与 M2 端口上的电机动力输出，该指令主要是为了使得两个电机动作同步。参数：

power1 float，有效范围 "-100~100"%，表示 M1 端口的电机动力输出。
power2 float，有效范围 "-100~100"%，表示 M2 端口的电机动力输出。

**mbot2.motor_stop(port)**
将对应端口输出的动力大小变为0。参数：

port float 或 str，有效值为 "all"/"m1"/"m2"/"M1"/"M2"/1/2，表示对应的端口。

舵机驱动

**mbot2.servo_add(angle, port)**
增加指定端口设置的舵机度数，若之前未执行过 mbot2.servo_set(angle, port)，则执行该 API 时，舵机会转动到 20°。参数：

angle int，有效范围 "-180~180"°，表示舵机增加的度数。
port int 或 str，有效值为 “all”/“s1”/“s2”/“s3”/“s4”/“S1”/“S2”/“S3”/“S4”/1/2/3/4`，表示对应的端口。

**mbot2.servo_set(angle, port)**
设置指定端口的舵机度数。参数：

angle int，有效范围 "0~180"°，表示舵机设置的度数。
port int 或 str，有效值为 “all”/“s1”/“s2”/“s3”/“s4”/“S1”/“S2”/“S3”/“S4”/1/2/3/4`，表示对应的端口。

**mbot2.servo_get(port)**
获得指定端口的舵机设置度数。由于数字舵机本身不带度数检测，故若舵机执行了 mbot2.servo_release(port)，或被强行扭动，该读值将失去其准度。

port int 或 str，有效值为 “s1”/“s2”/“s3”/“s4”/“S1”/“S2”/“S3”/“S4”/1/2/3/4，表示对应的端口。

返回 int，可能的值为 0~180°。

**mbot2.servo_release(port)**
释放指定端口的舵机度数，此时舵机的输出轴将不再被锁死，直到执行了 mbot2.servo_add(angle, port) 或 mbot2.servo_set(angle, port)。

port int 或 str，有效值为 “all”/“s1”/“s2”/“s3”/“s4”/“S1”/“S2”/“S3”/“S4”/1/2/3/4`，表示对应的端口。

**mbot2.servo_drive(angle1, angle2, angle3, angle4)**
同时设置端口 S1、S2、S3、S4 上的舵机角度，该指令主要是为了使得舵机动作同步。参数：

angle1 int，有效范围 "0~180"°，表示 S1 端口的舵机设置角度。
angle2 int，有效范围 "0~180"°，表示 S2 端口的舵机设置角度。
angle3 int，有效范围 "0~180"°，表示 S3 端口的舵机设置角度。
angle4 int，有效范围 "0~180"°，表示 S4 端口的舵机设置角度。

灯带驱动

**mbot2.led_on(r,g,b, id = "all", port)**
点亮指定端口上连接的 LED灯带/灯环。参数：

r int 或 str。
r 为 int 时，有效范围是 0 - 255，表示 LED 灯的红色色值。
r 为 str 时，表示颜色名称或缩写。颜色名称及其缩写对照表：
```
红 red r
橙 orange o
黄 yellow y
绿 green g
青 cyan c
蓝 blue b
紫 purple p
白 white w
黑 black k
```
g int，有效范围是 0~255，表示 LED 灯的绿色色值。
b int，有效范围是 0~255，表示 LED 灯的蓝色色值。
id int 或 str，默认值为"all"。
id 为 str 时，有效值为"all"，此时设置所有灯珠的颜色。
id 为 int 时，有效范围为1-36，此时设置对应位置的灯珠的颜色。
port int 或 str，有效值为 “all”/“s1”/“s2”/“S1”/“S2”/1/2，表示对应的端口。

**mbot2.led_show(color, port)**
设置对应端口整条灯带上每一颗灯的颜色，参数：

color str，其格式需满足“color1 color2 color3 color4 color5 color6 color7 color8 color9 color10 ... color36”，其中colorx为red/green/blue/yellow/cyan/purple/white/orange/black 或是其缩写 r/g/b/y/c/p/w/o/k。颜色字符间以单个空格隔开。当颜色个数大于 36 时将被截断成 36 个。
port int 或 str，有效值为”all”/“s1”/“s2”/“S1”/“S2”/1/2，表示对应的端口。

**mbot2.led_move(step, cycle, port)**
将灯带从左向右滚动对应格数。参数：

step int，有效范围 -36~36，默认值 1，表示灯带向右移动的格数。
cycle int，有效范围 1~36，表示灯带循环滚动的范围。
port int 或 str，有效值为 “all”/“s1”/“s2”/“S1”/“S2”/1/2，表示对应的端口。

例如，将灯带（12 RGB 灯）的初始颜色设置为“r o y y y y y y y y y g”，如下所示：

则将 step 设置为 2， cycle 设置为 4 之后，灯带显示效果如下：

**mbot2.led_off(id = "all", port)**
熄灭指定位置的灯珠。参数：

id int 或 str，默认值 "all"
id 为 int 时，有效范围 1~36，对应熄灭指定位置的灯珠。
id 为 str 时，有效范围 "all"，表示熄灭所有的灯珠。
port int 或 str，有效值为 "all"/"s1"/"s2"/"S1"/"S2"/1/2，表示对应的端口。