README
NodeMCU-Tool
Upload/Download Lua files to your ESP8266/ESP32 module with NodeMCU firmware.
Simple. Command Line. Cross-Platform. File Management. NodeMCU.
$ npm install nodemcu-tool -g
Tool Summary
NodeMCU Tool allows you to
- Upload Lua files to your ESP8266/ESP32/NodeMCU module
- Upload any file-types (binary save)
- Bulk/Multi file uploads
- Download any file-type (binary save)
- Delete files
- Format the file system
- Simple Serial Terminal to interact with NodeMCU
- Show existing files on your module
- Precompile Lua files live on NodeMCU
- Minimize Lua files before uploading (provided by luamin)
- Use the NodeMcuConnector API in your own projects
- Apply Project based configurations
- Hard-Reset the module using DTR/RTS reset circuit (like NodeMCU DEV Kit)
- Run files on NodeMCU and display the output
directly from the command line.
Successful tested on Windows10, Debian 8,9,10 and Ubuntu 14,15,16,17,18 - works out of the box without any tweaks
Compatibility
The following NodeMCU firmware versions are verified
ESP8266
- NodeMCU LUA 1.4
- NodeMCU LUA 1.5.1
- NodeMCU LUA 1.5.4
- NodeMCU LUA 3.0.0
ESP32
- preliminary support (esp32-dev.latest)
Related Documents
- FAQ
- Command Reference
- Common Use-Cases and Examples
- Programmatic Usage
- Behind The Scene
- Fixing Reset-on-Connect Issue
- File Transfer Encoding
- Webstorm Integration
- Contribution Guidelines
- NodeMCU DEVKIT Schematics
- Changelog
- License
Terminology
- NodeMCU Original NodeMCU Module OR any ESP8266 platform with NodeMCU Firmware
- Upload Transfer files from your PC to NodeMCU/ESP8266 module
- Download Transfer files/obtaining information from the module
Requirements
To use/install the NodeMCU-Tool, you have to prepare your system to match the following requirements. Especially as beginner, you should read this part carefully
NodeMCU Serial Driver
Depending on your Module-Type you have to install the platform-specific driver for the usb-serial-interface. The original NodeMCU v0.9 comes with a CH341 chip with may requires manual driver installation. Modern versions like 1.0 use a CP210x chip with work out of the box on most common systems. Other ESP8266 platforms may user other interfaces - please refer to their user manuals!
Node.js
The NodeMCU-Tool is written in javascript and requires Node.js >= 7.6 as runtime environment. And please don't worry about the wording - NodeMCU and Node.js are two complete different things!
!! There is currently an issue with Node.js 11 on Windows 10 platforms. Please use Node.js 10 LTS !!
In case you're not familiar with Node.js and NPM it's recommended to read some basic introductions first! Please download the Node.js installer and install on your system in case it's not already there.
Installation
Thanks to Node.js, the NodeMCU-Tool is platform independent and will run on Windows, Linux und OSX. There are different installation variants available (system wide or project based).
via NPM (Node.js Package Manager)
It's recommended to install nodemcu-tool as global package. NPM will register the binary automatically in your path - it will be directly available on the command line.
Global Installation as root (Linux/Mac OS Platforms)
The global installation may require administrator(root) privileges because the package is added to the systems library path. If you get any permission errors on Linux/Mac OS run the command as root or via sudo
.
Note: In some special cases the installation may fail with some errors related to
node-serialport
ornode-gyp
. This errors are caused by missing pre-build binaries (native code/drivers for your platform matching your OS/nodejs version) - therefore they have to compiled on your machine! To resolve such issues, add the--unsafe-perm
flag to the following command - it allows the build scripts to be executed as root.
$ sudo npm install nodemcu-tool -g
Global Installation (Windows Platforms)
$ npm install nodemcu-tool -g
Local/Project related Installation
You can also install it in your local project directory. When using this method, the nodemcu-tool
command is not registered within your path!
$ npm install nodemcu-tool
In this case, a link to the binary file is located in node_modules/.bin/nodemcu-tool
As Archive from GitHub
You can also download the latest release directly from GitHub and extract the sources to your project directory.
After downloading you have to install the dependencies by running npm install
in the nodemcu-tool directory.
When using this method, the nodemcu-tool
command is not registered within your path. You have to register it manually using a symlink - or the recommended way: call the binary file ./bin/nodemcu-tool.js
directly.
First Steps
1. The Location of the binary file
After installing NodeMCU-Tool you should open a new terminal window and check if the tool is working by obtaining the current version. It should output the current semantic-version tag. Depending on your installation type (global ==> file is registered into your path) you can use the tool directly or you have to go into the module directory:
For Global Installations (Win/Linux/OSX)
The binary file is registered within your path. This tutorial assumes that you have installed the tool globally. Otherwise you have to modify the program-call as described below.
$ nodemcu-tool --version
1.5.0
For Local Installations
This means you have installed nodemcu-tool via NPM without the -g
(global) flag or via the .zip
/ .tar
package.
There will be no global shortcut to the nodemcu-tool binary! The binary is located in node_modules/nodemcu-tool/bin/nodemcu-tool.js
Linux, OSX
$ cd node_modules/nodemcu-tool/bin
$ ./nodemcu-tool.js --version
1.5.0
Windows
You have to call the node.exe runtime in your command!
$ cd node_modules/nodemcu-tool/bin
$ node nodemcu-tool.js --version
1.5.0
2. Identify Your NodeMCU Device
Now you can connect the NodeMCU Module to your computer. The module will be accessible via a virtual serial port. You can identify the port by using the devices
command.
In this example, it is connected via /dev/ttyUSB0
. Keep in mind that you have to provide the device-name to NodeMCU-Tool on each command!
./nodemcu-tool devices
[NodeMCU] Connected Devices | Total: 1
|- /dev/ttyUSB0 (Silicon_Labs, usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0)
3. Create the initial File System
This will remove all existing files on the module but is required when running the module for the first time. You can skip this step in case you've already done that manually!
$ nodemcu-tool mkfs --port=/dev/ttyUSB0
[NodeMCU-Tool] Do you really want to format the filesystem and delete all file ? (no) yes
[NodeMCU-Tool] Connected
[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0
[NodeMCU] Formatting the file system...this will take around ~30s
[NodeMCU] File System created | format done.
4. Upload a new File
Hint include the native encoder Module into your firmware to speed-up the uploading by factor 4..10!
$ nodemcu-tool upload --port=/dev/ttyUSB0 helloworld.lua
[NodeMCU-Tool] Connected
[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0
[NodeMCU-Tool] Uploading "main.lua" ...
[NodeMCU-Tool] Data Transfer complete!
5. Run It directly and view the output
$ nodemcu-tool run helloworld.lua
[NodeMCU-Tool] Connected
[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0
[NodeMCU] Running "helloworld.lua"
>----------------------------->
Hello World!
YEAH!!! HELLO WORLD!!!
String: Lorem ipsum dolor sit amet, consetetur sadipscing elitr
>----------------------------->
Available Commands
All commands a well documented within the Command Reference
Project based configuration
In case you're using different serial port or the baudrate-settings, it's possible to create a configuration file with specific settings for your project.
To initially create the configuration file, use the init
command:
$ nodemcu-tool init
[NodeMCU-Tool] Creating project based configuration file..
[NodeMCU-Tool] Baudrate in Bit per Seconds, e.g. 9600 (default) (9600) 9600
[NodeMCU-Tool] Serial connection to use, e.g. COM1 or /dev/ttyUSB2 (/dev/ttyUSB0) COM3
This will create a JSON based configuration file named .nodemcutool
in your current directory - you can edit this file manually
Example Configuration
In this Example, the baudrate is changed to 19.2k and COM3 is selected as default port. Additionally the --minify
and --compile
flags are set permanently.
{
"baudrate": "19200",
"port": "COM3",
"connectionDelay": 100,
"compile": true,
"minify": true,
"keeppath": true
}
Configuration Keys
All configuration options are optional
- baudrate (int) - the default baudrate in bits per second
- port (string) - the comport to use
- connectionDelay (int) - connection-delay in ms
- compile (boolean) - compile lua files after upload
- minify (boolean) - minifies files before uploading
- keeppath (boolean) - keep the relative file path in the destination filename (i.e: static/test.html will be named static/test.html)
Notes
- NodeMCU-Tool will only search in the current directory for the
.nodemcutool
file! - All default options can be overwritten by using the command line options
- The
.nodemcutool
file is only recognized inCLI Mode
NOT inAPI Mode
Programmatic Usage and Low Level API
It's possible to use the underlying "NodeMcuConnector" in your own projects to communicate with a NodeMCU based device.
Or you can call the bin
file with an external tool. For more details, take a look into the Programmatic Usage Guide
Any Questions ? Report a Bug ? Enhancements ?
Please open a new issue on GitHub
Contributing
Contributors are welcome! Even if you are not familiar with javascript you can help to improve the documentation!
License
NodeMCU-Tool is OpenSource and licensed under the Terms of The MIT License (X11). You're welcome to contribute!