fauria/nodemcu Docker镜像文档

镜像概述

fauria/nodemcu是一个用于构建和自定义NodeMcu固件的Docker镜像。NodeMcu是基于ESP8266 WiFi芯片的Lua开源固件，该镜像提供了便捷的固件编译环境，支持默认配置和自定义模块选择，编译后的固件可直接刷写到ESP8266设备。

核心功能与特性

• 提供完整的NodeMcu固件编译环境，无需本地配置编译依赖
• 支持默认模块配置编译，生成标准固件
• 允许通过环境变量自定义启用模块，灵活配置固件功能
• 暴露/firmware目录作为卷，方便持久化保存编译后的固件文件

安装方法

从Docker Hub拉取镜像：

bash
docker pull fauria/nodemcu

暴露卷

镜像暴露/firmware目录，用于存放编译后的固件文件。为保留固件文件，需将该目录挂载到主机卷，避免容器退出后文件丢失。

使用方法

默认配置编译固件

以下命令将使用默认设置编译固件，并将结果保存到当前目录的nodemcu-firmware文件夹：

bash
docker run --rm -v ${PWD}/nodemcu-firmware:/firmware fauria/nodemcu

编译完成后，nodemcu-firmware/nodemcu目录下将生成两个固件文件：0x00000.bin和0x***.bin，可直接用于ESP8266设备刷写。

自定义模块编译固件

NodeMcu模块通过app/include/user_modules.h文件配置。默认情况下，镜像使用该文件的默认设置。若需自定义模块，可通过环境变量ENABLE_+模块名（如ENABLE_WIFI、ENABLE_MQTT）指定启用的模块。

注意：启用单个模块会禁用所有未显式启用的模块，需通过环境变量明确指定所有需要的模块。

支持的模块列表（2.1.0版本）

默认启用的模块（加粗）：

• ADC
• ADS1115
• ADXL345
• AM2320
• APA102
• BIT
• BME280
• BMP085
• COAP
• CRON

• ---

• DHT
• DS18B20
• ENCODER
• ENDUSER_SETUP
• FILE
• GDBSTUB
• GPIO
• HDC1080
• HMC5883L
• HTTP
• HX711
• I2C
• L3G4200D
• MCP4725
• MDNS
• MQTT
• NET
• NODE
• OW
• PCM
• PERF
• PWM
• RC
• RFSWITCH
• ROTARY
• RTCFIFO
• RTCMEM
• RTCTIME
• SI7021
• SIGMA_DELTA
• SJSON
• SNTP
• SOMFY
• SPI
• STRUCT
• SWITEC
• TCS34725
• TLS
• TM1829
• TMR
• TSL2561
• U8G
• UART
• UCG
• WEBSOCKET
• WIFI
• WPS
• WS2801
• WS2812
• XPT2046

自定义模块示例

以下命令启用默认模块（效果等同于默认编译）：

bash
docker run --rm -v ${PWD}/nodemcu-firmware:/firmware \
  -e ENABLE_ADC=1 -e ENABLE_BIT=1 -e ENABLE_DHT=1 -e ENABLE_FILE=1 \
  -e ENABLE_GPIO=1 -e ENABLE_I2C=1 -e ENABLE_MQTT=1 -e ENABLE_NET=1 \
  -e ENABLE_NODE=1 -e ENABLE_OW=1 -e ENABLE_SPI=1 -e ENABLE_TLS=1 \
  -e ENABLE_TMR=1 -e ENABLE_UART=1 -e ENABLE_WIFI=1 \
  fauria/nodemcu

可将环境变量保存到文件（如modules.env），通过--env-file参数加载：

bash
docker run --rm -v ${PWD}/nodemcu-firmware:/firmware --env-file modules.env fauria/nodemcu

刷写固件

编译完成后，使用esptool工具将固件刷写到ESP8266设备。基本命令格式：

bash
esptool.py --port /path/to/serial_port write_flash 0x00000 /host/volume/0x00000.bin 0x*** /host/volume/0x***.bin

macOS示例（端口可能因系统而异）：

bash
esptool.py --port /dev/cu.SLAB_USBtoUART write_flash 0x00000 nodemcu-firmware/0x00000.bin 0x*** nodemcu-firmware/0x***.bin

注意：端口路径需根据操作系统和实际连接的串口设备调整。