sensebox/sensebox-sketches

senseBox Blockly草图容器化编译器

!https://github.com/sensebox/sensebox-sketches/actions/workflows/registry-build-publish.yaml/badge.svg

镜像概述

本镜像为基于容器的senseBox Blockly草图编译器，提供HTTP接口服务，支持编译senseBox系列开发板的Arduino草图代码，并提供编译结果下载功能。适用于需要动态编译senseBox设备固件的开发场景，可通过容器扩展实现负载均衡。

核心功能与特性

• 提供HTTP接口实现草图编译与下载
• 支持多种senseBox开发板：sensebox-mcu（新型MCU）、sensebox（基于Arduino Uno的旧款）、sensebox-esp32s2（ESP32S2架构MCU）
• 支持通过docker-compose横向扩展，实现负载均衡
• 轻量级容器化部署，易于集成到现有开发流程

使用方法

构建镜像

bash
docker build -t sensebox/sensebox-sketches .

运行容器

bash
docker run --rm -it -p 3000:3000 sensebox/sensebox-sketches

编译草图示例

使用curl调用编译接口：

bash
curl \
  --request POST \
  --header "Content-type: application/json" \
  --data '{"board":"sensebox-mcu", "sketch":"void setup() {\nSerial.begin(9600);\nSerial.println(\"Hello World\");\n}\nvoid loop() {}"}' \
  http://localhost:3000/compile

下载编译结果

使用编译返回的id下载草图：

bash
curl \
  --request GET \
  -O \
  -J \
  'http://localhost:3000/download?id={生成的ID}&board={sensebox|sensebox-mcu}'

HTTP接口说明

POST /compile

编译草图接口。

• 请求头：Content-type: application/json
• 请求体：JSON格式，包含以下字段：
  • board：开发板类型，可选值：sensebox-mcu、sensebox、sensebox-esp32s2
  • sketch：Arduino草图代码字符串（非空）

响应示例：

json
{
    "code": 201,
    "message": "Sketch successfully compiled and created!",
    "data": {
        "id": "77c1df527a874bd909b56bf1e3906604"
    }
}

响应中的id用于后续下载操作。

GET /download

下载编译结果接口。

• 参数：
  • id：编译接口返回的唯一标识符（必填）
  • board：开发板类型（必填，与编译时一致）
  • filename：下载文件名（可选，默认值：sketch）

请求示例：

http://localhost:3000/download?id=77c1df527a874bd909b56bf1e3906604&board=sensebox-mcu&filename=my_sketch

响应：

• 响应头：Content-type: application/octet-stream
• 响应头：Content-Disposition: attachment; filename:{filename}.bin|hex（根据开发板类型决定文件扩展名）
• 响应体：编译后的二进制固件文件

使用docker-compose扩展

通过docker-compose可实现多实例部署，实现负载均衡。仓库中包含docker-compose.yml文件，自动为所有容器分配compiler网络别名。

启动多实例

bash
docker-compose up -d --scale compiler=4

启动后，通过compiler别名访问服务，请求将自动分发到不同容器实例。

容器内编译示例

senseBox MCU草图编译

bash
arduino-builder -hardware /arduino-ide/hardware -hardware /root/.arduino15/packages -tools /arduino-ide/tools-builder -tools /root/.arduino15/packages -libraries /arduino-ide/libraries -fqbn=sensebox:samd:sb:power=on -build-cache /arduino-ide/build-cache -build-path /arduino-ide/builds /root/.arduino15/packages/sensebox/hardware/samd/1.0.4/libraries/senseBox/examples/Blink/Blink.ino

Arduino Uno编译

bash
arduino-builder -hardware /arduino-ide/hardware -hardware /root/.arduino15/packages -tools /arduino-ide/tools-builder -tools /root/.arduino15/packages -libraries /arduino-ide/libraries -fqbn=arduino:avr:uno -build-cache /arduino-ide/build-cache -build-path /arduino-ide/builds /root/.arduino15/packages/sensebox/hardware/samd/1.0.4/libraries/senseBox/examples/Blink/Blink.ino