KeenPlus
API 文档横幅

📋 设备 API 文档

KeenPlus 智能设备开放接口，供 MicroPython 应用和第三方开发者使用。

全部🖥 显示 UI🎵 音频🌐 网络/云端💾 存储📤 文件传输⚙️ App引擎🔧 系统
文档总览：10 个接口条目

🧭 嵌入式开发指南

先看这组本地文档，再结合下方 API 条目开发。

00. 开发总览

平台结构、能力边界与开发路线

01. 环境准备

账号、权限、依赖、调试建议

02. 应用目录规范

项目结构、命名规范、发布清单

03. 设备 API 速查

常用接口目录与调用注意事项

04. AI 协作开发指南

给 AI 的上下文模板与提示词模板

05. 性能评估与芯片选型

S3 / P4 / BK7258 基准对比方法

06. 提审与上架流程

从开发到审核通过的完整流程

🎵音频(3)

audio_engine_play_filesince v1.0.0
audio

从 SPIFFS 路径播放音频文件，支持 MP3/FLAC/WAV/APE/AAC 格式。

参数

  • path(const char*)SPIFFS 文件路径，如 /spiffs/music/song.mp3

返回值

esp_err_tESP_OK 成功，ESP_FAIL 文件不存在

C 示例
esp_err_t err = audio_engine_play_file("/spiffs/music/song.mp3");
MicroPython 示例
import esp_audio
esp_audio.play("/spiffs/music/song.mp3")
audio_engine_set_volumesince v1.0.0
audio

设置播放音量，范围 0-100。

参数

  • vol(uint8_t)音量 0-100

返回值

void无返回值

C 示例
audio_engine_set_volume(75);
MicroPython 示例
esp_audio.set_volume(75)
audio_engine_pause_resumesince v1.0.0
audio

暂停或恢复当前正在播放的音频。

返回值

esp_err_tESP_OK

C 示例
audio_engine_pause_resume();
MicroPython 示例
esp_audio.toggle_pause()

🖥显示 UI(2)

lv_label_createsince v1.0.0
display

在 LVGL 屏幕上创建文本标签控件。

参数

  • parent(lv_obj_t*)父对象，传 lv_scr_act() 表示当前屏幕

返回值

lv_obj_t*标签对象指针

C 示例
lv_obj_t *lbl = lv_label_create(lv_scr_act());
lv_label_set_text(lbl, "Hello ESP-S3");
MicroPython 示例
import lvgl as lv
lbl = lv.label(lv.scr_act())
lbl.set_text("Hello ESP-S3")
ui_navigate_tosince v1.0.0
display

切换到指定 App 界面。

参数

  • app(app_id_t)APP_MUSIC / APP_EBOOK / APP_CLOCK 等

返回值

void

C 示例
ui_navigate_to(APP_MUSIC);
MicroPython 示例
import ui
ui.navigate(ui.APP_MUSIC)

🌐网络/云端(2)

cloud_http_getsince v1.0.0
network

发起 HTTP GET 请求，返回响应体。

参数

  • url(const char*)请求 URL
  • resp(cloud_http_response_t*)输出：响应结构体，用后调用 free

返回值

esp_err_tESP_OK 成功

C 示例
cloud_http_response_t resp = {0};
cloud_http_get("http://example.com/api/data", &resp);
printf("%s", resp.body);
cloud_http_response_free(&resp);
MicroPython 示例
import cloud
data = cloud.http_get("http://example.com/api/data")
print(data)
cloud_tts_requestsince v1.0.0
network

调用云端 TTS 服务将文本转为 MP3 音频数据。

参数

  • text(const char*)待合成文本，UTF-8
  • voice(const char*)声音名称，如 zh-CN-XiaoxiaoNeural
  • mp3_out(uint8_t**)输出：MP3 数据指针，调用方 free
  • len_out(size_t*)输出：MP3 数据长度

返回值

esp_err_t

C 示例
uint8_t *mp3; size_t len;
cloud_tts_request("你好世界", "zh-CN-XiaoxiaoNeural", &mp3, &len);
audio_player_play_buffer(mp3, len);
free(mp3);
MicroPython 示例
import cloud
mp3 = cloud.tts("你好世界", voice="zh-CN-XiaoxiaoNeural")
esp_audio.play_buffer(mp3)

💾存储(1)

spiffs_read_filesince v1.0.0
storage

从 SPIFFS 读取文件内容到缓冲区。

参数

  • path(const char*)文件路径
  • buf(char*)输出缓冲区
  • size(size_t)缓冲区大小

返回值

int读取字节数，-1 表示错误

C 示例
char buf[1024];
FILE *f = fopen("/spiffs/data/config.txt", "r");
fread(buf, 1, sizeof(buf), f);
fclose(f);
MicroPython 示例
with open("/spiffs/data/config.txt") as f:
    content = f.read()
print(content)

🔧系统(1)

esp_app_get_descriptionsince v1.0.0
system

获取固件版本、编译时间等设备信息。

返回值

const esp_app_desc_t*固件描述结构体

C 示例
const esp_app_desc_t *d = esp_app_get_description();
printf("Version: %s", d->version);
MicroPython 示例
import system
info = system.app_info()
print(info["version"])

📤文件传输(1)

transfer_service_startsince v1.0.0
transfer

启动文件传输服务（BLE 或 Wi-Fi 直连模式）。

参数

  • mode(transfer_mode_t)TRANSFER_MODE_BLE 或 TRANSFER_MODE_WIFI_DIRECT

返回值

esp_err_t

C 示例
transfer_service_start(TRANSFER_MODE_WIFI_DIRECT);
MicroPython 示例
import transfer
transfer.start(mode="wifi")

💡 用 AI 加速开发

选择接口文档，让 AI 自动生成应用代码。

打开 AI Studio →