{"id":15287649,"url":"https://github.com/kmpm/nodemcu-uploader","last_synced_at":"2025-07-08T07:16:27.375Z","repository":{"id":25654094,"uuid":"29089534","full_name":"kmpm/nodemcu-uploader","owner":"kmpm","description":"Upload files to your esp8266 running nodeMcu","archived":false,"fork":false,"pushed_at":"2024-08-11T22:09:52.000Z","size":1101,"stargazers_count":320,"open_issues_count":17,"forks_count":89,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-01-17T17:07:17.499Z","etag":null,"topics":["esp8266","lua","nodemcu","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/kmpm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-01-11T11:31:22.000Z","updated_at":"2024-11-11T17:16:05.000Z","dependencies_parsed_at":"2024-11-19T21:46:34.219Z","dependency_job_id":null,"html_url":"https://github.com/kmpm/nodemcu-uploader","commit_stats":{"total_commits":176,"total_committers":27,"mean_commits":6.518518518518518,"dds":0.5227272727272727,"last_synced_commit":"6178f40fff2deadd56b5bc474f9b4475ef444b37"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmpm%2Fnodemcu-uploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmpm%2Fnodemcu-uploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmpm%2Fnodemcu-uploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kmpm%2Fnodemcu-uploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kmpm","download_url":"https://codeload.github.com/kmpm/nodemcu-uploader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235481631,"owners_count":18997121,"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","lua","nodemcu","python"],"created_at":"2024-09-30T15:33:46.556Z","updated_at":"2025-07-08T07:16:27.368Z","avatar_url":"https://github.com/kmpm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"nodemcu-uploader.py\n===================\n\n__Archival notice!!!__ This project is currently archived because of lack of time\nand interest. I no longer use NodeMCU in any form. But someone else might be.\nIf you want to post a notice here about your active alternative then send me a\nDM here on github.\n\n---\n\nA simple tool for uploading files to the filesystem of an\nESP8266 running NodeMCU as well as some other useful commands.\n\nIt should work on Linux, and OS X; and with any type of file\nthat fits the filesystem, binary or text.\n\n| master |\n|--------|\n|[![Build Status](https://travis-ci.org/kmpm/nodemcu-uploader.svg?branch=master)](https://travis-ci.org/kmpm/nodemcu-uploader) | \n\nPlease note that these tests is not complete and it might be the tests\nthemselves that are having issues.\n\n\nCall for maintainers\n--------------------\nHi,\nThis project is in need of maintenance and I (kmpm) do not have the time the \nproject deserves. Look at https://github.com/kmpm/nodemcu-uploader/issues/90 \nfor more information on what to do about it or email me@kmpm.se\n\n\nInstallation\n-------------\nShould be installable by PyPI (prefered) but there might be\npackaging issues still.\n\n    pip install nodemcu-uploader\n    nodemcu-uploader\n\nOtherwise clone from github and run directly from there\n\n    git clone https://github.com/kmpm/nodemcu-uploader\n    cd nodemcu-uploader\n    python ./nodemcu-uploader.py\n\nNote that pip would install pyserial \u003e= 2.7.\nThe terminal command (using miniterm from pyserial) might\nnot work depending on version used. This is a known issue.\n\n\n### Notes for Windows\nThere might be some\n[significant issues with Windows](https://github.com/kmpm/nodemcu-uploader/issues?q=is%3Aissue+is%3Aopen+label%3Aos%3Awindows).\n\n### Notes for OS X\nTo solve \"ImportError: No module named serial\", install the pyserial module:\n```sh\npython easy_install pyserial\n```\n\nUsage\n-----\nDownload NodeMCU firmware from  http://nodemcu-build.com/ .\n\nSince version v0.4.0 of the tool you will need a recent (june/july 2016) version \nof the firmware for nodemcu. The default baudrate was changed in firmware from\n9600 to 115200 and this tool was changed as well. \n\nIf you are using an older firmware you MUST use the option `--start-baud 9600`\nto the device to be recognized. Otherwise you will get a \n_Device not found or wrong port_ error.\n\nFor more usage details see [USAGE.md in doc](doc/USAGE.md)\n\n\nIssues\n-------\nWhen reporting issues please provide operating system (windows, mac, linux etc.),\nversion of this tool `nodemcu-uploader --version` and version of the firmware\non you device. If you got the firmware from http://nodemcu-build.com/ please\ntell if it was the dev or master branch and at what date it was created.\n\nAs for firmware version I would like to have a dump of the details you get\nwhen connected using a terminal to the device at boot time.\nIt would look something like this...\n```\nNodeMCU custom build by frightanic.com\n        branch: master\n        commit: b580bfe79e6e73020c2bd7cd92a6afe01a8bc867\n        SSL: false\n        modules: crypto,file,gpio,http,mdns,mqtt,net,node,tmr,uart,wifi\n build  built on: 2016-07-29 11:08\n powered by Lua 5.1.4 on SDK 1.5.1(e67da894)\n ```\n\nWhen you have as much of that as possible, \ncreate a issue in github, https://github.com/kmpm/nodemcu-uploader/issues\n\n\n\nTechnical Details\n-----------------\nThis *almost* uses a implementation of xmodem protocol for the up-/download part.\nThe main missing part is checksum and retransmission.\n\nThis is made possible by first preparing the device by creating a set of helper\nfunctions using the ordinary terminal mode.\nThese function utilize the built in uart module for the actual transfer and\ncuts up the transfers to a set of manageable blocks that are reassembled\nin the receiving end.\n\n### Upload\n1. Client calls the function recv()\n2. NodeMCU disables echo and send a 'C' to tell that it's ready to receive data\n3. Client sends a filename terminated with 0x00\n4. NodeMCU sends ACK\n5. Client send block of data according to the definition.\n6. NodeMCU sends ACK\n7. Step 5 and 6 are repeated until NodeMCU receives a block with 0 as size.\n8. NodeMCU enables normal terminal again with echo\n\n### Download\n1. Client calls the function send(\u003cfilename\u003e).\n2. NodeMCU disables echo and waits for start.\n2. Client send a 'C' to tell that it's ready to receive data\n3. NodeMCU sends a filename terminated with 0x00\n4. Client sends ACK\n5. NodeMCU send block of data according to the definition.\n6. Client sends ACK\n7. Step 5 and 6 are repeated until client receives a block with 0 as size.\n8. NodeMCU enables normal terminal again with echo.\n\n\n\n### Data Block Definition\n__SOH__, __size__, __data[128]__\n\n* SOH = 0x01\n* Single byte telling how much of the 128 bytes data that are actually used.\n* Data padded with random bytes to fill out the 128 bytes frame.\n\nThis gives a total 130 bytes per block.\n\nThe block size was decided for...\n\n1. Being close to xmodem from where the inspiration came\n2. A fixed size allow the use of the uart.on('data') event very easy.\n3. 130 bytes would fit in the receive buffer.\n4. It would not waste that much traffic if the total size uploaded was not a \n   even multiple of the allowed datasize.\n\n\n\nDisclaimer\n-----------\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmpm%2Fnodemcu-uploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkmpm%2Fnodemcu-uploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkmpm%2Fnodemcu-uploader/lists"}