marcelstoer/nodemcu-build

Docker NodeMCU 构建与 LFS 镜像

在您的平台上本地克隆并编辑https://github.com/nodemcu/nodemcu-firmware%EF%BC%8C%E6%AD%A4%E9%95%9C%E5%83%8F%E5%B0%86%E6%8E%A5%E6%89%8B%E5%90%8E%E7%BB%AD%E6%B5%81%E7%A8%8B%EF%BC%8C%E5%B0%86%E6%82%A8%E7%9A%84%E4%BB%A3%E7%A0%81%E8%BD%AC%E6%8D%A2%E4%B8%BA%E5%8F%AF%E5%88%B7%E5%86%99%E5%88%B0ESP8266%E6%88%96ESP32%E7%9A%84%E4%BA%8C%E8%BF%9B%E5%88%B6%E6%96%87%E4%BB%B6%E3%80%82%E5%AE%83%E8%BF%98%E5%8F%AF%E4%BB%A5%E4%BB%8ELua%E6%BA%90%E4%BB%A3%E7%A0%81%E5%88%9B%E5%BB%BALFS%E9%95%9C%E5%83%8F%E3%80%82

目标用户

NodeMCU开发者主要分为以下三类：

• NodeMCU"应用开发者"

  他们只需要现成的固件。我为他们创建了一个带有友好UI和配置选项的云构建服务。但如果他们使用LFS，可能需要构建LFS镜像作为Terry Ellison在线服务的替代方案。此时此镜像非常适合他们！

• 偶尔的NodeMCU固件修改者

  他们不需要完全控制整个工具链，也不想设置带有构建环境的Linux虚拟机。此镜像正是为他们准备的！

• NodeMCU固件开发者

  他们向GitHub项目提交代码或贡献，需要自己的完整工具链构建环境。他们仍可能发现此Docker镜像有用。

⚠️ 定期更新

如果您之前已拉取过此Docker镜像，应定期更新以获取最新的错误修复：

docker pull marcelstoer/nodemcu-build

使用方法

安装Docker

按照[***]

克隆NodeMCU固件仓库

Docker运行在VirtualBox虚拟机中，默认只共享底层客户机操作系统的用户目录。在Windows上是c:/Users/<user>，在Mac上是/Users/<user>。因此，您需要将https://github.com/nodemcu/nodemcu-firmware%E4%BB%93%E5%BA%93%E5%85%8B%E9%9A%86%E5%88%B0*%E7%94%A8%E6%88%B7%E7%9B%AE%E5%BD%95*%E4%B8%AD%E3%80%82%E5%A6%82%E6%9E%9C%E8%A6%81%E6%94%BE%E5%9C%A8%E7%94%A8%E6%88%B7%E7%9B%AE%E5%BD%95%E5%A4%96%EF%BC%8C%E9%9C%80%E7%9B%B8%E5%BA%94%E8%B0%83%E6%95%B4VirtualBox%E8%99%9A%E6%8B%9F%E6%9C%BA%E5%85%B1%E4%BA%AB%E8%AE%BE%E7%BD%AE%E3%80%82

git clone --recurse-submodules https://github.com/nodemcu/nodemcu-firmware.git

对于ESP32，需切换到dev-esp32分支并更新子模块：

git checkout dev-esp32
git submodule update --recursive

为ESP8266构建

配置模块和特性

注意 构建脚本会将您在下方设置的选项信息添加到NodeMCU启动消息中（应用启动时输出到控制台）。

要配置构建到固件中的模块，请编辑app/include/user_modules.h。还可以在app/include/user_config.h中开启SSL或LFS。同一文件中的#define LUA_NUMBER_INTEGRAL可控制构建的固件是否支持浮点数。其他选项和详情请参见NodeMCU构建选项文档。

版本信息和构建日期会自动正确设置，除非您修改app/include/user_version.h中的参数。

构建固件

启动Docker并切换到NodeMCU固件目录（在Docker控制台中）。要构建固件，请运行：

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware marcelstoer/nodemcu-build build

根据系统性能，编译需1-3分钟完成。首次运行时会更长，因为Docker需要下载镜像并创建容器。

输出

所有输出将创建在NodeMCU仓库根目录的bin子文件夹中，包括：

• nodemcu_${BUILD_TYPE}_${IMAGE_NAME}.bin：可刷写的组合固件镜像。BUILD_TYPE为integer或float。IMAGE_NAME详见下文选项章节。
  • 类似但以.map结尾的文件：包含函数相对偏移的映射文件。
• 0x00000.bin：仅包含固件。
• 0x10000.bin：包含SPIFFS。

刷写固件

有多种工具可将固件刷写到ESP8266。

为ESP8266创建LFS镜像

启动Docker并切换到NodeMCU固件目录（在Docker控制台中）。要创建LFS镜像，请运行：

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware -v {Lua源文件夹路径}:/opt/lua marcelstoer/nodemcu-build lfs-image

这将编译并存储指定文件夹（包括子文件夹）中的所有Lua文件。

要仅添加特定文件，可准备一个包含待添加文件的列表文件，并将其作为参数：

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware -v {Lua源文件夹路径}:/opt/lua marcelstoer/nodemcu-build lfs-image final/files.lst

假设files.lst内容如下：

lib/*.lua    main.lua
../baseProject/*.lua

注意：使用Linux路径分隔符/而非Windows的\。这本质上是一个ls表达式，只要不包含空格和其他需要shell转义的字符。

假设{Lua源文件夹路径}（挂载为/opt/lua）中有以下文件：

baseProject/base.lua
baseProject/lib/baseLib.lua
final/files.lst
final/lib/lib1.lua
final/main.lua
main.lua

将添加以下文件：

baseProject/base.lua
final/lib/lib1.lua
final/main.lua

输出

根据构建的固件类型，将在Lua文件夹根目录创建一个或两个LFS镜像。

为ESP32构建

ESP32的NodeMCU基于https://github.com/espressif/esp-idf%EF%BC%88%E4%B9%90%E9%91%AB%E7%89%A9%E8%81%94%E7%BD%91%E5%BC%80%E5%8F%91%E6%A1%86%E6%9E%B6%EF%BC%89%E6%9E%84%E5%BB%BA%EF%BC%8C%E4%BD%BF%E7%94%A8%E8%8F%9C%E5%8D%95%E9%A9%B1%E5%8A%A8%E7%9A%84Kconfig%E7%94%A8%E6%88%B7%E7%95%8C%E9%9D%A2%E9%85%8D%E7%BD%AE%E6%89%80%E6%9C%89%E5%9B%BA%E4%BB%B6%E7%89%B9%E6%80%A7%E5%92%8C%E9%80%89%E9%A1%B9%E3%80%82%E5%9B%A0%E6%AD%A4%EF%BC%8C%E4%B8%BAESP32%E6%9E%84%E5%BB%BANodeMCU%E9%9C%80%E5%88%86%E4%B8%A4%E6%AD%A5%EF%BC%8C%E9%9C%80%E5%90%AF%E5%8A%A8Docker%E5%AE%B9%E5%99%A8%E4%B8%A4%E6%AC%A1%EF%BC%9A%E9%A6%96%E5%85%88%E5%90%AF%E5%8A%A8Kconfig%E9%80%89%E6%8B%A9%E6%89%80%E6%9C%89%E9%80%89%E9%A1%B9%E5%B9%B6%E5%86%99%E5%85%A5%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6%EF%BC%8C%E7%84%B6%E5%90%8E%E5%AE%9E%E9%99%85%E6%9E%84%E5%BB%BA%E5%9B%BA%E4%BB%B6%E3%80%82

注意 确保已按上文所述加载Git子模块。

配置模块和特性

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware marcelstoer/nodemcu-build configure-esp32

这将在固件目录中内部运行make menuconfig，并在同一目录生成sdkconfig文件。

构建固件

docker run --rm -ti -v `pwd`:/opt/nodemcu-firmware marcelstoer/nodemcu-build build

这与构建ESP8266的命令完全相同。它会分析可用文件以确定您检出的是ESP32还是ESP8266的NodeMCU，build命令是build-esp32的快捷方式。

如果在固件目录中未找到sdkconfig文件，构建过程将提前失败并显示有意义的错误消息。

输出

所有输出将创建在NodeMCU仓库根目录的bin子文件夹中，包括：

• nodemcu_${IMAGE_NAME}.bin：固件镜像。IMAGE_NAME详见下文选项章节。

选项

可通过docker run -e "<参数>=值" -e ...传递以下可选参数：

• BUILD_MAKE_TARGETS：自定义make目标的空格分隔列表，替代默认目标。
• IMAGE_NAME：设置后可使用固定名称保存输出文件（见上文各平台的"输出"部分）。若未设置或为空，将使用分支名称和时间戳。
• TZ：默认Docker容器使用UTC时区，因此默认镜像名称时间戳（见上文IMAGE_NAME选项）可能与主机系统时间不同（除非主机也为UTC）。可将TZ设置为任何有效时区名称，例如-e TZ=Asia/Kolkata。

INTEGER_ONLY和FLOAT_ONLY不再受支持。请按上文说明在app/include/user_config.h中配置LUA_NUMBER_INTEGRAL。

Windows用户注意事项

Windows上的Docker路径处理略有不同。需在命令中指定NodeMCU固件目录的完整路径：

docker run --rm -it -v c:/Users/<user>/<nodemcu-firmware>:/opt/nodemcu-firmware marcelstoer/nodemcu-build build

如果Windows路径包含空格，需像通常在Windows上那样用引号包裹：

docker run --rm -it -v "c:/Users/monster tune/<nodemcu-firmware>":/opt/nodemcu-firmware marcelstoer/nodemcu-build build

如果Docker容器在共享驱动器时（或启动时）挂起，请检查Windows服务“LanmanServer”是否运行。详见https://github.com/docker/for-win/issues/2196%E3%80%82

macOS用户注意事项

macOS上的Docker速度较慢。不过，通过优化卷挂载可显著减少I/O相关延迟。Docker for Mac 17.04引入了“delegated”标志，避免主机文件系统和容器文件系统始终保持完全同步。“delegated”会延迟将容器中的更改写回主机，以提高文件系统吞吐量。

因此，可将-v `pwd`:/opt/nodemcu-firmware替换为-v `pwd`:/opt/nodemcu-firmware:delegated（注意末尾的标志）。

更新NodeMCU

NodeMCU团队希望您定期将他们的最新更新拉取到克隆的仓库中并构建新固件。实现方法不止一种，因此本章有意简略带过。

重新开始

最简单的方法是放弃本地更改，更新固件，然后手动重新应用更改。如果您只修改了.h文件中的少量设置，这可能是合适的：

git reset --hard origin/<您使用的分支名称>
git submodule update --recursive

之后，您需手动重新编辑文件并再次运行Docker。

尝试保留更改

Git非常灵活强大。您采用的流程通常只是个人喜好问题。无论如何，除非您熟悉Git操作，否则最不想处理的就是命令行上的冲突解决（您和NodeMCU更新了同一文件=>可能冲突）。

一种尝试保留更改的方法是使用git stash。我说“尝试”是因为您仍可能遇到冲突。

git stash
git pull
git submodule update --recursive
git stash pop

支持

在StackOverflow上提问，并添加nodemcu和docker标签。

对于错误和改进建议，请在https://github.com/marcelstoer/docker-nodemcu-build/issues%E5%88%9B%E5%BB%BAissue%E3%80%82

致谢

感谢Paul Sokolovsky创建并维护https://github.com/pfalcon/esp-open-sdk%E3%80%82

特别感谢https://github.com/HHHartmann%E4%B8%BA%E6%AD%A4%E9%95%9C%E5%83%8F%E5%AE%9E%E7%8E%B0%E4%BA%86LFS%E6%94%AF%E6%8C%81%E5%B9%B6%E7%A7%BB%E9%99%A4%E4%BA%86%E8%AE%BE%E8%AE%A1%E4%B8%8D%E4%BD%B3%E7%9A%84%60INTEGER_ONLY%60/%60FLOAT_ONLY%60%E5%8F%82%E6%95%B0%E3%80%82

作者

[***]