{"id":15287656,"url":"https://github.com/NodeMCU-Tool/NodeMCU-Tool","last_synced_at":"2025-12-29T23:45:16.053Z","repository":{"id":2787984,"uuid":"47454151","full_name":"AndiDittrich/NodeMCU-Tool","owner":"AndiDittrich","description":":wrench: Upload + Manage Lua files on NodeMCU","archived":false,"fork":false,"pushed_at":"2024-08-22T06:14:27.000Z","size":430,"stargazers_count":316,"open_issues_count":9,"forks_count":54,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-30T06:58:38.685Z","etag":null,"topics":["esp8266","iot","lua","nodemcu","nodemcu-firmware","nodemcu-lua","serial","transfer-files"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nodemcu-tool","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AndiDittrich.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-05T11:59:14.000Z","updated_at":"2024-09-17T05:49:28.000Z","dependencies_parsed_at":"2024-11-19T21:46:50.994Z","dependency_job_id":null,"html_url":"https://github.com/AndiDittrich/NodeMCU-Tool","commit_stats":{"total_commits":144,"total_committers":20,"mean_commits":7.2,"dds":0.2152777777777778,"last_synced_commit":"d4eb3892cb576187cdf21ada6283cb253695bbb2"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndiDittrich%2FNodeMCU-Tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndiDittrich%2FNodeMCU-Tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndiDittrich%2FNodeMCU-Tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AndiDittrich%2FNodeMCU-Tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AndiDittrich","download_url":"https://codeload.github.com/AndiDittrich/NodeMCU-Tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243258495,"owners_count":20262298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp8266","iot","lua","nodemcu","nodemcu-firmware","nodemcu-lua","serial","transfer-files"],"created_at":"2024-09-30T15:33:47.823Z","updated_at":"2025-12-29T23:45:15.994Z","avatar_url":"https://github.com/AndiDittrich.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/AndiDittrich/NodeMCU-Tool.svg?branch=master)](https://travis-ci.org/AndiDittrich/NodeMCU-Tool)\n\nNodeMCU-Tool\n============\nUpload/Download Lua files to your ESP8266/ESP32 module with NodeMCU firmware.\n\n**Simple. Command Line. Cross-Platform. File Management. [NodeMCU](http://nodemcu.com/index_en.html).**\n\n```shell\n$ npm install nodemcu-tool -g\n```\n\n![Demo](assets/video.gif)\n\nTool Summary\n-------------\nNodeMCU Tool allows you to\n\n* Upload Lua files to your ESP8266/ESP32/NodeMCU module\n* Upload any file-types (binary save)\n* Bulk/Multi file uploads\n* Download any file-type (binary save)\n* Delete files\n* Format the file system\n* Simple Serial Terminal to interact with NodeMCU\n* Show existing files on your module\n* Precompile Lua files live on NodeMCU\n* Minimize Lua files before uploading (provided by [luamin](https://www.npmjs.com/package/luamin))\n* Use the **NodeMcuConnector API** in your own projects\n* Apply Project based configurations\n* Hard-Reset the module using DTR/RTS reset circuit (like NodeMCU DEV Kit)\n* Run files on NodeMCU and display the output\n\ndirectly from the command line.\n\n*Successful tested on Windows10, Debian 8,9,10 and Ubuntu 14,15,16,17,18 - works out of the box without any tweaks*\n\nCompatibility\n-------------\nThe following NodeMCU firmware versions are verified\n\n**ESP8266**\n* NodeMCU Lua 1.4\n* NodeMCU Lua 1.5.1\n* NodeMCU Lua 1.5.4\n* NodeMCU Lua 3.0.0\n\n**ESP32**\n* support (dev-esp32.latest)\n\n---------------------------------------\n\nRelated Documents\n-----------------\n\n* [FAQ](FAQ.md)\n* [Command Reference](docs/CommandReference.md)\n* [Common Use-Cases and Examples](docs/Examples.md)\n* [Programmatic Usage](docs/ProgrammaticUsage.md)\n* [Behind The Scene](docs/BehindTheScene.md)\n* [Fixing Reset-on-Connect Issue](docs/Reset_on_Connect.md)\n* [File Transfer Encoding](docs/TransferEncoding.md)\n* [Webstorm Integration](docs/WebstormIntegration.md)\n* [Contribution Guidelines](CONTRIBUTE.md)\n* [NodeMCU DEVKIT Schematics](https://github.com/nodemcu/nodemcu-devkit-v1.0/blob/master/NODEMCU_DEVKIT_V1.0.PDF)\n* [Changelog](CHANGES.md)\n* [License](LICENSE.md)\n\nTerminology\n-----------\n* **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)\n* **Upload** Transfer files from your PC to NodeMCU/ESP8266 module\n* **Download** Transfer files/obtaining information from the module\n\n---------------------------------------\n\nRequirements\n------------\n\nTo 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**\n\n### NodeMCU Serial Driver ###\n\nDepending on your Module-Type you have to install the platform-specific driver for the usb-serial-interface. \nThe 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.\nOther ESP8266 platforms may user other interfaces - please refer to their user manuals!\n\n### Node.js ###\n\nThe NodeMCU-Tool is written in javascript and requires [Node.js \u003e= 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!\n\n**!! There is currently an issue with Node.js 11 on Windows 10 platforms. Please use Node.js 10 LTS !!**\n\nIn 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!\nPlease [download the Node.js installer](https://nodejs.org/en/download/) and install on your system in case it's not already there.\n\n---------------------------------------\n\nInstallation\n------------\n\nThanks 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). \n\n### via NPM (Node.js Package Manager) ###\n\nIt's recommended to install nodemcu-tool as [global package](https://docs.npmjs.com/getting-started/installing-npm-packages-globally).\nNPM will register the binary automatically in your path - it will be directly available on the command line.\n\n#### Global Installation as root (Linux/Mac OS Platforms) ####\n\nThe 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`.\n\n\u003e **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!\n\u003e To resolve such issues, add the `--unsafe-perm` flag to the following command - it allows the build scripts to be executed as root.\n\n```shell\n$ sudo npm install nodemcu-tool -g\n```\n\n#### Global Installation (Windows Platforms) ####\n\n```shell\n$ npm install nodemcu-tool -g\n```\n\n#### Local/Project related Installation ####\n\nYou can also install it in your local project directory. When using this method, the `nodemcu-tool` command is **not registered** within your path!\n\n```shell\n$ npm install nodemcu-tool\n```\n\nIn this case, a link to the binary file is located in `node_modules/.bin/nodemcu-tool`\n\n### As Archive from GitHub ###\n\nYou 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.\nAfter downloading you have to **install the dependencies** by running `npm install` in the nodemcu-tool directory.\n\nWhen 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.\n\n---------------------------------------\n\nFirst Steps\n-----------\n\n### 1. The Location of the binary file ###\n\nAfter 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.\nDepending on your installation type (global ==\u003e file is registered into your path) you can use the tool directly or you have to go into the module directory:\n\n#### For Global Installations (Win/Linux/OSX) ####\n\nThe 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.\n\n```bash\n$ nodemcu-tool --version\n1.5.0\n```\n\n#### For Local Installations ####\n\nThis means you have installed nodemcu-tool via NPM **without** the `-g` (global) flag or via the `.zip` / `.tar` package.\nThere will be **no** global shortcut to the nodemcu-tool binary! The binary is located in `node_modules/nodemcu-tool/bin/nodemcu-tool.js`\n\n##### Linux, OSX #####\n\n```bash\n$ cd node_modules/nodemcu-tool/bin\n$ ./nodemcu-tool.js --version\n1.5.0\n```\n\n##### Windows #####\n\nYou have to call the node.exe runtime in your command!\n\n```bash\n$ cd node_modules/nodemcu-tool/bin\n$ node nodemcu-tool.js --version\n1.5.0\n```\n\n### 2. Identify Your NodeMCU Device ###\n\nNow 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.\nIn 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!\n\n```shell\n./nodemcu-tool devices\n[NodeMCU] Connected Devices | Total: 1\n          |- /dev/ttyUSB0 (Silicon_Labs, usb-Silicon_Labs_CP2102_USB_to_UART_Bridge_Controller_0001-if00-port0)\n```\n\n### 3. Create the initial File System ###\nThis 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!\n\n```shell\n$ nodemcu-tool mkfs --port=/dev/ttyUSB0\n[NodeMCU-Tool] Do you really want to format the filesystem and delete all file ? (no) yes\n[NodeMCU-Tool] Connected\n[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0\n[NodeMCU] Formatting the file system...this will take around ~30s\n[NodeMCU] File System created | format done.\n```\n\n### 4. Upload a new File ###\n\n**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!\n\n```shell\n$ nodemcu-tool upload --port=/dev/ttyUSB0 helloworld.lua\n[NodeMCU-Tool] Connected\n[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0\n[NodeMCU-Tool] Uploading \"main.lua\" ...\n[NodeMCU-Tool] Data Transfer complete!\n```\n\n### 5. Run It directly and view the output ###\n\n```shell\n$ nodemcu-tool run helloworld.lua\n[NodeMCU-Tool] Connected\n[NodeMCU] Version: 0.9.5 | ChipID: 0xd1aa | FlashID: 0x1640e0\n[NodeMCU] Running \"helloworld.lua\"\n\u003e-----------------------------\u003e\nHello World!\nYEAH!!! HELLO WORLD!!!\nString: Lorem ipsum dolor sit amet, consetetur sadipscing elitr\n\u003e-----------------------------\u003e\n```\n\n### Available Commands ###\n\nAll commands a well documented within the [Command Reference](docs/CommandReference.md)\n\nProject based configuration\n---------------------------\n\nIn 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.\nTo initially create the configuration file, use the `init` command:\n\n```shell\n$ nodemcu-tool init\n[NodeMCU-Tool] Creating project based configuration file..\n[NodeMCU-Tool] Baudrate in Bit per Seconds, e.g. 9600 (default) (9600) 9600\n[NodeMCU-Tool] Serial connection to use, e.g. COM1 or /dev/ttyUSB2 (/dev/ttyUSB0) COM3\n```\n\nThis will create a JSON based configuration file named `.nodemcutool` in your **current directory** - you can edit this file manually\n\n### Example Configuration ###\n\nIn 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.\n\n```json\n{\n    \"baudrate\": \"19200\",\n    \"port\": \"COM3\",\n    \"connectionDelay\": 100,\n    \"compile\": true,\n    \"minify\": true,\n    \"keeppath\": true\n}\n```\n \n### Configuration Keys ###\n\nAll configuration options are **optional**\n\n* **baudrate** (int) - the default baudrate in bits per second\n* **port** (string) - the comport to use\n* **connectionDelay** (int) - connection-delay in ms\n* **compile** (boolean) - compile lua files after upload\n* **minify** (boolean) - minifies files before uploading\n* **keeppath** (boolean) - keep the relative file path in the destination filename (i.e: static/test.html will be named static/test.html)\n  \n### Notes ###\n  \n* NodeMCU-Tool will only search in the **current directory** for the `.nodemcutool` file!\n* All default options can be overwritten by using the command line options\n* The `.nodemcutool` file is only recognized in `CLI Mode` **NOT** in `API Mode`\n\nProgrammatic Usage and Low Level API\n------------------------------------\nIt's possible to use the underlying \"NodeMcuConnector\" in your own projects to communicate with a NodeMCU based device.\nOr you can call the `bin` file with an external tool. For more details, take a look into the [Programmatic Usage Guide](docs/ProgrammaticUsage.md)\n\nAny Questions ? Report a Bug ? Enhancements ?\n---------------------------------------------\nPlease open a new issue on [GitHub](https://github.com/AndiDittrich/NodeMCU-Tool/issues)\n\nContributing\n------------\n\nContributors are welcome! Even if you are not familiar with javascript you can help to improve the documentation!\n\nLicense\n-------\nNodeMCU-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)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNodeMCU-Tool%2FNodeMCU-Tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNodeMCU-Tool%2FNodeMCU-Tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNodeMCU-Tool%2FNodeMCU-Tool/lists"}