GUI与扩展驱动库

本文引用的文件

gui.py
sdcard.py
bluebit.py
parrot.py
ds18x20.py
machine_servo.c
sdcard.rst（ESP32-S3 API文档）
sdcard.rst（mPython API文档）
parrot.rst（拓展板说明）
sdcard示例

产品概述

本章节面向GUI图形绘制、SD卡存储、Bluebit扩展板驱动、Parrot鹦鹉扩展板驱动、DS18X20温度传感器以及舵机控制等常用外设的API参考。这些模块覆盖显示、存储、传感、执行器与扩展板生态，适用于掌控板及ESP32-S3系列产品的教学与创客项目。

目标用户：K12创客教育、电子爱好者、嵌入式初学者
核心价值：提供统一易用的Python接口，屏蔽底层硬件细节，快速实现交互界面、数据记录、环境感知与机械控制
适用场景：数据可视化、设备状态展示、离线数据存储、传感器采集、电机与舵机控制、红外遥控、语音合成等

核心业务流程

图形绘制流程：初始化显示对象 → 调用绘图API（点线面、文本、图像、二维码）→ 刷新显示
SD卡流程：配置SPI与CS引脚 → 创建SDCard对象 → 挂载文件系统 → 使用标准文件操作读写
Bluebit流程：通过I2C/ADC/UART访问各类传感器与显示模块（温湿度、颜色、光线、数码管、矩阵屏、MIDI等）
Parrot流程：通过I2C控制电机速度/LED亮度、读取电池电压；通过IR类进行红外编码发送、学习与停止
DS18X20流程：单总线读取温度值
舵机流程：创建Servo对象 → 设置角度或脉宽 → 控制PWM输出

flowchart TD
A["应用层"] --> B["GUI绘制"]
A --> C["SD卡存储"]
A --> D["Bluebit扩展"]
A --> E["Parrot扩展"]
A --> F["DS18X20温度"]
A --> G["舵机控制"]
B --> H["framebuf/屏幕驱动"]
C --> I["SPI + FAT挂载"]
D --> J["I2C/ADC/UART"]
E --> K["I2C/IR"]
F --> L["单总线"]
G --> M["LEDC PWM"]

功能模块清单

GUI（图形绘制）
- UI：进度条、条形图、二维码生成
- multiScreen：多帧切换与指示符
- Clock：模拟时钟绘制
- Image：PBM/BMP图片解码为FrameBuffer
SD卡
- SDCard(spi, cs)：初始化并挂载FAT文件系统
Bluebit（扩展板驱动）
- 温度：Thermistor/LM35
- 按键：joyButton/joyButton1
- 温湿度：SHT20
- 颜色：Color（RGB/HSV）
- 光线：AmbientLight
- 超声波：Ultrasonic
- 数码管：SEGdisplay（TM1650/HT16K33）
- 点阵：Matrix（HT16K33）
- LCD1602：字符显示与光标控制
- MIDI：音量、音色、音符控制
- 其他：GPS、气压、PM2.5、心率、手势、太阳能等子模块集成
Parrot（鹦鹉扩展板）
- 电机：set_speed/get_speed
- LED灯：led_on/led_off
- 电池：get_battery_level
- 红外：IR_encode.encode_nec/encode_raw、IR.send/learn/get_learn_data/stop_send
DS18X20（温度传感器）
- 单总线温度读取（基于MicroPython onewire驱动）
舵机（Servo）
- Servo(pin, freq=50, angle=-1, min_us=750, max_us=2250, actuation_range=180)
- write_angle(angle)、write_us(us)、freq()、duty()、init()/deinit()

Section sources

gui.py:7-48
gui.py:49-79
gui.py:81-142
gui.py:144-224
sdcard.rst（ESP32-S3 API文档）:18-39
sdcard.rst（mPython API文档）:18-39
bluebit.py:47-123
bluebit.py:125-180
bluebit.py:181-212
bluebit.py:214-275
bluebit.py:277-323
bluebit.py:324-413
bluebit.py:422-499
bluebit.py:507-562
bluebit.py:573-751
bluebit.py:754-800
parrot.py:20-57
parrot.py:59-108
parrot.py:112-187
parrot.py:189-243
machine_servo.c:137-221
machine_servo.c:223-250
machine_servo.c:252-352

数据与状态

GUI
- UI进度条/条形图：以百分比作为输入，内部计算填充宽度/高度
- multiScreen：维护当前帧索引与帧列表，支持nextScreen切换
- Clock：维护中心坐标与半径，实时获取系统时间绘制指针
- Image：根据文件头识别格式（PBM/PBM或BMP），解析像素数据为FrameBuffer
SD卡
- 依赖SPI与CS引脚，需FAT/FAT32格式化；挂载后使用标准文件API
Bluebit
- 各传感器返回标准化数值（如温度℃、湿度%、光照lux、距离cm、磁场强度、航向角等）
- 显示模块（数码管/矩阵/LCD1602）维护缓冲区与显示状态
Parrot
- 电机速度缓冲：_speed_buf缓存最近一次速度，便于查询
- 红外：学习成功后返回布尔状态，可获取编码数据buff
DS18X20
- 单总线时序读取温度，异常时返回None（由封装决定）
舵机
- 维护通道、频率、脉宽范围、角度范围；写角度/脉宽时校验范围并更新占空比

classDiagram
class UI {
+ProgressBar(x,y,width,height,progress)
+stripBar(x,y,width,height,progress,dir,frame)
+qr_code(str,x,y,scale)
}
class multiScreen {
+drawScreen(index)
+nextScreen()
}
class Clock {
+settime()
+drawClock()
+clear()
}
class Image {
+load(path,invert)
}
UI --> "uses" FrameBuffer
multiScreen --> "uses" FrameBuffer
Clock --> "uses" FrameBuffer
Image --> "returns" FrameBuffer

Diagram sources

gui.py:7-48
gui.py:49-79
gui.py:81-142
gui.py:144-224

Section sources

gui.py:7-224
sdcard.rst（ESP32-S3 API文档）:18-39
sdcard.rst（mPython API文档）:18-39
bluebit.py:47-800
parrot.py:20-243
machine_servo.c:137-352

关键约束与边界

GUI
- 依赖framebuf与具体屏幕驱动；二维码生成使用adafruit_miniqr，注意内存占用
- 图像加载仅支持部分格式（PBM/PBM与1位BMP），超出将抛出类型错误
SD卡
- 必须正确连接SPI引脚与CS；卡需FAT/FAT32格式化；挂载路径需唯一
- 频繁写入可能影响寿命，建议批量写入与合理刷新策略
Bluebit
- 多数模块通过I2C通信，需确保地址与上电时序；部分模块需要延时等待转换完成
- ADC读取需注意衰减配置与分压电路参数
Parrot
- 电机速度与LED亮度有范围限制（速度-100~100，亮度0~100）
- 红外学习需在5秒内按住被学习按键；重复码发送需显式停止
DS18X20
- 单总线时序严格，需保证总线空闲与复位序列；多设备时需处理ROM地址
舵机
- 角度与脉宽需落在min_us~max_us范围内；频率变更受分辨率限制
- 通道资源有限，避免同时过多Servo实例导致冲突

sequenceDiagram
participant App as "应用"
participant SD as "SDCard"
participant SPI as "SPI"
participant FS as "文件系统"
App->>SD : 构造(SPI, CS)
SD->>SPI : 初始化SPI
App->>FS : os.mount(sd, "/sd")
FS-->>App : 挂载成功
App->>FS : open("/sd/test.txt","w")
FS-->>App : 文件句柄
App->>FS : write("Hello world!")
FS-->>App : 写入完成

Diagram sources

Section sources

gui.py:144-224
sdcard.rst（ESP32-S3 API文档）:18-39
sdcard.rst（mPython API文档）:18-39
bluebit.py:47-800
parrot.py:20-243
machine_servo.c:137-352

详细API参考

GUI（图形绘制）

UI
- ProgressBar(x, y, width, height, progress)：绘制圆角进度条
- stripBar(x, y, width, height, progress, dir=1, frame=1)：水平/垂直条形图
- qr_code(str, x, y, scale=2)：生成二维码并绘制到屏幕
multiScreen
- drawScreen(index)：绘制指定帧与底部指示符
- nextScreen()：切换到下一帧
Clock
- settime()：从系统时间更新时分秒
- drawClock()：绘制表盘与时分秒针
- clear()：清除时钟区域
Image
- load(path, invert=0)：加载PBM/PBM或1位BMP，返回FrameBuffer

flowchart TD
Start(["开始"]) --> LoadImg["Image.load(path)"]
LoadImg --> Format{"格式?"}
Format --> |PBM/PBM| DecodePBM["_pbm_decode()"]
Format --> |BMP| DecodeBMP["_bmp_decode()"]
DecodePBM --> FB["FrameBuffer"]
DecodeBMP --> FB
FB --> End(["结束"])

Diagram sources

gui.py:144-224

Section sources

gui.py:7-48
gui.py:49-79
gui.py:81-142
gui.py:144-224

SD卡（sdcard）

SDCard(spi, cs)：创建并初始化SD卡对象
挂载：os.mount(sd, "/sd")
文件操作：open/read/write/close等标准API

sequenceDiagram
participant App as "应用"
participant SPI as "SPI"
participant SD as "SDCard"
participant OS as "os"
App->>SPI : 配置引脚与波特率
App->>SD : SDCard(spi, cs)
App->>OS : mount(sd, "/sd")
OS-->>App : 挂载结果
App->>OS : open("/sd/test.txt","w")
OS-->>App : 文件句柄
App->>OS : write("Hello world!")
OS-->>App : 关闭

Diagram sources

Section sources

Bluebit（扩展板驱动）

温度
- Thermistor(pin, series_resistor, nominal_resistance, nominal_temperature, b_coefficient, high_side=True)：NTC温度测量
- LM35(pin)：线性温度传感器
按键
- joyButton(pin)：四键检测（A/B/C/D）
- joyButton1(pin)：五向按键（up/down/right/left/mid）
温湿度
- SHT20(i2c=i2c)：temperature()/humidity()
颜色
- Color(i2c=i2c)：getRGB()/getHSV()
光线
- AmbientLight(i2c=i2c)：getLight()
超声波
- Ultrasonic(i2c=i2c)：distance()
数码管
- SEGdisplay(i2c=i2c)：numbers(x)/Clear()
点阵
- Matrix(i2c=i2c)：pixel/fill/text/show
LCD1602
- Print/Cursor/Blink/display/move_left/move_right/createChar等
MIDI
- volume/instrument/note等属性与方法

Section sources

bluebit.py:47-123
bluebit.py:125-180
bluebit.py:181-212
bluebit.py:214-275
bluebit.py:277-323
bluebit.py:324-413
bluebit.py:422-499
bluebit.py:507-562
bluebit.py:573-751
bluebit.py:754-800

Parrot（鹦鹉扩展板）

电机
- set_speed(motor_no, speed)：设置M1/M2速度（-100~100）
- get_speed(motor_no)：查询当前速度
LED灯
- led_on(no, brightness=50)：点亮并设置亮度（0~100）
- led_off(no)：关闭
电池
- get_battery_level()：返回电量mV
红外
- IR_encode.encode_nec(user_code, command_code)：NEC编码
- IR_encode.encode_raw(carry_freq, len, repeat_pos, code, data)：自定义编码
- IR.send(buff, repeat_en=0)：发送编码数据
- IR.learn(wait=True)：学习红外信号
- IR.get_learn_data()：获取学习后的编码数据
- IR.stop_send()：停止重复码发送

sequenceDiagram
participant App as "应用"
participant Parrot as "parrot"
App->>Parrot : set_speed(MOTOR_1, 50)
Parrot->>Parrot : i2c.writeto(0x10, [motor_no, speed])
App->>Parrot : IR.send(buff)
Parrot->>Parrot : i2c.writeto(16, [0x04, repeat_en] + buff)
App->>Parrot : IR.learn(True)
Parrot->>Parrot : i2c.writeto(16, 0x06)
Parrot-->>App : True/False

Diagram sources

parrot.py:20-57
parrot.py:59-108
parrot.py:112-187
parrot.py:189-243

Section sources

parrot.rst（拓展板说明）:1-106
parrot.py:20-243

DS18X20（温度传感器）

基于onewire协议的单总线温度读取
典型用法：初始化单总线 → 搜索设备 → 读取温度
注意事项：总线时序严格，多设备需区分ROM地址

Section sources

ds18x20.py:1

舵机（Servo）

构造函数：Servo(pin, freq=50, angle=-1, min_us=750, max_us=2250, actuation_range=180)
方法：
- write_angle(angle)：设置角度（0~actuation_range）
- write_us(us)：设置脉宽（min_us~max_us）
- freq()：获取/设置PWM频率
- duty()：获取/设置占空比
- init()/deinit()：初始化/释放通道

flowchart TD
S["创建Servo(pin)"] --> Init["初始化LEDC定时器与通道"]
Init --> SetAngle{"是否设置angle?"}
SetAngle --> |是| CalcUS["计算us = min_us + angle*range/actuation_range"]
CalcUS --> SetDuty["设置占空比并更新"]
SetAngle --> |否| Wait["等待后续调用"]
SetDuty --> End["结束"]
Wait --> End

Diagram sources

machine_servo.c:137-221
machine_servo.c:316-352

Section sources

machine_servo.c:137-221
machine_servo.c:223-250
machine_servo.c:252-352

性能考虑

GUI
- 大量图形绘制时注意gc.collect()时机与内存碎片
- 二维码缩放比例越大，像素点越多，渲染耗时增加
SD卡
- 高频写入会加速磨损，建议合并写入与减少小文件频繁操作
- 挂载后文件IO遵循操作系统缓存策略，适时flush或close
Bluebit
- I2C传感器读取需预留转换时间（sleep_ms），避免读回无效数据
- ADC采样速率与精度需权衡，必要时降低采样频率
Parrot
- 电机频繁启停会产生冲击电流，建议平滑调速
- 红外学习过程阻塞，非阻塞模式需自行轮询状态
DS18X20
- 单次转换约750ms（取决于分辨率），避免阻塞主循环
舵机
- PWM频率过低可能导致抖动，过高则分辨率受限；推荐50Hz左右

[本节为通用指导，不直接分析具体文件]

故障排查

GUI
- 图片格式不支持：检查是否为PBM/PBM或1位BMP
- 二维码空白：确认字符串编码与scale参数
SD卡
- 挂载失败：检查SPI引脚与CS是否正确；确认卡已格式化
- 无法写入：检查权限与文件系统类型
Bluebit
- 传感器无响应：检查I2C地址与供电；增加延时
- ADC读数异常：检查衰减配置与外部电路
Parrot
- 电机不转：检查速度范围与电源能力；确认I2C通信正常
- 红外学习失败：确保在5秒内按住按键；重试或更换遥控器
DS18X20
- 读数为None：检查单总线接线与上拉电阻
舵机
- 角度无效：检查angle是否在actuation_range内；脉宽是否在min_us~max_us

Section sources

gui.py:144-224
sdcard.rst（ESP32-S3 API文档）:18-39
sdcard.rst（mPython API文档）:18-39
bluebit.py:47-800
parrot.py:20-243
machine_servo.c:137-352

结论

本参考覆盖了GUI绘制、SD卡存储、Bluebit与Parrot扩展板驱动、DS18X20温度传感器与舵机控制的核心API与使用要点。通过统一的Python接口，开发者可以快速构建交互界面、扩展存储、采集环境与运动控制等功能。实际项目中应关注时序、电源与资源分配，以获得稳定可靠的运行效果。

[本节为总结性内容，不直接分析具体文件]