nodemcu-tool

v3.2.1

Command line tool to upload and manage files on your NodeMCU / ESP8266 Module / ESP32 Module. For more information about how to use this package see README

Latest version published 4 years ago

License: MIT

NPM

GitHub

Package Health Score

45 / 100

security
Security review needed
popularity
Limited
maintenance
Inactive
community
Sustainable

Explore Similar Packages

Security

Security review needed

All security vulnerabilities belong to production dependencies of direct and indirect packages.

Security and license risk for significant versions

All Versions

Version				Vulnerabilities	License Risk
3.2.1	\|	04/2020	Popular	0 C 0 H 0 M 0 L	0 H 0 M 0 L
3.1.0	\|	10/2019		0 C 0 H 0 M 0 L	0 H 0 M 0 L
2.1.1	\|	04/2017		0 C 0 H 0 M 0 L	0 H 0 M 0 L
1.6.0	\|	05/2016		0 C 0 H 0 M 0 L	0 H 0 M 0 L
1.5.0	\|	03/2016		0 C 0 H 0 M 0 L	0 H 0 M 0 L

License

MIT

Security Policy

Is your project affected by vulnerabilities?

Scan your projects for vulnerabilities. Fix quickly with automated fixes. Get started with Snyk for free.

Get started free

Popularity

Limited

Weekly Downloads (17)

GitHub Stars: 308
Forks: 54
Contributors: 20

Direct Usage Popularity

The npm package nodemcu-tool receives a total of 17 downloads a week. As such, we scored nodemcu-tool popularity level to be Limited.

Based on project statistics from the GitHub repository for the npm package nodemcu-tool, we found that it has been starred 308 times.

Downloads are calculated as moving averages for a period of the last 12 months, excluding weekends and known missing data points.

Community

Sustainable

Readme.md: Yes
Contributing.md: No
Code of Conduct: No
Contributors: 20
Funding: No

With more than 10 contributors for the nodemcu-tool repository, this is possibly a sign for a growing and inviting community.

We found a way for you to contribute to the project! Looks like nodemcu-tool is missing a Code of Conduct.

Embed Package Health Score Badge

Maintenance

Inactive

Commit Frequency

No Recent Commits

Open Issues: 8
Open PR: 9
Last Release: 4 years ago
Last Commit: 3 years ago

Further analysis of the maintenance status of nodemcu-tool based on released npm versions cadence, the repository activity, and other data points determined that its maintenance is Inactive.

An important project maintenance signal to consider for nodemcu-tool is that it hasn't seen any new versions released to npm in the past 12 months, and could be considered as a discontinued project, or that which receives low attention from its maintainers.

As a healthy sign for on-going project maintenance, we found that the GitHub repository had at least 1 pull request or issue interacted with by the community.

Keep your project healthy

Check your package.json

Ensure all the packages you're using are healthy and well-maintained

Snyk Vulnerability Scanner

Get health score & security insights directly in your IDE

Package

Node.js Compatibility: >=8.0

Age: 8 years
Dependencies: 11 Direct
Versions: 23
Install Size: 83.2 kB
Dist-tags: 1
# of Files: 37
Maintainers: 1
TS Typings: No

nodemcu-tool has more than a single and default latest tag published for the npm package. This means, there may be other tags available for this package, such as next to indicate future releases, or stable to indicate stable releases.

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

Demo

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)

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 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.

$ 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 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

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!

nodemcu-tool dependencies

async-magic cli-progress colors commander fs-magic glob is-glob logging-facility luamin prompt serialport

nodemcu-tool development dependencies

eslint eslint-config-aenondynamics

FAQs

What is nodemcu-tool?

Command line tool to upload and manage files on your NodeMCU / ESP8266 Module / ESP32 Module. Visit Snyk Advisor to see a full health score report for nodemcu-tool, including popularity, security, maintenance & community analysis.

Is nodemcu-tool popular?

The npm package nodemcu-tool receives a total of 17 weekly downloads. As such, nodemcu-tool popularity was classified as limited. Visit the popularity section on Snyk Advisor to see the full health analysis.

Is nodemcu-tool well maintained?

We found indications that nodemcu-tool is an Inactive project. See the full package health analysis to learn more about the package maintenance status.

Is nodemcu-tool safe to use?

While scanning the latest version of nodemcu-tool, we found that a security review is needed. A total of 3 vulnerabilities or license issues were detected. See the full security scan results.

Last updated on 16 April-2024, at 02:42 (UTC).

Build a secure application checklist

Select a recommended open source package

Minimize your risk by selecting secure & well maintained open source packages

DONE

Scan your app for vulnerabilities

Scan your application to find vulnerabilities in your: source code, open source dependencies, containers and configuration files

SCAN NOW

Fix identified vulnerabilities

Easily fix your code by leveraging automatically generated PRs

AUTO FIX

Monitor for new issues

New vulnerabilities are discovered every day. Get notified if your application is affected

MONITOR APP

Package Health Score

Explore Similar Packages

Security and license risk for significant versions

Is your project affected by vulnerabilities?

Weekly Downloads (17)

Direct Usage Popularity

Embed Package Health Score Badge

Commit Frequency

Keep your project healthy

Check your package.json

Snyk Vulnerability Scanner

Readme

NodeMCU-Tool

Tool Summary

Compatibility

Related Documents

Terminology

Requirements

NodeMCU Serial Driver

Node.js

Installation

via NPM (Node.js Package Manager)

Global Installation as root (Linux/Mac OS Platforms)

Global Installation (Windows Platforms)

Local/Project related Installation

As Archive from GitHub

First Steps

1. The Location of the binary file

For Global Installations (Win/Linux/OSX)

For Local Installations

Linux, OSX

Windows

2. Identify Your NodeMCU Device

3. Create the initial File System

4. Upload a new File

5. Run It directly and view the output

Available Commands

Project based configuration

Example Configuration

Configuration Keys

Notes

Programmatic Usage and Low Level API

Any Questions ? Report a Bug ? Enhancements ?

Contributing

License

nodemcu-tool dependencies

nodemcu-tool development dependencies

FAQs

What is nodemcu-tool?

Is nodemcu-tool popular?

Is nodemcu-tool well maintained?

Is nodemcu-tool safe to use?

Build a secure application checklist

Select a recommended open source package

Scan your app for vulnerabilities

Source Code

Open Source

Container

Config

Fix identified vulnerabilities

Monitor for new issues