欢迎使用童芯派学习 Python 编程，童芯派具备丰富的输入输出能力，能够让你和你的代码互动起来，并直观地展现撰写代码的效果。
童芯派自带蓝牙及 Wi-Fi，你可以使用它们组建本地局域网或连接至因特网。在实际项目进行动手实践，可了解和掌握物联网、人工智能、计算机网络等方面的相关知识和技能。
童芯派还支持30余种扩展电子模块以及数块扩展板，能够支撑智慧农场、智能家居、自动驾驶车、智能机器人、竞赛用机器人等项目的制作。
cyberpi 库能够帮助你实现上述的所有功能。

cyberpi 库的导入

cyberpi 库其实指向运行在童芯派硬件上的 micro-python 库 cyberpi，以及运行在电脑端的 python 库 ，这两个库并不是同一个，但它们拥有相同的名字，完全一致的 API，以及相近的执行效果。这一特性来自于 cyberpi 团队的刻意追求，这使得您在上传模式（运行在童芯派硬件）下撰写的 micro-python 代码，可以同时在在线模式下（运行在电脑）可以被作为 python 代码来执行。我们相信这有利于学习者从 micro-python 较舒适地过渡到 python 学习。

为了让您更好的阅读童芯派的API文档，我们对API的可使用场景（Python３与MicroPython）进行了标识。Python3 对应的是童芯派在线模式的编程，MicroPython对应的是上传模式的编程。
支持Python 3 的标识：
支持MicroPython 的标识：
你可以在 Python 编辑器或 micro-python 编辑器中使用 cyberpi库，按如下方式导入：

## python 全写
import cyberpi
cyberpi.console.print("hello")
## micropython 简写
from cyberpi import *
console.print("hello")

全写的写法更适合在线模式下的 python 代码撰写，这意味 cyberpi 部分的代码不会在导入其他 python 库时出错。
简写的写法更适合在上传模式下的 micro-python 代码撰写时使用——这样你可以少打一些字。

慧编程的积木转码会倾向于使用更不容易出错的全写。

cyberpi 库中的 API

cyberpi 库提供多个 API 用以实现对硬件的控制，本页面描述童芯派的API，你还可查看童芯派的各种扩展 API：
功能扩展 API
扩展板 API
mBuild 电子模块 API

童芯派的 API

用于对童芯派本身进行编程控制，涵盖童芯派的主要功能，包含如下部分：

播放

童芯派带有扬声器和麦克风，使用以下 API 实现音频的录制、播放以及音量和播放速度的调节。

预置音频

**cyberpi.audio.play_until(music_name)**
播放预置的音频文件，该 API 会阻塞线程直至音频播放结束。参数：

• music_name str，有效范围和对应的音频效果见表(1-1)。

**cyberpi.audio.play(music_name)**
播放预置的音频文件。参数：

• music_name str，表示播放音频的文件名，有效范围为和对应的音频效果见下表1-1。

表1-1

模拟乐器

**cyberpi.audio.play_music(note, beat, type = "piano")**
以特定的音符和节拍演奏指定乐器，该 API 会阻塞线程直至播放结束。使用该 API 可以谱曲并演奏乐曲。参数：

• note int，有效范围为 0~132，表示乐器弹奏声音的频率高低，音符和参数值的关系见note 取值与音符的对应关系(表1-2)。
• beat float，有效范围为大于 0 的数值，单位为 拍 表示该音符播放的时长。在正常的播放速度下，1 拍的时长为 1s。
• type str，有效范围为"piano"，表示设定的演奏乐器。

表1-2：note 取值与音符的对应关系

示例程序(可在Python 3 与MicroPython模式分别运行)

import time
import cyberpi
cyberpi.console.println('按 B 播放乐曲')
cyberpi.console.println('Press B to play music.')
while True:
    while not cyberpi.controller.is_press('b'):
        pass
    # 右键积木可以获取帮助
    # 查看音符序号使用了 MIDI 标准，此示例涉及的几个音符的对应关系如下：
    #
    # 简谱/音符/MIDI序号
    # 1 C4 60
    # 2 D4 62
    # 3 E4 64
    # 4 F4 65
    # 5 G4 67
    # 6 A4 69
    # 7 B4 71
    cyberpi.audio.play_music(60, 0.25)
    cyberpi.audio.play_music(60, 0.25)
    cyberpi.audio.play_music(67, 0.25)
    cyberpi.audio.play_music(67, 0.25)
    cyberpi.audio.play_music(69, 0.25)
    cyberpi.audio.play_music(69, 0.25)
    cyberpi.audio.play_music(67, 0.25)
    time.sleep(1)
    cyberpi.audio.play_music(65, 0.25)
    cyberpi.audio.play_music(65, 0.25)
    cyberpi.audio.play_music(64, 0.25)
    cyberpi.audio.play_music(64, 0.25)
    cyberpi.audio.play_music(62, 0.25)
    cyberpi.audio.play_music(62, 0.25)
    cyberpi.audio.play_music(60, 0.25)

**cyberpi.audio.play_drum(type, beat)**

• type str，有效范围为"snare"：小军鼓。"bass-drum"：低音鼓。"side-stick"：鼓边敲击。"crash-cymbal"：碎音鼓。"open-hi-hat"：开音双面鼓。"closed-hi-hat"：闭音双面鼓。"tambourine"：铃鼓。"hand-clap"：拍掌。"claves"：音棒。
• beat float，有效范围为大于 0 的数值，单位为 拍 表示该音符播放的时长。在正常的播放速度下，1 拍的时长为 1s。

示例程序

import time
import cyberpi
while True:
   if cyberpi.is_tiltforward():
        cyberpi.audio.play_drum('snare', 0.25)
   if cyberpi.is_tiltforward():
        cyberpi.audio.play_drum('bass-drum', 0.25)
   if cyberpi.is_tiltforward():
        cyberpi.audio.play_drum('open-hi-hat', 0.25)
   if cyberpi.is_tiltforward():
        cyberpi.audio.play_drum('closed-hi-hat', 0.25)

录音和播放

**cyberpi.audio.record()**
开始录音，该 API 执行后，cyberpi 会一直录音直到执行 cyberpi.audio.stop_record() 或录音时长超过10秒，录音文件会被存在 RAM 中，因此当童芯派掉电将引起录音文件的丢失。

**cyberpi.audio.stop_record()**
停止录音，该 API 需要配合 cyberpi.audio.record() 使用。

**cyberpi.audio.play_record_until()**
播放录音，该 API 会阻塞线程直至音频播放结束。

**cyberpi.audio.play_record()**
播放录音。

示例程序

import cyberpi
import time
cyberpi.console.println("按下A键开始录音")
while True:                                          # while True 重复执行：
    if cyberpi.controller.is_press("a"):             # 如果童芯派按键A按下：
        cyberpi.audio.record()                       # 童芯派开始录音
        cyberpi.console.println("开始录音")          # 屏幕显示文字"开始录音"
        time.sleep(0.3)                              # 设置等待0.3秒，避免循环过快
    if cyberpi.controller.is_press("b"):             # 如果童芯派按键B按下：
        cyberpi.audio.stop_record()                  # 童芯派停止录音
        cyberpi.console.println("停止录音")          # 屏幕显示文字"停止录音"
        time.sleep(0.3)                              # 设置等待0.3秒，避免循环过快，反复触发
    if cyberpi.controller.is_press("middle"):        # 如果童芯派摇杆的中间被按下：
        time.sleep(0.3)                              # 等待0.3秒
        cyberpi.console.println("开始播放录音")       # 童芯派屏幕显示文字开始播放录音
        cyberpi.audio.play_record()                  # 童芯派开始播放录音。

模拟蜂鸣器

**cyberpi.audio.play_tone(freq, t)**
模拟蜂鸣器发声。参数：

• freq int，有效范围为20-5000Hz。超出这一范围，蜂鸣器不发声，这是出于对人耳的保护（长时间处于过高频率声音的环境下会对耳朵造成损害），因此该蜂鸣器被限制了最高频率5000Hz。
  另外，若希望以扬声器通过频率改变播放曲子，我们需要知道不同频率与音符的对应关系，以下是给到的参考：

  ['C2','65'],   ['D2','73'],   ['E2','82'],   ['F2','87'],
  ['G2','98'],   ['A2','110'],  ['B2','123'],  ['C3','131'],
  ['D3','147'],  ['E3','165'],  ['F3','175'],  ['G3','196'],
  ['A3','220'],  ['B3','247'],  ['C4','262'],  ['D4','294'],
  ['E4','330'],  ['F4','349'],  ['G4','392'],  ['A4','440'],
  ['B4','494'],  ['C5','523'],  ['D5','587'],  ['E5','659'],
  ['F5','698'],  ['G5','784'],  ['A5','880'],  ['B5','988'],
  ['C6','1047'], ['D6','1175'], ['E6','1319'], ['F6','1397'],
  ['G6','1568'], ['A6','1760'], ['B6','1976'], ['C7','2093'],
  ['D7','2349'], ['E7','2637'], ['F7','2794'], ['G7','3136'],
  ['A7','3520'], ['B7','3951'], ['C8','4186'], ['D8','4699'],

• t 播放时长，有效范围为非负数值，表示扬声器模拟蜂鸣器发出特定频率的时长。

示例程序

import cyberpi
import time
while True:
    if cyberpi.controller.is_press("a"):
        for count in range(2):
            cyberpi.audio.play_tone(800, 1)
            cyberpi.audio.play_tone(200, 1)

改变播放速度和音量

你可以通过以下 API 对扬声器的播放速度和音量进行编程。

**cyberpi.audio.add_tempo(pct)**
增加扬声器播放音频的速度。参数：

• pct int，表示播放速度相比正常播放速度增加的百分比。

**cyberpi.audio.set_tempo(pct)**
设置扬声器播放音频的速度。参数：

• pct int，有效范围为 25~400%，表示设置扬声器的播放速度为正常速度的百分比。

**cyberpi.audio.get_tempo()**
获得扬声器当前的播放速度。
返回 int，可能的范围为 25~400，参数对应的单位为%。

**cyberpi.audio.add_vol(val)**
增加扬声器的播放音量。参数：

• pct int，有效范围-100~100,参数对应的单位为%，表示播放音量增加的百分比。

**cyberpi.audio.set_vol(val)**
设置扬声器的音量大小。参数：

• pct int，有效范围0~100，对应的单位为%，表示设置扬声器播放音量的百分比。

**cyberpi.audio.get_vol()**
获得扬声器播放音量值。
返回 int，可能的范围为 0~100，对应的单位为%.

**cyberpi.audio.stop()**
停止童芯派扬声器音效的播放。

灯光

童芯派板载 5 颗可编程 RGB 灯，依赖如下 API 进行编程控制。
**cyberpi.led.on(r, g, b, id = "all")**
点亮童芯派上的LED灯珠，该API有两种使用方法：
方法1-通过设置RGB数值的方式点亮指定位置的LED灯。

• r int，有效范围是 0~255，表示 LED 灯的红色色值。
• g int，有效范围是 0~255，表示 LED 灯的绿色色值。
• b int，有效范围是 0~255，表示 LED 灯的蓝色色值。
• id int 或 str，默认值为"all"。
  id 为 str 时，有效值为"all"，此时设置所有灯珠的颜色。 id 为 int 时，有效范围为1~5，此时设置对应位置的灯珠的颜色。灯珠对应位置如下图所示：

方法1 示例程序

import cyberpi
cyberpi.led.on(255,0,0) #将整个灯条点亮为红色

方法2-通过预制颜色参数点亮LED灯

• **cyberpi.led.on(r, id = "all")**
  r 为 str ，可以填入颜色名称或缩写。颜色名称及其缩写对照表：

  红 red r
  橙 orange o
  黄 yellow y
  绿 green g
  青 cyan c
  蓝 blue b
  紫 purple p
  白 white w
  黑 black k

• id int 或 str，默认值为"all"。使用方法同方法1。

方法2 示例程序

import cyberpi
cyberpi.led.on('red', id = 1) #将灯环上1位置的灯珠点亮为红色

import cyberpi
cyberpi.led.on('r',  id = 1) #将灯环上1位置的灯珠点亮为红色

**cyberpi.led.play(name = "rainbow")**
显示预置灯效，该 API 会阻塞线程直至灯效播放结束。参数：

• name str，默认值为 "rainbow"，有效值为"rainbow"/"spoondrift"/"meteor_blue"/"meteor_green"/"flash_red"/"flash_orange"/"firefly"，表示播放的预置灯效名称。

**cyberpi.led.show(color)**
同时设置 5 颗 LED 灯的颜色，参数：

• color str，其格式需满足“color1 color2 color3 color4 color5”，其中colorx为red/green/blue/yellow/cyan/purple/white/orange/black 或是其缩写 r/g/b/y/c/p/w/o/k。颜色字符间以单个空格隔开。当颜色个数大于 5 时将被截断成 5 个。

**cyberpi.led.move(step = 1)**
将灯带从左向右滚动对应格数。参数：

• step int，有效范围 -4~4，默认值 1，表示灯带向右移动的格数。

例如，将 5 颗 LED 灯的颜色设置为 r，o，y，g，c（红、橙、黄、绿、青），使用此 API，将 step 设为 0 时，显示颜色为设置的颜色（见图 a）；将 step 设为 1 时，显示颜色依次向右移动，第一颗 LED 灯将显示原先最后一颗 LED 灯的颜色 (见图 b)。

**cyberpi.led.off(id = "all")**
熄灭指定位置的灯珠。参数：

• id int 或 str，默认值 "all"。id 为 int 时，有效范围 1~5，对应熄灭指定位置的灯珠。 id 为 str 时，有效范围 "all"，表示熄灭所有的灯珠。

**cyberpi.led.add_bri(brightness)**
增加童芯派上 LED 灯的显示亮度。参数：

• brightness int，有效范围 -100~100%，表示 LED 灯亮度的增加的百分比。

**cyberpi.led.set_bri(brightness)**
设置童芯派上 LED 灯的显示亮度。参数：

• brightness int，有效范围 0~100%，表示 LED 灯点亮亮度的百分比。

**cyberpi.led.get_bri()**
获得童芯派上 LED 灯的显示亮度值。
返回 int，可能的范围为 0~100%。

示例程序

import cyberpi
while True:
    for count in range(10):
        cyberpi.led.add_bri(10)
        cyberpi.led.move(1)
    for count2 in range(10):
        cyberpi.led.add_bri(-10)
        cyberpi.led.move(1)

显示

童芯派板载一块 1.44寸 全彩显示屏，通过以下 API 实现图文显示，图表绘制，游戏设计和 APP 设计。

打印图文

**cyberpi.console.print(message)**
打印控制台信息。信息将以小号字体在童芯派的显示屏上显示，该接口打印的信息和print() 或 println() 打印的信息会叠加在一起，一行数据满后自动换行显示。参数：

• message str，表示需要打印的信息，如 "hello"。

示例程序

import cyberpi
cyberpi.console.print('hello')
cyberpi.console.print('world')

**cyberpi.console.println(message)**
信息将在控制台显示，该接口打印的信息会换行显示。

• message str，表示需要打印的信息，如 "hello"。

示例程序

import cyberpi
import time
cyberpi.console.println('hello world')
time.sleep(3)
cyberpi.console.print('hello'+' '+'world')

全屏文本显示

**cyberpi.display.show_label(message, size, x, y,index)**
该API有两种使用方法。
方法1：基于坐标的图文显示方法
全屏显示图文。参数：

• message str，表示需要打印的信息，如 "hello"。
• size int，表示打印信息的字号，有效值为 16,24,32
• x int有效值为 0~127，表示标签的左上角位于屏幕的 x 坐标位置。
• y int有效值为 0~127，表示标签的左上角位于屏幕的 y 坐标位置。
• index int有效值为 0-7，表示不同的标签。

方法1示例程序：

import cyberpi
cyberpi.display.show_label('cyberpi', 16, x = 64, y = 64, index= 0)

方法2：基于已定义位置的显示方法
全屏显示图文。参数：

• message str，表示需要打印的信息，如 "hello"。
• size int，表示打印信息的字号，有效值为 16,24,32
• x str 或 int表示信息显示的位置，

当 x 为 str 时，有效值为：
"top_mid"，此时文案在屏幕中顶部居中显示。
"top_left"，此时文案在屏幕中顶部左侧显示。
"top_right"，此时文案在屏幕中顶部右侧显示。
"center"，此时文案在屏幕中居中显示。
"mid_left"，此时文案在屏幕中居中靠左显示。
"mid_right"，此时文案在屏幕中居中靠右显示。
"bottom_mid"，此时文案在屏幕中底部居中显示。
"bottom_left"，此时文案在屏幕中底部靠左显示。
"bottom_right"，此时文案在屏幕中底部靠右显示。

• y参数不需要填写。
• index int有效值为 0-7，表示不同的标签。

方法2示例程序：

import cyberpi
cyberpi.display.show_label('cyberpi', 16, 'center', index = 0)

绘制图表

**cyberpi.linechart.add(data)**
显示折线图，并向折线图中添加数据。通过 cyberpi.display.set_brush(color) 改变颜色，可以同时显示不同颜色的折线图用以同时呈现多个数据。参数：

• data float，有效范围 0~100，因此如果需要键入超过该范围的数值时，需要先对原始进行归一化处理。

**cyberpi.linechart.set_step(step)**
设置折线图的数据点间的显示间距。参数：

• step int，显示间距，有效范围为 0~128 像素。

例如，输入 5 天的气温值 17、20、24、26、30 后，以 8 和 2 像素的间距显示效果分别如下：

**cyberpi.barchart.add(data)**
显示柱状图，并向柱状图中添加数据。通过 display.set_brush(r, g, b) 改变颜色，可以同时显示不同颜色的柱，用以同时呈现多个数据，柱的宽度会随着显示的柱的数量实时变化。参数：

• data float，有效范围 0~100，因此如果需要键入超过该范围的数值时，需要先对原始进行归一化处理。

**cyberpi.table.add(row, column, data)**
显示表格，并向表格中添加数据，表格会根据填写数据的位置来变换其实时显示的行列数，至多可以显示4行3列内容。当填写的数据过长时，数据会在单元格内滚动。通过 display.set_brush(r, g, b) 改变颜色，可以在表格的不同行列显示不同的文字。此处的文字依旧支持与预置的图标混排。参数：

• row int，表示填写内容所在的行数。
• column int，表示填写内容所在列数。
• data str，表示向表格内容添加的信息。

示例程序

import random
import cyberpi
import time
cyberpi.console.println('Magic Volume Column')
cyberpi.console.println('光影音量柱')
cyberpi.console.println('Press B to start')
cyberpi.console.println('按 B 以开始...')
while not cyberpi.controller.is_press('b'):
    cyberpi.display.set_brush(random.randint(1, 255), random.randint(1, 255), random.randint(1, 255))
    time.sleep(0.1)
cyberpi.led.on(114, 0, 255, 1)
cyberpi.led.on(191, 0, 255, 2)
cyberpi.led.on(255, 0, 195, 3)
cyberpi.led.on(255, 0, 72, 4)
cyberpi.led.on(255, 0, 0, 5)
while True:
    cyberpi.led.set_bri(cyberpi.get_loudness("maximum"))
    cyberpi.display.set_brush(114, 0, 255)
    cyberpi.barchart.add(cyberpi.get_loudness("maximum"))
    time.sleep(0.02)
    cyberpi.display.set_brush(191, 0, 255)
    cyberpi.barchart.add(cyberpi.get_loudness("maximum"))
    time.sleep(0.02)
    cyberpi.display.set_brush(255, 0, 195)
    cyberpi.barchart.add(cyberpi.get_loudness("maximum"))
    time.sleep(0.02)
    cyberpi.display.set_brush(255, 0, 72)
    cyberpi.barchart.add(cyberpi.get_loudness("maximum"))
    time.sleep(0.02)
    cyberpi.display.set_brush(255, 24, 24)
    cyberpi.barchart.add(cyberpi.get_loudness("maximum"))
    time.sleep(0.05)

显示屏设置

**cyberpi.display.set_brush(r, g, b)**
用于设置童芯派显示内容的颜色，也叫做笔刷颜色。该API有两种使用方法：
方法1-通过设置RGB数值的方式设置笔刷颜色。

• r int ，有效范围是 0~255，表示笔刷的红色色值。
• g int，有效范围是 0~255，表示笔刷的绿色色值。
• b int，有效范围是 0~255，表示笔刷的蓝色色值。

方法2-通过预制颜色参数设置笔刷颜色。

• r str。表示颜色名称或缩写。其它参数无需填写。颜色名称及其缩写对照表：

  红 red r
  橙 orange o
  黄 yellow y
  绿 green g
  青 cyan c
  蓝 blue b
  紫 purple p
  白 white w
  黑 black k

  **cyberpi.display.rotate_to(angle)**
  旋转显示屏。为了保证旋转后的显示效果，显示屏的面向角度被限制在 -90，0，90，180/-180 5个角度上。显示屏的显示效果与对应面向角度关系如下图所示。参数：

• angle int，有效范围为 -90/0/90/180/-180°。

**cyberpi.display.clear()**
清除显示屏的显示内容。

**cyberpi.display.off()**
关闭显示屏背光。

感知

童芯派利用如下 API 读取板载传感器读值或一些关于主机的信息。

按钮和摇杆状态

cyberpi 自带一个摇杆（五向控制）和两个按钮（A、B），如下图所示：

使用如下 API 进行控制：
**cyberpi.controller.is_press(name)**
判断对应按钮或摇杆是否被触发。参数：

• name str，代表判断被触发按钮或摇杆的名字。有效范围为：

"a" ：按钮A（方形）
"b" ：按钮B（三角形）
"up" ：摇杆向上拨动
"down" ：摇杆向下拨动
"left" ：摇杆向左拨动
"right" ：摇杆向右拨动
"middle" ：摇杆中间按下
"any_direction" ：摇杆朝任意方向拨动
"any_button" ：按钮A或B
"any" ：任意按钮或摇杆触发
返回 bool。

**cyberpi.controller.get_count(name)**
获取对应按钮或摇杆是否被触发的计数。参数：

• name str，代表判断被触发按钮或摇杆的名字。有效范围：

"a" ：按钮A（方形）
"b" ：按钮B（三角形）
"up" ：摇杆向上拨动
"down" ：摇杆向下拨动
"left" ：摇杆向左拨动
"right" ：摇杆向右拨动
"middle" ：摇杆中间按下
返回 int。

**cyberpi.controller.reset_count(name)**
将按钮或摇杆的触发计数重置为 0。参数：

• name str，代表判断被触发按钮或摇杆的名字。有效范围：

"a" ：按钮A（方形）
"b" ：按钮B（三角形）
"up" ：摇杆向上拨动
"down" ：摇杆向下拨动
"left" ：摇杆向左拨动
"right" ：摇杆向右拨动
"middle" ：摇杆中间按下
"any_direction" ：摇杆朝任意方向拨动
"any_button" ：按钮A或B
"any" ：任意按钮或摇杆触发

获取传感器的读值

**cyberpi.get_bri()**
获取板载光线传感器读到的环境光亮度数据。 返回 int，可能的范围为 0~100，当返回值为 100 时，光线传感器达到了它的最大量程。

**cyberpi.get_loudness(mode = "maximum")**
获取板载麦克风读到的环境响度。参数：

• mode str，有效范围为 "average"：获得一段时间内的响度平均值；"maximum"：获得一段时间内响度的最大值。显然地，type = “maximum” 时，将更易于构建对声音变化敏感的项目。
  返回int，可能的范围为 0~100，当返回值为 100 时，麦克风达到了它的最大量程。

计时器

**cyberpi.timer.get()**
获取童芯派计时器的时间，该计时器会在开机时启动。 返回 float，单位为秒。

**cyberpi.timer.reset()**
将童芯派计时器的时间置为 0。

其他读值

**cyberpi.get_mac_address()**
获取 Wi-Fi 的 mac 地址，注意 Wi-Fi 未连接前，mac 地址可能出现错误。
返回 str，长度为 12 字节，例如 "FFEE33445566"

**cyberpi.get_battery()**
获取童芯派连接的扩展板的电池电量，单位%。 返回int，可能的范围为0~100，当返回值为 100 时，电池电量为最大值；当返回值为 0 时，cyberpi 未连接扩展板，或扩展板的电池电量为 0。

**cyberpi.get_firmware_version()**
获得固件版本号。 返回 str，例如"44.01.001"

**cyberpi.get_ble()**
获得蓝牙名称。 获得童芯派广播出的蓝牙名称。 返回 str，例如"Makeblock_LE_XXXXX"

**cyberpi.get_name()**
获得童芯派的名称，该名称默认为"CyberPi"，但可以通过set_name(name)函数进行设置。

**cyberpi.set_name(name)**
设置童芯派的名称，该名称会在 CyberOS 的操作界面中被显示，你可以通过设置该名字来找到自己的硬件设备，或是利用该名字在局域网或物联网中识别彼此的身份。参数：

• name str，表示用户设置的新名字，如 "Alex"，"小明"。

**cyberpi.get_language()**
获得童芯派当前的系统语言。返回 str，可能值为：
"chinese"：中文；
"cantonese"：繁体中文；
"japanese"：日文；
"english"：英文；
"french"：法文；
"german"：德文；
"spanish"：西班牙文；
"portuguese"：葡萄牙文；
"russian"：俄文；
"korean"：韩文；
"italian"：意大利文；
"dutch"：荷兰文

体感

童芯派上的陀螺仪与加速度计配合内置的运动检测算法，可以实现体感控制的功能。童芯派依赖以下 API 获得对应的姿态数据。

判断自身姿态

**cyberpi.is_tiltforward()**
判断童芯派是否向前倾斜。前倾姿态如下图所示：

返回 bool。

**cyberpi.is_tiltback()**
判断童芯派是否向后倾斜。后倾姿态如下图所示：

返回 bool。

**cyberpi.is_tiltleft()**
判断童芯派是否向左倾斜。左倾姿态如下图所示：

返回 bool。

**cyberpi.is_tiltright()**
判断童芯派是否向右倾斜。右倾姿态如下图所示：

返回 bool。

**cyberpi.is_faceup()**
判断童芯派是否正面向上。正面向上姿态如下图所示：

返回 bool。

**cyberpi.is_facedown()**
判断童芯派是否正面向下。正面向下姿态如下图所示：

返回 bool。

**cyberpi.is_stand()**
判断童芯派是否垂直地面（灯条向下）。垂直地面姿态如下图所示：

返回 bool。

**cyberpi.is_handstand()**
判断童芯派是否垂直地面倒置（灯条朝上）。垂直地面倒置姿态如下图所示：

返回 bool。

检测持续动作

**cyberpi.is_shake()**
判断童芯派是否被摇晃，当摇晃强度高于 20 时，会认为童芯派被摇晃。 返回 bool。

**cyberpi.is_waveup()**
判断童芯派是否向上挥动，此时童芯派需要被竖向握持。 返回 bool。

**cyberpi.is_wavedown()**
判断童芯派是否向下挥动，此时童芯派需要被竖向握持。 返回 bool。

**cyberpi.is_waveleft()**
判断童芯派是否向左挥动，此时童芯派需要被竖向握持。 返回 bool。

**cyberpi.is_waveright()**
判断童芯派是否向右挥动，此时童芯派需要被竖向握持。 返回 bool。

**cyberpi.is_freefall()**
判断童芯派是否处于自由落体状态。 返回 bool。

**cyberpi.is_clockwise()**
判断童芯派是否正在绕 z 轴顺时针转动。 返回 bool。

**cyberpi.is_anticlockwise()**
判断童芯派是否正在绕 z 轴逆时针转动。 返回 bool。

读取姿态数据和加速度数据

**cyberpi.get_shakeval()**
获得摇晃强度，摇晃强度与摇晃的频率和幅度呈正相关性。 返回 int，可能的范围为0~100，当返回值为 100 时，摇晃强度达到其最大量程。

**cyberpi.get_wave_angle()**
获得挥动的方向，挥动方向定义如下图。 返回 int，可能的范围为-179~180，单位 °。

**cyberpi.get_wave_speed()**
获得挥动的速度大小。挥动的速度与童芯派实际的运动速度有正相关性，但并不等效，因为积分误差会使得该数值存在较大误差。 返回 int，可能的范围为0~100。

**cyberpi.get_pitch()**
获取童芯派的俯仰角大小，该角度等于童芯派y轴与水平面的夹角。 返回 int，可能的范围为-90~90，单位 °。

**cyberpi.get_roll()**
获取童芯派的翻滚角大小，该角度等于童芯派x轴与水平面的夹角。 返回 int，可能的范围为 -179~180，单位 °。

**cyberpi.get_yaw()**
获取童芯派的偏航角大小，需要注意，由于缺失罗盘，该度数会有累积误差。你可以通过 reset_yaw() 来重新校准偏航角的读值。（对于没有罗盘的童芯派来说，这意味着将偏航角的读值设为 0。) 返回 int，可能的范围为-180~180，单位 °。

**cyberpi.reset_yaw()**
校准偏航角的读值。对于没有罗盘的童芯派来说，这意味着将偏航角的读值设为 0。

**cyberpi.get_acc(axis)**

获得加速度计读值，单位（m/s²）。参数：

• axis str，有效值为"x"/"y"/"z"，代表童芯派定义的坐标轴。
  返回 float，表示对应轴的加速度读值，需要注意该读值会受到地球重力的影响，因此当童芯派静置在水平桌面时，其 z 轴有 -9.8m/s² 的加速度读值。（1g = 9.8m/s²。）

**cyberpi.get_gyro(axis)**
获取三个轴的角速度值。参数：

• axis str，有效值为"x"/"y"/"z"，代表童芯派定义的坐标轴。

返回 int，可能的范围为 -500~500，单位是 °/s。

**cyberpi.get_rotation(axis)**
获得光环板在三个轴上转动的角度，以逆时针转动方向为正方向。参数：

• axis str，有效值为"x"/"y"/"z"，代表童芯派定义的坐标轴。

返回数值，单位是 °。

**cyberpi.reset_rotation(axis= "all")**
将绕三个轴转动的角度变为 0，get_rotation(axis) 函数将从 0 开始计算。参数：

• axis str，有效值是 "x"/"y"/"z"/"all"。"x"/"y"/"z"代表童芯派定义的坐标轴。默认值为"all" 代表全部的三个轴。

返回 int，单位 °。

wifi

童芯派内置 Wi-Fi 模组，依赖以下 API 可以实现网络连接和局域网广播。
**cyberpi.wifi.connect(ssid, password)**
启动wifi连接，该API不阻塞，API 退出不代表Wi-Fi已连接上，需要调用wifi.is_connect()进行判断，参数：

• ssid str，Wi-Fi帐号。
• password str，Wi-Fi密码。

**cyberpi.wifi.is_connect()**
检测 Wi-Fi 连接状态。 返回 bool。
**cyberpi.wifi_broadcast.set(message, val)**
发送局域网广播，参见局域网广播。
**cyberpi.wifi_broadcast.get(message)**
接收局域网广播，参见局域网广播。

云服务

当童芯派连接到互联网后，可以依赖 makeblock 提供的各项云服务实现 AI、IoT 功能。
**cyberpi.cloud.setkey(key)**
验证慧编程帐号，以便获得 makeblock 提供的各项云服务的使用权限。需要注意，该 API 需要在童芯派连接到互联网后方可使用。参数：

• key str，云服务授权码，登录慧编程网页端或客户端，然后按如下步骤可以获得你的云服务授权码。

物联网

**cyberpi.cloud.weather(option, woe_id)**
获得指定地点的实时气象数据。参数：

• option str ，表示可获取的气象数据选项，有效值为："max_temp" 最高气温。"min_temp"最低气温。"weather"天气。"humidity"空气湿度。
• woe_id str 表示要获取气象数据的城市编码。

各城市对应的编码可访问天气查询网站获得。

将地点修改为你想要了解天气情况的城市，然后就可以在地址栏中查看该城市的编码。

你也可以查看慧编程中对应积木块的转码，如下图所示。
返回 str 表示对应气象数据的查询结果。其中，天气查询结果的返回值可能结果如下表：

0    tornado
1    tropical storm
2    hurricane
3    severe thunderstorms
4    thunderstorms
5    mixed rain and snow
6    mixed rain and sleet
7    mixed snow and sleet
8    freezing drizzle
9    drizzle
10    freezing rain
11    showers
12    rain
13    snow flurries
14    light snow showers
15    blowing snow
16    snow
17    hail
18    sleet
19    dust
20    foggy
21    haze
22    smoky
23    blustery
24    windy
25    cold
26    cloudy
27    mostly cloudy (night)
28    mostly cloudy (day)
29    partly cloudy (night)
30    partly cloudy (day)
31    clear (night)
32    sunny
33    fair (night)
34    fair (day)
35    mixed rain and hail
36    hot
37    isolated thunderstorms
38    scattered thunderstorms
39    scattered showers (day)
40    heavy rain
41    scattered snow showers (day)
42    heavy snow
43    blizzard
44    not available
45    scattered showers (night)
46    scattered snow showers (night)
47    scattered thundershowers

**cyberpi.cloud.air(option, woe_id)**

• option str ，表示可获取的空气质量数据选项，有效值为："aqi"空气质量指数"pm2.5"PM2.5 浓度"pm10"PM10 浓度"co" 一氧化碳浓度"so2" 二氧化硫浓度"no2" 二氧化氮浓度
• woe_id str 表示要获取气象数据的城市编码。 返回 str 表示对应空气质量数据的查询结果。

**cyberpi.cloud.time(option, location)**

• option str ，表示可获得的时间数据选项，有效值为：

"sunrise_time"日出时间；
"sunrise_hour"日出时间的时；
"sunrise_minute"日出时间的分；
"sunset_time"日落时间；
"sunset_hour"日落时间的时；
"sunset_minute"日落时间的分。
【未实装】
"hour"：当前时区的时；
"minute"：当前时区的分；
"second"：当前时区的秒；
"year"：当前时区年份；
"month"：当前时区的月份；
"day"：当前时区的星期；
"date"：当前时区的日期；

• location str 或 int 表示要获取日出日落或当地时间的地区。

当其为 str 时，表示需要获得日出日落时间的地区，其有效值为城市对应的 woe_id，可通过访问雅虎天气查询获得。

将地点修改为你想要了解天气情况的城市，然后就可以在地址栏中查看该城市的编码。

你也可以查看慧编程中对应积木块的转码，如下图所示。
【未实装】当其为 int 时，表示需要查询 年、月、日、星期、时、分、秒 的所在时区，其有效值为 -12~12
返回 str 或 int 表示对应时间选项的查询结果。

人工智能

通过联网使用一些人工智能接口，童芯派具备人工智能能力，能够进行语音识别、文本朗读、智能翻译等功能。
**cyberpi.cloud.listen(language,t=3)**
开始进行语音识别，该 API 将阻塞直至得到语音识别的结果。参数：

• language str，有效值为："chinese"：汉语；"chinese_taiwan"：台湾普通话；"cantonese"：粤语；"japanese"：日语；"english"：英语；"french"：法语；"german"：德语；"spanish"：西班牙语；"portuguese"：葡萄牙；"russian"：俄语；"korean"：韩语；"italian"：意大利语；"dutch"：荷兰语；表示需要识别语言的种类。
• t float 或 str，默认值为3。 t 为 int时，表示语音识别持续的时间，单位为秒。 t 为 str时，有效值 "record"，表示使用最近一次的录音文件进行语音识别。

**cyberpi.cloud.listen_result()**
获得最近一次的语音识别结果。 返回 str。

**cyberpi.cloud.tts("zh", message)**
朗读对应文本。参数：

• “zh”表示自动识别语言。
• message str，表示朗读的文本内容。

**cyberpi.cloud.translate(language, message)**
翻译对应语种的文本。参数：

• language str，有效值为：

"chinese"：中文；
"cantonese"：繁体中文；
"japanese"：日文；
"english"：英文；
"french"：法文；
"german"：德文；
"spanish"：西班牙文；
"portuguese"：葡萄牙文；
"russian"：俄文；
"korean"：韩文；
"italian"：意大利文；
"dutch"：荷兰文；
表示需要翻译的目标语种。

• message str，表示需要翻译的源文本内容。

  广播

  童芯派可以使用多种不同类型的广播，这些广播有各自的用途，能够帮助童芯派在线程、局域网、互联网之间互相通信。

基础广播

**cyberpi.broadcast(message)**
发送广播消息，广播将能被所有童芯派内的线程所接受，或在在线模式下被慧编程舞台接受。参数：

• message str，广播消息的名称。

局域网广播

:::info 注意：
参与局域网广播的童芯派必须处于同一频道。
所有童芯派都有相同的默认频道，未连接路由器时，童芯派会处于默认的频道，此时相互之间能够进行局域网广播通信；连接路由器后，童芯派的频道取决于路由器的设置，可能会与默认频道不同，从而无法与未连接路由器的童芯派通信。
因此，为了确保正常通信，如使用路由器联网，请将需要参与局域网广播的所有童芯派都连接至同一路由器。 :::

**cyberpi.wifi_broadcast.set(message, val)**
发送局域网广播并附带值.参数：

• message str，局域网广播消息的名称。
• val str，局域网广播消息的值。

**cyberpi.wifi_broadcast.get(message)**
获取指定局域网广播消息的值。参数：

• message str，广播的消息名称。 返回 str。

提示：在程序当中直接调用该API，可能会出现无法正常接收广播的情况。由于在运行其它带有阻塞的代码，可能会导致程序错过广播的接收。如下方示例程序所示，如果程序在执行time.sleep(1)代码时，另一个童芯派在这时发送了一个广播，则接收的童芯派可能会错过广播的接收。

import cyberpi
import time
while True:
    cyberpi.led.on(0,0,255,1)
    time.sleep(1)
    cyberpi.wifi_broadcast.get(message)

上传模式广播

**cyberpi.upload_broadcast.set(message, val)**
发送上传模式广播消息，当童芯派与慧编程通过蓝牙或 USB 线保持连接状态时，上传模式广播将能被慧编程舞台所接收。该功能主要用于一些对实时性有较高要求的软硬件互动项目。参数：

• message str，上传模式广播消息的名称。
• val str，上传模式广播消息的值。

**cyberpi.upload_broadcast.get(message)**
获得指定名称上传模式广播消息的值。参数：

• message str，上传模式广播的消息名称。

返回 str。
提示：在程序当中直接调用该API，可能会出现无法正常接收广播的情况。由于在运行其它带有阻塞的代码，可能会知道程序错过广播的接收。如下方示例程序所示，如果程序在执行time.sleep(1)代码时，另一个童芯派在这时发送了一个广播，则接收的童芯派可能会错过广播的接收。

import cyberpi
import time
while True:
    cyberpi.led.on(0,0,255,1)
    time.sleep(1)
    cyberpi.upload_broadcast.get(message)

帐号云广播

**cyberpi.cloud_broadcast.set(message, val)**
发送帐号云广播消息，使用该功能需要先使用 wifi.is_connect() 与 cloud.setkey(key) 使硬件获得 makeblock 的云服务使用权限。帐号云广播会被发送给同一慧编程帐号下的所有在线的硬件设备和慧编程舞台。利用此功能，你可以轻松地通过互联网访问、控制你的硬件，并利用慧编程舞台或 Python 设计对应的可视化交互界面。参数：

• message str，帐号云广播消息的名称。
• val str，帐号云广播消息的值。

**cyberpi.cloud_broadcast.get(message)**
获得指定名称帐号云广播消息的值。参数：

• message str，帐号云广播的消息名称。

返回 str。
提示：在程序当中直接调用该API，可能会出现无法正常接收广播的情况。由于在运行其它带有阻塞的代码，可能会知道程序错过广播的接收。如下方示例程序所示，如果程序在执行time.sleep(1)代码时，另一个童芯派在这时发送了一个广播，则接收的童芯派可能会错过广播的接收。

import cyberpi
import time
while True:
    cyberpi.led.on(0,0,255,1)
    time.sleep(1)
    cyberpi.cloud_broadcast.get(message)

脚本控制

**cyberpi.stop_all()**
停止所有脚本。

**cyberpi.stop_this()**
停止当前脚本。

**cyberpi.stop_other()**
停止当前脚本外的其他脚本。
**cyberpi.restart()**
重启童芯派。

事件

童芯派 支持多线程，通过添加事件头代码来为童芯派添加对应的线程，线程监听特定事件的发生。当事件发生时，对应线程下的代码被执行。

:::info 注意：事件部分的 API 无法在 Python 下被使用。你需要依赖 Python3 本身的 threading 机制来撰写在线的多线程代码。 :::

事件的写法

事件头使用修饰器写法，如以下示例：

import cyberpi
@cyberpi.event.start # 你需要监听的事件
def callback():
    cyberpi.led.on("green") # 事件被触发后需要执行的代码
@cyberpi.event.received('hello') # 你需要监听的带参数的事件
def callback():
    cyberpi.led.on("blue") # 事件被触发后需要执行的代码

在此写法下，事件头触发时事件下定义的函数将被执行。在此例子中，该函数名称是callback()，但实际上，任何合乎命名规则的名字都是可以的。你也不用担心函数名称是否重名，因为该函数是被定义在事件下的。
因此，你可以看到，尽管在上述例子中，按下按钮或接受到广播消息”hello”都将导致 callback() 被执行，但他们其实都仅指向各自的事件而不至于互相冲突。

事件的判断机制

事件头只在其监听的事件发生时被触发。对于按钮按下的事件来说，其仅在按钮状态从未按下变为按下时触发，并执行其下的代码。若按钮一直保持在被按下的状态，其下的代码是不会被执行的。

事件头相关 API

**cyberpi.event.start**
启动事件，童芯派 启动时被触发。

import cyberpi
@cyberpi.event.start
def start():
    cyberpi.console.println("启动了")

**cyberpi.event.is_press(name)**
按键事件，童芯派 板载按钮A\B 或摇杆拨动时被触发。参数：

• name str，代表判断被触发按钮或摇杆的名字。有效范围为：

"a" ：按钮A（方形）
"b" ：按钮B（三角形）
"up" ：摇杆向上拨动
"down" ：摇杆向下拨动
"left" ：摇杆向左拨动
"right" ：摇杆向右拨动
"middle" ：摇杆中间按下
"any_direction" ：摇杆朝任意方向拨动
"any_button" ：按钮A或B
"any" ：任意按钮或摇杆触发

import cyberpi
@cyberpi.event.is_press("a")
def button():
    cyberpi.console.println("按键A按下了")

**cyberpi.event.is_tiltforward**
前倾事件，童芯派 向前倾时被触发。

import cyberpi
@cyberpi.event.is_tiltforward
def tiltforward():
    cyberpi.console.println("向前倾斜啦")

**cyberpi.event.is_tiltback**
后倾事件，童芯派 向后倾时被触发。

import cyberpi
@cyberpi.event.is_tiltback
def tiltback():
    cyberpi.console.println("向后倾斜啦")

**cyberpi.event.is_tiltleft**
左倾事件，童芯派 向左倾斜时被触发。

import cyberpi
@cyberpi.event.is_tiltleft
def tiltleft():
    cyberpi.console.println("向左倾斜啦")

**cyberpi.event.is_tiltright**
右倾事件，童芯派 向右倾斜时被触发。

import cyberpi
@cyberpi.event.is_tiltright
def tiltright():
    cyberpi.console.println("向右倾斜啦")

**cyberpi.event.is_faceup**
正面朝上事件，童芯派正面向上时被触发。

**cyberpi.event.is_facedown**
背面朝上事件，童芯派背面向上时被触发。

**cyberpi.event.is_stand**
站立事件，童芯派竖直立于水平面上（灯带朝下）时触发。

**cyberpi.event.is_handstand**
倒立事件，童芯派竖直倒立于水平面上（灯带朝上）时触发。

**cyberpi.event.is_shake**
摇晃事件，童芯派检测到摇晃时被触发。

import cyberpi
@cyberpi.event.is_shake
def shaking():
    cyberpi.console.println("摇晃啦！")

**cyberpi.event.is_waveup**
向上挥动事件，童芯派向上挥动时触发。

**cyberpi.event.is_wavedown**
向下挥动事件，童芯派向下挥动时触发。

**cyberpi.event.is_waveleft**
向左挥动事件，童芯派向左挥动时触发。

**cyberpi.event.is_waveright**
向右挥动事件，童芯派向右挥动时触发。

**cyberpi.event.is_freefall**
自由落体事件，童芯派自由落体时触发。

**cyberpi.event.is_clockwise**
顺时针旋转事件，童芯派绕 z 轴顺时针旋转时触发。

**cyberpi.event.is_anticlockwise**
逆时针旋转事件，童芯派绕 z 轴逆时针旋转时触发。

**cyberpi.event.greater_than(threshold, type)**
大于比较事件， 超过阈值则触发，参数：

• threshold int，有效范围是0~100，表示触发阈值。
• type str，有效范围为："microphone"：麦克风。"light_sensor"：光线传感器。"shake_val"摇晃强度。"timer"：计时器。

**cyberpi.event.smaller_than(threshold, type)**
小于比较事件， 小于阈值则触发，参数：

• threshold int，有效范围是0~100，表示触发阈值。
• type str，有效范围为："microphone"：麦克风。"light_sensor"：光线传感器。"shake_val"摇晃强度。"timer"：计时器。 ```python import cyberpi

@cyberpi.event.smaller_than(50, “microphone”) def detect(): cyberpi.console.println(“声音大于阈值”) `` ![Py2.png](https://cdn.nlark.com/yuque/0/2021/png/536550/1622537195043-362c198c-2051-40d6-b514-3fe62cd01399.png#clientId=udea050f3-706d-4&crop=0&crop=0&crop=1&crop=1&from=drop&height=29&id=UO3hw&margin=%5Bobject%20Object%5D&name=Py2.png&originHeight=422&originWidth=421&originalType=binary&ratio=1&rotation=0&showTitle=false&size=8520&status=done&style=stroke&taskId=ucdf65d17-28fc-4ce8-9935-97c33e33895&title=&width=29)![Mp2.png](https://cdn.nlark.com/yuque/0/2021/png/536550/1622537243110-a797f2d6-a3da-412a-930a-e1b70cc25a2b.png#clientId=udea050f3-706d-4&crop=0&crop=0&crop=1&crop=1&from=drop&height=29&id=w2LhJ&margin=%5Bobject%20Object%5D&name=Mp2.png&originHeight=421&originWidth=421&originalType=binary&ratio=1&rotation=0&showTitle=false&size=8004&status=done&style=stroke&taskId=ud99db07e-4c39-48cf-bf8a-e2021159de9&title=&width=29)cyberpi.event.receive(message)`
广播事件，收到广播消息时被触发，参数：

• message str，监听的广播消息名称。

**cyberpi.event.upload_broadcast(message)**
上传模式广播事件，收到上传模式广播消息时被触发，参数：

• message str，上传模式广播的消息名称。

**cyberpi.event.cloud_broadcast(message)**
帐号云广播事件，收到帐号云广播消息时被触发，参数：

• message str，帐号云广播的消息名称。

**cyberpi.event.wifi_broadcast(message)**
局域网广播事件，参数：

• message str，局域网广播的消息名称。