Small python script for loading init.lua to ESP8266 nodemcu firmware
Switch branches/tags
Nothing to show
Clone or download


Join the chat at

Tool for loading Lua-based scripts from file to ESP8266 with nodemcu firmware


  • Allow easy uploading of any Lua-based script into the ESP8266 flash memory with NodeMcu firmware

Other projects

Another my project for NodeMCU: ESPlorer Integrated Development Environment (IDE) for ESP8266 developers


python 2.7, pyserial (as for esptool)




  • add TCP as possible transport to connect to the module using the supplied telnet server code
  • add --id/-i to query the ID of a module
  • add --delete to remove a given file from the module


  • fix download bug


  • added support for nested strings
  • added check to verify the UART buffer will not overflow.


  • put short versions of arguments back, see issue #2
  • flush serial port, fixes issue #1


  • switched to argparse from getopts, renamed some arguments
  • removed call-home from main.lua
  • added --verbose option to show debugging
  • added comments, fixed some grammar, updated README
  • chmod 755'd the script so its runnable on POSIX
  • checked with nodemcu 0.9.4 20141222


  • add new option -r, --restart : auto restart module, send command "node.restart()", after file load
  • add new option -d, --dofile : auto run, send command "dofile('file')", after file load
  • delete line "lua script loaded by luatool" for correct line number, lines number now equal lines number in original file
  • add 0.3 sec delay after write


  • now check proper answer from NodeMCU after send data. After send string we expect echo line, if not got it, then error message displayed "Error sending data to LuaMCU"
  • if lua interpreter error received, then error message displayed "ERROR from LUA interpreter lua:..."
  • add heap info and chip id to example file init.lua
  • some changes in example file main.lua


Typical use:

Edit file init.lua and set SSID and MasterPassword Then disconnect any terminal programm, and at command prompt type

./ --port /dev/ttyUSB0 --src init.lua --dest init.lua --verbose

Downloader start
Set timeout 3
Set interCharTimeout 3
Stage 1. Deleting old file from flash memory
->file.remove("init.lua") -> ok
->file.close() -> ok
--->>> All done <<<---


->"main.lua", "w") -> ok
->file.close() -> ok
->file.remove("main.lua") -> ok
->"main.lua", "w+") -> ok
->file.writeline([[tmr.alarm(0, 1000, 1, function()]]) -> ok
->file.writeline([[if wifi.sta.getip() == nil then]]) -> ok
->file.writeline([[print("Connecting to AP...")]]) -> ok
->file.writeline([[else]]) -> ok
->file.writeline([[print('IP: ',wifi.sta.getip())]]) -> ok
->file.writeline([[tmr.stop(0)]]) -> ok
->file.writeline([[end]]) -> ok
->file.writeline([[end)]]) -> ok
->file.flush() -> ok
->file.close() -> ok
--->>> All done <<<---

Connect you terminal program and send command (or you can use --restart option, when loading file init.lua)


after reboot:

lua script loaded by luatool 0.4
init.lua ver 1.2
set mode=STATION (mode=1)
MAC: 	18-FE-34-98-D4-B5
chip: 	10015925
heap: 	18464
set wifi
NodeMcu 0.9.2 build 20141125  powered by Lua 5.1.4

send command (or you can use --dofile option, when loading file main.lua)


connects to your AP and displays MCU's IP address

> dofile("main.lua")
> IP:


./ --port COM4 --src file.lua --dest main.lua --baud 9600
  • --port - COM1-COM128, default /dev/ttyUSB0
  • --baud - baud rate, default 9600
  • --src - source disk file, default main.lua
  • --dest - destination flash file, default main.lua

If use --dest option with parameter "init.lua" - autostart init.lua after boot. Be carefully about bugs in lua-script - may cause a boot loop. Use this option after full testing only.

Running without any parameters: load file "main.lua" via port /dev/ttyUSB0:9600 and place code into "main.lua" file into flash.


after loading file to flash you can connect any terminal programm to ESP8266 and type:


for executing you lua script

If you want load and autoexecute file main.lua, command dofile("main.lua"), you can use --dofile option

./ --dofile

Typically, place wifi.setmode, wifi.sta.config commands to init.lua file for connecting to you AP with low risk of boot loop, and other code place to main.lua for manually start and debug.

Alternative use:

This requires a nodemcu based module already configured to meet the following conditions:

  • the module is accessible via TCP/IP
  • the telnet server (file: telnet_srv.lua) is running

Now the option --ip IP[:PORT] enables you to specify an IP and optionally a port (if changed for the telnet server) that will be used to communicate with the module via TCP/IP.


./ --ip --src file.lua --dest test.lua --dofile 
  • --ip - the IP to connect to. Note that no Port is given, so 23 will be used (can be changed in telnet_srv.lua)
  • --src - source disk file, default main.lua
  • --dest - destination flash file, default main.lua
  • --dofile - run the just uploaded file