particle/buildpack-particle-firmware

Particle固件开发构建镜像文档

1. 镜像概述与主要用途

本镜像为Particle设备开发提供集成化的Docker环境，包含Particle设备代码编译所需的完整工具链和固件。主要用途是简化Particle设备固件的本地编译流程，帮助开发者快速搭建一致的编译环境，无需手动配置底层依赖。

2. 核心功能与特性

• 完整工具链集成：内置Particle设备开发所需的编译器、链接器等工具链，无需额外安装编译依赖。
• 固件支持：包含Particle官方固件，支持主流Particle设备的固件编译。
• 平台指定：通过环境变量可指定目标设备平台（PLATFORM_ID），适配不同型号的Particle设备。
• 版本可控：支持通过镜像标签选择不同版本的工具链和固件，确保开发环境一致性。
• 本地编译能力：提供本地化编译流程，无需依赖云端编译服务，提升开发效率。

3. 使用场景与适用范围

• Particle设备开发者：需在本地环境编译固件的个人或团队开发者。
• 离线开发环境：网络受限场景下，需脱离云端编译服务完成固件开发。
• CI/CD集成：可嵌入自动化构建流程（如Jenkins、GitHub Actions），实现固件编译的自动化。
• 多版本测试：通过切换镜像版本标签，快速测试不同工具链/固件版本的兼容性。

4. 使用方法与配置说明

4.1 Particle Dev图形界面方式

通过Particle Dev IDE（集成Local Compiler插件）使用本镜像：

1. 安装https://github.com/spark/particle-dev-local-compiler%E6%8F%92%E4%BB%B6%EF%BC%9B
2. 按照插件文档说明配置镜像路径及参数，即可通过图形界面触发本地编译。

4.2 命令行方式

通过Docker命令行直接运行镜像，完成项目编译：

4.2.1 前提条件

• 已安装Docker引擎；
• 本地项目目录包含Particle设备源代码（如.ino或.cpp文件）。

4.2.2 编译步骤

1. 定义本地环境变量：

   bash
   # 本地项目目录路径（需替换为实际路径）
   export PROJECT_DIR=~/path/to/your/project
   # 目标设备平台ID（参考Particle官方文档获取设备对应的ID，例如6对应Photon）
   export PLATFORM_ID=6
   # 镜像版本标签（例如0.4.5，可省略默认使用latest）
   export VERSION=0.4.5
   

2. 执行编译命令：

   bash
   docker run --rm \
     -v $PROJECT_DIR:/input \  # 挂载本地项目目录到容器/input（源代码输入）
     -v $PROJECT_DIR:/output \ # 挂载本地项目目录到容器/output（编译结果输出）
     -e PLATFORM_ID=$PLATFORM_ID \  # 传递平台ID到容器
     particle/buildpack-particle-firmware:$VERSION  # 指定镜像及版本
   

3. 查看结果：编译产物（如.bin固件文件）将输出到$PROJECT_DIR目录。

4.3 Docker Compose配置示例

创建docker-compose.yml文件，简化编译命令：

yaml
version: '3'
services:
  particle-compiler:
    image: particle/buildpack-particle-firmware:${VERSION:-latest}
    volumes:
      - ${PROJECT_DIR}:/input
      - ${PROJECT_DIR}:/output
    environment:
      - PLATFORM_ID=${PLATFORM_ID}

使用时执行：

bash
# 定义环境变量（同4.2.2步骤1）
export PROJECT_DIR=~/path/to/project PLATFORM_ID=6 VERSION=0.4.5
# 启动编译
docker-compose up

5. 配置参数详解

5.1 环境变量（容器内）

5.2 挂载卷

5.3 镜像版本标签

通过镜像标签指定工具链/固件版本，格式为particle/buildpack-particle-firmware:<VERSION>，例如：

• particle/buildpack-particle-firmware:0.4.5（指定0.4.5版本）
• particle/buildpack-particle-firmware:latest（默认最新版本）

版本兼容性说明：不同标签对应不同工具链和固件版本，需根据项目需求选择，具体版本信息可参考Particle官方发布记录。