# NodeMCU-Tool **Repository Path**: Ll_M_m/NodeMCU-Tool ## Basic Information - **Project Name**: NodeMCU-Tool - **Description**: :wrench: Upload + Manage Lua files on NodeMCU - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 3 - **Created**: 2023-01-11 - **Last Updated**: 2023-01-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README [![Build Status](https://travis-ci.org/AndiDittrich/NodeMCU-Tool.svg?branch=master)](https://travis-ci.org/AndiDittrich/NodeMCU-Tool) NodeMCU-Tool ============ Upload/Download Lua files to your ESP8266/ESP32 module with NodeMCU firmware. **Simple. Command Line. Cross-Platform. File Management. [NodeMCU](http://nodemcu.com/index_en.html).** ```shell $ npm install nodemcu-tool -g ``` ![Demo](assets/video.gif) 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](https://www.npmjs.com/package/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](FAQ.md) * [Command Reference](docs/CommandReference.md) * [Common Use-Cases and Examples](docs/Examples.md) * [Programmatic Usage](docs/ProgrammaticUsage.md) * [Behind The Scene](docs/BehindTheScene.md) * [Fixing Reset-on-Connect Issue](docs/Reset_on_Connect.md) * [File Transfer Encoding](docs/TransferEncoding.md) * [Webstorm Integration](docs/WebstormIntegration.md) * [Contribution Guidelines](CONTRIBUTE.md) * [NodeMCU DEVKIT Schematics](https://github.com/nodemcu/nodemcu-devkit-v1.0/blob/master/NODEMCU_DEVKIT_V1.0.PDF) * [Changelog](CHANGES.md) * [License](LICENSE.md) Terminology ----------- * **NodeMCU** Original [NodeMCU](http://nodemcu.com/index_en.html) Module **OR** any [ESP8266](http://espressif.com/en/products/esp8266/) platform with [NodeMCU Firmware](https://github.com/nodemcu/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](https://nodejs.org) 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](https://nodejs.org) and [NPM](https://www.npmjs.com) it's recommended to read some [basic introductions](https://docs.npmjs.com/getting-started/what-is-npm) first! Please [download the Node.js installer](https://nodejs.org/en/download/) 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](https://docs.npmjs.com/getting-started/installing-npm-packages-globally). 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` or `node-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. ```shell $ sudo npm install nodemcu-tool -g ``` #### Global Installation (Windows Platforms) #### ```shell $ 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! ```shell $ 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](https://github.com/AndiDittrich/NodeMCU-Tool/releases/latest) directly from [GitHub](https://github.com/AndiDittrich/NodeMCU-Tool/releases) 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. ```bash $ 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 ##### ```bash $ 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! ```bash $ 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! ```shell ./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! ```shell $ 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](https://nodemcu.readthedocs.io/en/release/modules/encoder/) into your firmware to speed-up the uploading by factor 4..10! ```shell $ 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 ### ```shell $ 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](docs/CommandReference.md) 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: ```shell $ 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. ```json { "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 in `CLI Mode` **NOT** in `API 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](docs/ProgrammaticUsage.md) Any Questions ? Report a Bug ? Enhancements ? --------------------------------------------- Please open a new issue on [GitHub](https://github.com/AndiDittrich/NodeMCU-Tool/issues) 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)](http://opensource.org/licenses/MIT). You're welcome to [contribute](https://github.com/AndiDittrich/NodeMCU-Tool/blob/master/CONTRIBUTE.md)!