除了通过连接扩展板和电子模块实现功能扩展，童芯派自身也能够实现强大的功能扩展。目前， cyberpi 库中提供了“精灵”和“涂鸦” API 用于实现童芯派显示屏的功能扩展，更多 API 正在开发中。 :::tips 提示：这些 API 不支持 Python 3 编程，仅支持 MicroPython 编程，只能在“上传”模式下使用。有关编程模式的说明和使用，参见“在线模式和上传模式”。 :::

为了让您更好的阅读童芯派的API文档，我们对API的可使用场景（Python３与MicroPython）进行了标识。Python3 对应的是童芯派在线模式的编程，MicroPython对应的是上传模式的编程。
支持Python 3 的标识：
支持MicroPython 的标识：

显示屏+ API

精灵（显示屏）

精灵 API 能够极大地发挥童芯派彩色显示屏的创作潜力。通过这些 API，你能够制作各种小游戏和 UI 界面。

设置背景

**cyberpi.background.fill(r, g, b)**
初始化背景，目前只支持将背景设置为某一个统一的颜色。参数：

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

**cyberpi.background.copy()**
将屏幕当前显示的画面复制，作为背景，此版本暂不对外使用。

创建精灵

**sprite1 = cyberpi.sprite()**
声明一个精灵对象 sprite1。
精灵在创建时，各个属性的默认值为：

属性	默认值
x 坐标	64
y 坐标	64
方向	90°
大小	100%
锚点	中心
是否显示	是
默认颜色	白色
图层	新创建的精灵位于更高的图层

**sprite.set_pixel(color, x, y)**
改变精灵图层指定像素点的颜色，此版本暂不对外使用。参数：

• color str，有效范围为 "0x000000" 到 "0xFFFFFF" 表示设置像素点的 RGB 颜色的色值。
• x int，有效范围 0~127，表示设置的像素点的 x 坐标。
• y int，有效范围 0~127，表示设置的像素点的 y 坐标。

童芯派显示屏坐标轴定义如下：

**sprite.draw_text(text)**
使用一段文字做为精灵，默认为 16像素高度的字体大小。参数：

• text str ，表示作为精灵的字符串。

当输入的文字为字库不支持的语言时，显示会混乱。童芯派支持的语种如下：

• 简体中文 SC
• 英文 EN
• 法文 | French | Français
• 西班牙文 | Spanish | Español
• 繁体中文 | Traditional Chinese | 繁體中文
• 德文 | German | Deutsch
• 意大利文 | Italian | Italiano
• 葡萄牙文 | Portuguese | Português
• 俄文 | Russian | русский язык
• 韩文 | Korean | 한국어
• 日文
• 荷兰语

**sprite.draw_icon(name)【未实装】**
使用图标做为精灵。参数：
name str ，选择的图标名称，其有效范围如下：

参数值	对应图标		参数值	对应图标
“music”			“download”
“image”			“sunny”
“video”			“cloudy”
“clock”			“rain”
“play”			“snow”
“pause”			“train”
“next”			“rocket”
“prev”			“truck”
“sound”			“car”
“temperature”			“droplet”
“light”			“distance”
“motion”			“fire”
“home”			“magnetic”
“gear”			“gas”
“list”			“vision”
“right”			“color”
“wrong”			“overcast”
“shut_down”			“sandstorm”
“refresh”			“foggy”
“trash_can”

**sprite.draw_pixel(pixel, x_size, y_size)**
使用自定义像素画做为精灵。参数：

• pixel array，十六进制数列，用以描述像素画从左到右，从上到下的像素点颜色。如 [0xFF0000, 0x00FF00, 0x0000FF] 即表示一个头 3 个像素点颜色为红、绿、蓝的像素画。
• x_size int，默认值为 16 ，表示像素画的横向宽度。
• y_size int，默认值为 16 ，表示像素画的纵向高度。

对于超出 x、y 长宽定义部分的颜色会被丢弃，未满的部分颜色会被定义为透明。

**sprite.draw_QR(content)**
使用二维码做为精灵。参数：
content str，表示需要显示的二维码的内容。

示例程序：

import cyberpi
qrcode = cyberpi.sprite()
qrcode.draw_qrcode("Welcome")
qrcode.set_size(size=300)
qrcode.show()
cyberpi.screen.render()

**sprite.draw_sketch()**
使用当前的涂鸦结果做为精灵。

**sprite.mirror(axis)**
将精灵的形象进行上下或水平的垂直的镜像翻转。参数：

• axis str，有效范围为:

"x"：表示将精灵绕 x 轴方向进行镜像翻转，即垂直镜像。
"y"：表示将精灵绕 y 轴方向进行镜像翻转，即水平镜像。

**sprite.delete()**
删除精灵对象。

移动精灵

**sprite.set_align(align_point = "center")**
设置精灵的锚点，锚点决定了精灵移动、旋转时的中心点。参数：

• align_point str 表示信息显示的位置，有效值为：

"top_mid"，此时锚点在精灵顶部居中。
"top_left"，此时锚点在精灵顶部左侧。
"top_right"，此时锚点在精灵顶部右侧。
"center"，此时锚点在精灵居中。
"mid_left"，此时锚点在精灵居中靠左。
"mid_right"，此时锚点在精灵居中靠右。
"bottom_mid"，此时锚点在精灵底部居中。
"bottom_left"，此时锚点在精灵底部靠左。
"bottom_right"，此时锚点在精灵底部靠右。

**sprite.move_x(step)**
精灵朝 x 轴方向移动指定像素。参数：

• step int，表示精灵移动的像素大小。

**sprite.move_y(step)**
精灵朝 y 轴方向移动指定像素。参数：

• step int，表示精灵移动的像素大小。

**sprite.move_to(x, y)**
精灵移动到指定的坐标位置。参数：

• x int，表示设置的精灵的 x 坐标。
• y int，表示设置的精灵的 y 坐标。

**sprite.move_random()**
精灵移动到随机位置。该 API 会使精灵的 x、y 坐标变为 0~127 中的某个数。

旋转精灵

**sprite.rotate(angle)**
精灵顺时针旋转指定角度。参数：

• angle int。

**sprite.rotate_to(angle = 90)**
精灵旋转到指定的角度，参数：

• angle int，默认值为 90°。

以声音图标作为精灵为例，朝向角度的效果如下图：

缩放精灵

**sprite.set_size(size = 100)**
设置精灵的等比放大百分比，参数：

• size int，默认值为 100%。

**sprite.set_scale(x_size = 100, y_size = 100)**
设置精灵长宽的放大百分比，参数：

• x_size int，默认值为 100%，表示精灵 x 轴的放大尺寸。
• y_size int，默认值为 100%，表示精灵 y 轴的放大尺寸。

该 API 本版本不对外。

颜色特效

**sprite.set_color(**``**r, g, b)**
设置精灵颜色，精灵的所有非空像素点将会被渲染为指定的颜色。参数：

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

**sprite.close_color()**
取消颜色设置，精灵的颜色效果会恢复为默认状态，即 draw_XXX() 函数定义的样子。

图层及显示控制

**sprite.show()**
显示精灵（精灵默认处于显示状态）。

**sprite.hide()**
隐藏精灵。

**sprite.z_up(step)**
将精灵向上移动指定层数。参数：
step int，表示精灵向上移动的图层数。

**sprite.z_down(step)**
将精灵向下移动指定层数。参数：
step int，表示精灵向下移动的图层数。

**sprite.z_max()**
将精灵移到最上面。

**sprite.z_min()**
将精灵移到最下面。

检测

**screen.get_color(x, y)**
获得屏幕显示画面特定坐标上的显示颜色。参数：

• x int，有效范围 0~127，表示检测的像素点的 x 坐标。
• y int，有效范围 0~127，表示检测的像素点的 y 坐标。

返回 int，可能的范围为 0x000000 到 0xFFFFFF。代表对应 RGB 颜色的 16 进制表示。

**sprite.is_touch(other_sprite)**
判断精灵是否与其他精灵或屏幕边沿发生了碰撞———精灵间的非空像素点发生了接壤认为他们是碰撞的；精灵的非空像素点的坐标的x、y值大于等于128时认为其与屏幕边缘发生了碰撞.参数：
other_sprite，sprite对象或 str。
当 other_sprite 为 sprite 时，可能的范围为任意一个精灵对象。表示检测精灵间是否发生了碰撞。
当 other_sprite 为 str 时，有效值为 "edge"，表示检测精灵是否与屏幕边缘发生了碰撞。
返回 bool。

**sprite.get_align()**
获得精灵的锚点位置。
返回 str，可能值为：

• "top_mid"，此时锚点在精灵顶部居中。
• "top_left"，此时锚点在精灵顶部左侧。
• "top_right"，此时锚点在精灵顶部右侧。
• "center"，此时锚点在精灵居中。
• "mid_left"，此时锚点在精灵居中靠左。
• "mid_right"，此时锚点在精灵居中靠右。
• "bottom_mid"，此时锚点在精灵底部居中。
• "bottom_left"，此时锚点在精灵底部靠左。
• "bottom_right"，此时锚点在精灵底部靠右。

**sprite.get_x()**
获得精灵的 x 轴坐标。
返回 int。

**sprite.get_y()**
获得精灵的 y 轴坐标。
返回 int。

**sprite.get_rotation()**
获得精灵的面向角度。
返回 int。，有效范围-180~180°

**sprite.get_xsize()**
获得精灵的 x 轴放大尺寸。
返回 int。

**sprite.get_ysize()**
获得精灵的 y 轴放大尺寸。
返回 int。

渲染

渲染是精灵极其重要的机制，精灵需要需要通过渲染才能使得设置的属性（坐标、大小、角度等）变更生效。

**cyberpi.screen.enable_autorender()**
开启显示屏默认渲染，帧数为 10 帧。

**cyberpi.screen.disable_autorender()**
关闭显示屏默认渲染，帧数为 10 帧。

**cyberpi.screen.render()**
手动渲染。

涂鸦（显示屏）

喷枪有如下初始状态

**cyberpi.sketch.clear()**
清空涂鸦。

**cyberpi.sketch.start()**
笔头落下，开始涂鸦。

**cyberpi.sketch.end()**
笔头抬起，结束涂鸦。

**cyberpi.sketch.set_speed(speed)**
设置画笔的移动速度。参数：

• speed int ，有效范围是 1~10，表示画笔移动的速度。

**cyberpi.sketch.set_color(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.sketch.set_size(size)**
设置笔的粗细，笔触形状为圆形。参数：

• size int ，表示喷枪的粗细。

**cyberpi.sketch.cw(angle)**
笔头原地顺时针转动。参数：

• angle int ，表示旋转的角度大小。

**cyberpi.sketch.ccw(angle)**
笔头原地逆时针转动。参数：

• angle int ，表示旋转的角度大小。

**cyberpi.sketch.set_angle(angle)**
笔头设置面向角度。

**cyberpi.sketch.move(step)**
笔头朝面向方向移动指定像素距离。参数：

• step int，表示精灵朝面向方向移动的像素大小。

**cyberpi.sketch.move_x(step)**
笔头向x轴方向（右）移动指定像素距离。参数：

• step int，表示精灵朝 x 轴移动的像素大小。

**cyberpi.sketch.move_y(step)**
笔头向 y 轴方向（下）移动指定像素距离。参数：

• step int，表示精灵朝 y 轴移动的像素大小。

**cyberpi.sketch.move_to(x, y)**
笔头移动到指定坐标位置。参数：

• x int，表示设置的笔头的 x 坐标。
• y int，表示设置的笔头的 y 坐标。

**cyberpi.sketch.circle(r, angle)**
笔头以指定半径（圆心位于笔头方向顺时针 90°指向的方向上）划过指定角度。参数：

• r int，表示设置的笔头的滑动半径。
• y int，表示设置的笔头的滑动弧度。

**cyberpi.sketch.get_x()**
获得笔头的 x 坐标。
返回 int。

**cyberpi.sketch.get_y()**
获得笔头的 y 坐标。
返回 int。

**cyberpi.sketch.get_size()**
获得笔头的粗细。
返回 int。

**cyberpi.sketch.get_angle()**
获得笔头的面向角度。
返回 int。

**cyberpi.sketch.is_start()**
判断笔头的是否落下。
返回 bool。

**sprite_sketch = sprite.draw_sketch()**
使用当前涂鸦做为精灵。精灵会获取当前涂鸦的形状。另外，由于精灵的初始位置 坐标是 64，64，涂鸦被设置为精灵后会处于屏幕的中心。

涂鸦示例程序（仅支持上传模式）：

import cyberpi
import random
def draw():
    cyberpi.sketch.move_to(0, 0)
    cyberpi.sketch.start()
    cyberpi.sketch.set_size(1)
    cyberpi.sketch.set_speed(16)
    x = 0
    y = 0
    for k in range(0, 9, 1):
        r = random.randint(1, 255)
        g = random.randint(1, 255)
        b = random.randint(1, 255)
        cyberpi.led.on(r, g, b)
        cyberpi.sketch.set_color(r, g, b)
        for i in range(1, 5, 1):
            for j in range(0, 8 - k, 1):
                cyberpi.sketch.move(16)
            cyberpi.sketch.cw(90)
        x += 8
        y += 8
        cyberpi.sketch.end()
        cyberpi.sketch.move_to(x, y)
        cyberpi.sketch.start()
    cyberpi.sketch.end()
    cyberpi.led.off()
while True:
    if cyberpi.controller.is_press('a'):
        draw()
    if cyberpi.controller.is_press('b'):
        cyberpi.sketch.clear()

MESH 局域网【未实装】

在光环板上，我们使用了 MESH 机制建立光环板间的无线局域网通信；而在童芯派上，我们使用基于 ESP32-NOW 的技术来实现无线局域网通信，你理解为这是两种不同的通信协议。
在应用上，他们的主要的区分点为：

所以，童芯派局域网机制的使用门槛更低（它通过了一种近似红外通信的体验），但光环板的局域网机制性能更好。
因此，我们决定将 MESH 组网的功能以积木扩展的形式加入童芯派，以实现光环板和童芯派的便捷通信，并给到用户更好性能局域网通信的选择。以下是相关的 API：

**cyberpi.mesh.set(name = "mesh1")**
组建一个局域网，参数：

• name 字符串，默认值为 “mesh1”，表示要建立的 MESH 局域网名称。

**cyberpi.mesh.join(name = "mesh1")**
加入一个局域网，参数：

• name 字符串，默认值为 “mesh1”，表示要加入的 MESH 局域网名称。

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

• message 字符串类型，广播消息的名称。
• val 局域网广播消息的值。

**cyberpi.mesh_broadcast.get(message)**
获取广播信息的附带值，参数：

• message 字符串数据，广播的信息名称。

返回局域网广播消息的值。

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

• message 字符串类型，mesh 局域网广播的消息名称。