Windows Docker LFS esptool ESPlorer Workflow Cheat Sheet - nodemcu/nodemcu-firmware GitHub Wiki

Build LFS Enabled NodeMCU Firmware in Windows Using Docker NodeMCU Build

The procedure is broken down into 3 major segments:

1. First-Time Environment Setup [one-time-only]
2. Build & Upload the NodeMCU LFS Enabled Firmware to the ESP8266 [one-time-only unless you want/need to upgrade NodeMCU firmware]
3. Develop Your Lua Applications and Upload them to the ESP8266's NodeMCU LFS Region (a.k.a. App Dev Loop) [multiple times]

• https://nodemcu.readthedocs.io/en/master/en/getting-started/
• https://hub.docker.com/r/marcelstoer/nodemcu-build/
• https://github.com/marcelstoer/docker-nodemcu-build/

Notes: Replace everything in curly brackets {} with your own values, for example:

• {YourAcct} = Your Windows account folder
• {PWD} = "Present Working Directory"

First-Time Environment Setup - Start

First, install all the tools you need...

Install Docker for Windows

• https://docs.docker.com/get-started/
• https://docs.docker.com/engine/reference/commandline/run/
• https://docs.docker.com/docker-for-windows/install/

Reboot the computer Add the C:\Users{YourAcct} directory to the Docker File Share

• right-mouse on the Docker "whale" tray bar icon
• select "Settings", Select "Resources", Select "File Sharing"
• add "C:\Users{YourAcct}"}

Install Git for Windows

• https://git-scm.com/

Install Python

• https://www.python.org/downloads/windows/

Install / Upgrade PIP for Python27 install only

cd C:\python27
python -m pip install --upgrade pip

Install esptool {for Python27 install only}

-  cd C:\python27\scripts
-  pip install esptool

Upgrade esptool (maintenance task) {for Python27 install only}

cd C:\python27\scripts
pip install --upgrade wheel
pip install -–upgrade esptool
python -m pip install --upgrade pyserial
python -m pip install --upgrade pyaes
python -m pip install --upgrade ecdsa

Install Java (prereq for ESPlorer)

• https://www.java.com/ES/download/

Download ESPlorer

• https://esp8266.ru/esplorer/
• http://esp8266.ru/esplorer-latest/?f=ESPlorer.zip

Install putty (optional) (putty can be used in place of ESPlorer in some use cases)

• https://www.putty.org/
• https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html

Install NodeMCU-Tool (optional) (NodeMCU-Tool can be used in place of esptool in some use cases)

• https://github.com/andidittrich/NodeMCU-Tool
• https://github.com/AndiDittrich/NodeMCU-Tool/archive/master.zip

Install USB-to-Serial drivers required by your ESP8266 module (not needed for Win10) Ex: The CP210x USB to UART Bridge Virtual COM Port (VCP) drivers

• https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers

Open a Command Prompt window (recommend opening "As Administrator")

[/Start/Run/cmd | OK]

Create a new directory for your NodeMCU project anywhere under your "C:\Users{user_name}" directory Note: This will be the base directory for your NodeMCU project

Consider using Google Drive with the Google Backup & Sync app:

• https://www.google.com/drive/
• https://www.google.com/intl/en-GB_ALL/drive/download/backup-and-sync/

cd "C:\Users\{YourAcct}\Google Drive\Users\{YourAcct}\Project1\Build"

Create a new directory for your NodeMCU project's user applications source code (this is where you will be developing your Lua application module code)

cd "C:\Users\{YourAcct}\Google Drive\Users\{YourAcct}\Project1\Build\user-apps_source"

Create a new directory for your NodeMCU project's "Load into LFS region" user applications (this is where you will copy your Lua application modules when they are ready to be loaded into the NodeMCU firmware's LFS region)

cd "C:\Users\{YourAcct}\Google Drive\Users\{YourAcct}\Project1\Build\user-apps"

NodeMCU Firmware Build

Open a Command Prompt window (recommend opening "As Administrator")

• [/Start/Run/cmd | OK]

Change the Present Working Directory {PWD} to the base project directory

cd "C:\Users\{YourAcct}\Google Drive\Users\{YourAcct}\Project1\Build"

Clone the GitHub NodeMCU Firmware Master Repository

• https://hub.docker.com/r/marcelstoer/nodemcu-build/ If you want to user the ESP8266 Master Branch:

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

If you want to user the ESP8266 Dev Branch:

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

Docker NodeMCU Maintenance Tasks (perform these only after initial pass through this segment of the procedure)

Update the nodemcu-build docker image from time to time to pull in the latest bug fixes (if any)

docker pull marcelstoer/nodemcu-build

To list all docker images in repository (only if you care...)

docker image ls --all

To remove unused / old docker images (keep your Docker environment lean & mean...)

docker image prune

Edit {PWD}\nodemcu-firmware\app\include\ configuration files as required for your project For LFS enablement (at a minimum)...

Uncomment & modify as needed: user_config.h -->

#define LUA_FLASH_STORE 0x10000

Uncomment & modify as needed: user_config.h -->

#define LUA_INIT_STRING "pcall(function() node.flashindex'project1_init'() end)

(your user application code entry point will be "project1_init.lua")

Build the NodeMCU Firmware image file Note: Firmware image bin file will be located in {pwd}/nodemcu-firmware/bin directory Older versions of Windows and/or Docker required the use of "//C/" in the path name. At some point in 05/2020 that changed to "c:/"

docker run --rm -it -e "IMAGE_NAME=project1" -v "//c/Users/{YourAcct}/Google Drive/Users/{youracct}/project1/Build/nodemcu-firmware":/opt/nodemcu-firmware marcelstoer/nodemcu-build build
docker run --rm -it -e "IMAGE_NAME=project1" -v "c:/Users/{YourAcct}/Google Drive/Users/{youracct}/project1/Build/nodemcu-firmware":/opt/nodemcu-firmware marcelstoer/nodemcu-build build

Connect the ESP8266 to a USB port on your computer {COM3} is an example USB port - Replace it with the COMx port assigned to the ESP8266 USB port

Open a Command Prompt window (recommend opening "As Administrator")

[/Start/Run/cmd | OK]

Erase the ESP8266 flash (start with a clean slate)

esptool.py --port {COM3} --baud 460800 erase_flash

Upload the NodeMCU firmware to the ESP8266

esptool.py --port {COM3} --baud 460800 write_flash --flash_mode dio 0x0 ".\nodemcu-firmware\bin\nodemcu_float_project1.bin"

Fire-up ESPlorer and open the ESP8266 COMx port

Format the ESP8266 SPIFFS file system (start with a clean slate)

In ESPlorer...

SEND --> file.format()

Close the ESP8266 port and Exit ESPlorer

Application Development Cycle Loop

You will loop through this procedure segment as you develop your ESP8266 user applications...

Create/Develop your Lua application source code in the {PWD}\user-apps_source directory Once your Lua application is complete, copy your Lua application .lua files to the {PWD}\user-apps directory

At a minimum, consider including the following application modules in the {PWD}\user-apps directory:

project1_init.lua -- Your application's initialization module project1_main.lua -- Your application's main module (called by project1_init.lua) project1_preload.lua -- Your application's ROM String Table LFS Preload dummy module

• (see https://nodemcu.readthedocs.io/en/latest/lfs/#moving-common-string-constants-into-lfs for details)

Change the Present Working Directory {PWD} to the base project directory

cd "C:\Users\{YourAcct}\Google Drive\Users\{YourAcct}\Project1\Build"

Compile your application source code into a LFS image file Note: The compiled LFS image file will be located in {pwd}/user-apps directory

The example LFS image file is called "LFS_float_project1.img"

docker run --rm -it -e "IMAGE_NAME=project1" -v "//c/Users/{YourAcct}/Google Drive/Users/{youracct}/project1/Build/nodemcu-firmware":/opt/nodemcu-firmware -v "//c/Users/{YourAcct}/google Drive/Users/{youracct}/project1/Build/user-apps":/opt/lua marcelstoer/nodemcu-build lfs-image
docker run --rm -it -e "IMAGE_NAME=project1" -v "c:/Users/{YourAcct}/Google Drive/Users/{youracct}/project1/Build/nodemcu-firmware":/opt/nodemcu-firmware -v "c:/Users/{YourAcct}/Google Drive/Users/{youracct}/project1/Build/user-apps":/opt/lua marcelstoer/nodemcu-build lfs-image

Fire-up ESPlorer and open the ESP8266 COMx port

In ESPlorer...

• Navigate to the {PWD}\user-apps directory = Click "Upload" button
• Navigate to then Select the "{PWD}\user-apps\LFS_float_project1.img" file
• SEND --> node.flashreload("LFS_float_project1.img")

If all goes well, LFS will load your application image, restart the ESP8266 and execute your application.

Alternitive Upload/Reload Method: Use NodeMCU-Tool (optional)

• Upload the newly created LFS image file to the ESP8266

nodemcu-tool --port={COM3} upload ".\user-apps\LFS_float_project1.img"

• Start NodeMCU-Tool Terminal Mode

nodemcu-tool --port={COM3} terminal

Reload the new LFS flash image file - Type the following in the NodeMCU-Tool terminal window:

node.flashreload("LFS_float_project1.img")
[CTRL-C]