nrflash 1.0.0__tar.gz

nrflash-1.0.0/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

nrflash-1.0.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: nrflash
+Version: 1.0.0
+Summary: Termux-native .bin flasher for ESP32/ESP8266 boards — no root, no esptool.py subprocess, no pyserial.
+Author: 7wp81x
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/7wp81x/Termux-ESP-Flasher
+Project-URL: Repository, https://github.com/7wp81x/Termux-ESP-Flasher
+Project-URL: Issues, https://github.com/7wp81x/Termux-ESP-Flasher/issues
+Keywords: esp32,esp8266,termux,flasher,esptool,no-root,android
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Android
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE-APACHE
+License-File: STUB_LICENSE-APACHE
+License-File: STUB_LICENSE-MIT
+Requires-Dist: pyusb>=1.2.1
+Dynamic: license-file
+
+# Termux-ESP-Flasher
+
+A Termux-native `.bin` flasher for ESP32 boards — no root, no
+`esptool.py` subprocess, no pyserial.
+
+Covers **two** device families, auto-detected from the USB VID:PID:
+
+- **Native USB CDC** — ESP32-S3 / C3 / S2 (`303A:1001` / `303A:0002`).
+  Talks directly to the chip's USB-Serial-JTAG peripheral; bootloader
+  entry/exit is driven by `cdc_reset.py`.
+- **UART bridge** — classic ESP32 and ESP8266 devkits behind a
+  CP2102, CH340/CH340G, CH9102, or FTDI FT232 bridge chip. The bridge
+  is opened over raw USB (same fd-wrapping as the native path — Termux
+  never gives you a `/dev/ttyUSB*` node without root, so this isn't
+  optional) and its DTR/RTS lines are pulsed in the classic GPIO0+EN
+  pattern by `uart_reset.py`.
+
+Both paths upload the real ESP-IDF RAM stub for faster block writes, and
+both fall back automatically to the plain ROM bootloader if the stub
+fails to load for any reason.
+
+## Why this exists instead of just running esptool.py
+
+`esptool.py` talks over pyserial, which expects a `/dev/ttyUSB*` or
+`/dev/ttyACM*` node. On stock no-root Termux there often isn't one —
+Android hands USB access to apps as a raw file descriptor via
+`termux-usb`, not a serial device node. This tool talks straight to the
+USB endpoints (and, for UART-bridge boards, straight to the bridge
+chip's own vendor registers) instead of assuming a tty exists.
+
+**If you're on a desktop/laptop Linux box with a real `/dev/ttyUSB*`
+node, just use real `esptool.py` — it's more battle-tested.** This tool
+exists for the no-root-Termux gap esptool's pyserial transport can't
+reach.
+
+## What's supported
+
+- **Chip auto-detection.** `--chip` is optional on `probe`, `write`, and
+  `verify` — omit it and the tool syncs with the ROM bootloader, reads
+  the chip's magic-value register, and picks the right chip for you.
+  Pass `--chip` explicitly to override (still required for
+  `erase-info`, which never touches hardware).
+- **Stub loader.** Both native-USB and UART-bridge sessions upload the
+  real ESP-IDF RAM stub after syncing, switching from 1 KiB ROM-only
+  blocks to 16 KiB stub blocks. Falls back to ROM-only if the stub
+  upload doesn't succeed for some reason — flashing still works, just
+  slower.
+- **Automatic baud renegotiation on UART-bridge boards.** Once the stub
+  is running, the tool steps up through 921600 → 460800 → 230400 baud,
+  verifying each one actually holds (a cheap `sync()`) before trusting
+  it. If a candidate rate doesn't hold, it physically re-enters the ROM
+  bootloader and rebuilds the whole session at 115200 before trying the
+  next slower candidate — a bad guess costs a couple seconds, not the
+  whole flash. Settles on whatever your specific board/cable can
+  actually sustain, or stays at 115200 if nothing higher works. Native
+  USB CDC boards skip this entirely — there's no real UART clock
+  underneath USB CDC, so baud rate doesn't mean anything there.
+- **Live progress.** The flash progress bar streams in real time on the
+  no-root Termux fd-bootstrap path — earlier builds buffered progress
+  updates invisibly until the transfer finished, then dumped the whole
+  bar at once, which looked like a stall.
+- **Multi-file writes in one session.** `write` accepts one or more
+  `OFFSET:FILE` pairs and flashes all of them under a single USB
+  permission prompt / bootloader handshake.
+
+## Scope / limitations (read before filing an issue)
+
+- **No full-chip erase command.** `erase-info` explains why: an erase
+  that gets interrupted by a flaky OTG connection mid-operation has no
+  recovery path. Flash a full image (bootloader + partition table +
+  app) at the correct offsets instead of erasing first. `write --erase`
+  will erase exactly the bytes about to be overwritten via
+  `ERASE_REGION` if the ROM supports it, falling back silently to
+  `flash_begin`'s own per-block erase otherwise.
+- **Auto-detection is a best-effort heuristic**, not a guarantee for
+  every silicon revision — it reads the chip magic value at a register
+  address that's held true across ESP32/S2/S3/C3 for years, but an
+  unrecognized value means "pass `--chip` explicitly," not a guess.
+- **Stub data is vendored for more chips than are currently wired up**
+  (`esp32c2`, `c5`, `c6`, `c61`, `h2`, `h4`, `p4`, `s31` all have stub
+  binaries already sitting in `stub_flasher_data.py`), but
+  `CHIP_PARAMS`/`KNOWN_MAGIC`/`CHIP_CHOICES` only cover `esp32`,
+  `esp8266`, `esp32s2`, `esp32s3`, `esp32c3` today. Wiring up one of the
+  others means adding its real chip-magic value and SPI-attach params —
+  open an issue (or ask) with the specific chip if you need one.
+
+## Install
+
+```bash
+pkg update && pkg install python termux-api libusb
+pip install nrflash
+```
+
+`pip install nrflash` pulls in `pyusb` automatically. `termux-api` and
+`libusb` are system packages `pip` can't install for you — they still need
+`pkg install`, and the **Termux:API** app from
+[F-Droid](https://f-droid.org) (not the Play Store) must be installed
+separately for the no-root USB-permission flow to work at all.
+
+<details>
+<summary>Installing from source instead</summary>
+
+```bash
+git clone https://github.com/7wp81x/Termux-ESP-Flasher
+cd Termux-ESP-Flasher
+pip install .
+```
+</details>
+
+## Usage
+
+```bash
+chmod +x nrflash
+
+# --chip is optional everywhere except erase-info - omit it to auto-detect
+./nrflash probe
+./nrflash write --offset 0x0 firmware.bin
+
+# Still works if you want to force a specific chip
+./nrflash write --chip esp32c3 --offset 0x0 firmware.bin
+
+# Flash + MD5-verify against the device afterward
+./nrflash write --chip esp32s3 --offset 0x0 firmware.bin --verify
+
+# Flash a sub-image at a partition offset (e.g. app partition only)
+./nrflash write --offset 0x10000 app.bin
+
+# Flash bootloader + partition table + app in one session
+./nrflash write 0x0:bootloader.bin 0x8000:partitions.bin 0x10000:app.bin
+
+# Stand-alone MD5 check against a file already on disk
+./nrflash verify --chip esp32c3 --offset 0x0 firmware.bin
+
+# Explicitly erase the write range first via ERASE_REGION
+./nrflash write --offset 0x0 firmware.bin --erase
+
+# Stay in the bootloader after flashing instead of rebooting
+./nrflash write --offset 0x0 firmware.bin --no-reboot
+```
+
+First run on no-root Termux pops the same USB permission dialog every
+time — tap **OK**. The permission persists until you unplug.
+
+## What actually flashes — single binary vs. esptool's three images
+
+Real `esptool.py write_flash` usually takes **three** files at three
+offsets (bootloader, partition table, app), e.g.:
+
+```
+0x0      bootloader.bin
+0x8000   partition-table.bin
+0x10000  app.bin
+```
+
+`nrflash write` can take all three in one call (see the multi-file
+example above), or one file per invocation if you prefer. If your build
+only produces a single merged/combined `.bin` (PlatformIO can do this —
+check for a `firmware.factory.bin` or similar after `pio run`), one call
+at `0x0` is all you need.
+
+## How bootloader entry works
+
+- **UART-bridge boards** (CP2102/CH340/CH9102/FTDI) have real DTR/RTS
+  lines wired into EN/BOOT. `usb_device.py`'s `init_uart_bridge()`
+  configures the bridge's line coding and baud divisor via its own
+  vendor control transfers, then `uart_reset.py` pulses DTR/RTS in the
+  classic auto-reset pattern.
+- **Native USB CDC boards** have no bridge chip — the chip's internal
+  USB-Serial-JTAG peripheral watches the CDC class's
+  `SET_CONTROL_LINE_STATE` DTR/RTS bits in hardware and maps specific
+  transitions to an internal EN/BOOT reset, the software-only
+  equivalent of the same trick. That sequence lives in `cdc_reset.py`,
+  separate from `usb_device.py`'s bridge-chip logic since the two have
+  nothing in common at the wire level.
+
+## Files
+
+```
+src/nrflash/
+  __init__.py          package version
+  __main__.py          enables `python3 -m nrflash.cli`
+  cli.py               CLI: argv parsing, fd bootstrap, flash/verify/probe commands
+  rom_loader.py        SLIP framing + ROM bootloader command/response protocol,
+                        chip auto-detection, baud-change command
+  usb_device.py        USB backend detection, fd wrapping, UART-bridge register
+                        init/baud reprogramming, endpoint discovery
+  cdc_reset.py         native-USB-CDC bootloader entry/exit (DTR/RTS bit tricks)
+  uart_reset.py        UART-bridge bootloader entry/exit (DTR/RTS pulse pattern)
+  stub_flasher_data.py vendored ESP-IDF RAM stub binaries (Apache-2.0/MIT, Espressif)
+```
+
+`pip install nrflash` puts a `nrflash` console script on `PATH` — no
+`chmod +x`, no flat-directory requirement. Log/state files live under
+`~/.nrflash` (override with `NRFLASH_DATA_DIR`) rather than next to the
+installed package, since site-packages isn't guaranteed writable.
+
+## Troubleshooting
+
+**`probe` reports no response from bootloader**
+Some clone boards need the physical BOOT button held while plugging in,
+or the CH340/CP2102/FTDI wired to EN+GPIO0 for auto-reset to work at
+all. Try unplugging/replugging the OTG cable once before assuming it's a
+protocol problem.
+
+**Flashing is slow / progress bar looks stuck**
+On UART-bridge boards, check the log for a `Baud rate raised to ... and
+verified` line — if it's missing or stuck at 115200, your specific
+board/cable couldn't hold anything higher and the tool already fell back
+automatically. If the progress bar itself looks frozen and then jumps to
+100% all at once, make sure you're on a build with the live-progress fix
+(see "What's supported" above) rather than an older buffered-tail-thread
+build.
+
+**`Verify MISMATCH` after a successful-looking write**
+Don't trust a partial flash. Re-run `write --verify` rather than
+assuming the device is fine — a flaky OTG link or an unstable baud rate
+can drop bytes mid-transfer in a way that still returns "success" status
+on a given block.
+
+## Legal
+
+For use on hardware you own. Flashing arbitrary firmware to a device you
+don't own or have written permission to modify can violate warranty
+terms or, depending on the device and jurisdiction, the law.

nrflash-1.0.0/README.md

@@ -0,0 +1,224 @@
+# Termux-ESP-Flasher
+
+A Termux-native `.bin` flasher for ESP32 boards — no root, no
+`esptool.py` subprocess, no pyserial.
+
+Covers **two** device families, auto-detected from the USB VID:PID:
+
+- **Native USB CDC** — ESP32-S3 / C3 / S2 (`303A:1001` / `303A:0002`).
+  Talks directly to the chip's USB-Serial-JTAG peripheral; bootloader
+  entry/exit is driven by `cdc_reset.py`.
+- **UART bridge** — classic ESP32 and ESP8266 devkits behind a
+  CP2102, CH340/CH340G, CH9102, or FTDI FT232 bridge chip. The bridge
+  is opened over raw USB (same fd-wrapping as the native path — Termux
+  never gives you a `/dev/ttyUSB*` node without root, so this isn't
+  optional) and its DTR/RTS lines are pulsed in the classic GPIO0+EN
+  pattern by `uart_reset.py`.
+
+Both paths upload the real ESP-IDF RAM stub for faster block writes, and
+both fall back automatically to the plain ROM bootloader if the stub
+fails to load for any reason.
+
+## Why this exists instead of just running esptool.py
+
+`esptool.py` talks over pyserial, which expects a `/dev/ttyUSB*` or
+`/dev/ttyACM*` node. On stock no-root Termux there often isn't one —
+Android hands USB access to apps as a raw file descriptor via
+`termux-usb`, not a serial device node. This tool talks straight to the
+USB endpoints (and, for UART-bridge boards, straight to the bridge
+chip's own vendor registers) instead of assuming a tty exists.
+
+**If you're on a desktop/laptop Linux box with a real `/dev/ttyUSB*`
+node, just use real `esptool.py` — it's more battle-tested.** This tool
+exists for the no-root-Termux gap esptool's pyserial transport can't
+reach.
+
+## What's supported
+
+- **Chip auto-detection.** `--chip` is optional on `probe`, `write`, and
+  `verify` — omit it and the tool syncs with the ROM bootloader, reads
+  the chip's magic-value register, and picks the right chip for you.
+  Pass `--chip` explicitly to override (still required for
+  `erase-info`, which never touches hardware).
+- **Stub loader.** Both native-USB and UART-bridge sessions upload the
+  real ESP-IDF RAM stub after syncing, switching from 1 KiB ROM-only
+  blocks to 16 KiB stub blocks. Falls back to ROM-only if the stub
+  upload doesn't succeed for some reason — flashing still works, just
+  slower.
+- **Automatic baud renegotiation on UART-bridge boards.** Once the stub
+  is running, the tool steps up through 921600 → 460800 → 230400 baud,
+  verifying each one actually holds (a cheap `sync()`) before trusting
+  it. If a candidate rate doesn't hold, it physically re-enters the ROM
+  bootloader and rebuilds the whole session at 115200 before trying the
+  next slower candidate — a bad guess costs a couple seconds, not the
+  whole flash. Settles on whatever your specific board/cable can
+  actually sustain, or stays at 115200 if nothing higher works. Native
+  USB CDC boards skip this entirely — there's no real UART clock
+  underneath USB CDC, so baud rate doesn't mean anything there.
+- **Live progress.** The flash progress bar streams in real time on the
+  no-root Termux fd-bootstrap path — earlier builds buffered progress
+  updates invisibly until the transfer finished, then dumped the whole
+  bar at once, which looked like a stall.
+- **Multi-file writes in one session.** `write` accepts one or more
+  `OFFSET:FILE` pairs and flashes all of them under a single USB
+  permission prompt / bootloader handshake.
+
+## Scope / limitations (read before filing an issue)
+
+- **No full-chip erase command.** `erase-info` explains why: an erase
+  that gets interrupted by a flaky OTG connection mid-operation has no
+  recovery path. Flash a full image (bootloader + partition table +
+  app) at the correct offsets instead of erasing first. `write --erase`
+  will erase exactly the bytes about to be overwritten via
+  `ERASE_REGION` if the ROM supports it, falling back silently to
+  `flash_begin`'s own per-block erase otherwise.
+- **Auto-detection is a best-effort heuristic**, not a guarantee for
+  every silicon revision — it reads the chip magic value at a register
+  address that's held true across ESP32/S2/S3/C3 for years, but an
+  unrecognized value means "pass `--chip` explicitly," not a guess.
+- **Stub data is vendored for more chips than are currently wired up**
+  (`esp32c2`, `c5`, `c6`, `c61`, `h2`, `h4`, `p4`, `s31` all have stub
+  binaries already sitting in `stub_flasher_data.py`), but
+  `CHIP_PARAMS`/`KNOWN_MAGIC`/`CHIP_CHOICES` only cover `esp32`,
+  `esp8266`, `esp32s2`, `esp32s3`, `esp32c3` today. Wiring up one of the
+  others means adding its real chip-magic value and SPI-attach params —
+  open an issue (or ask) with the specific chip if you need one.
+
+## Install
+
+```bash
+pkg update && pkg install python termux-api libusb
+pip install nrflash
+```
+
+`pip install nrflash` pulls in `pyusb` automatically. `termux-api` and
+`libusb` are system packages `pip` can't install for you — they still need
+`pkg install`, and the **Termux:API** app from
+[F-Droid](https://f-droid.org) (not the Play Store) must be installed
+separately for the no-root USB-permission flow to work at all.
+
+<details>
+<summary>Installing from source instead</summary>
+
+```bash
+git clone https://github.com/7wp81x/Termux-ESP-Flasher
+cd Termux-ESP-Flasher
+pip install .
+```
+</details>
+
+## Usage
+
+```bash
+chmod +x nrflash
+
+# --chip is optional everywhere except erase-info - omit it to auto-detect
+./nrflash probe
+./nrflash write --offset 0x0 firmware.bin
+
+# Still works if you want to force a specific chip
+./nrflash write --chip esp32c3 --offset 0x0 firmware.bin
+
+# Flash + MD5-verify against the device afterward
+./nrflash write --chip esp32s3 --offset 0x0 firmware.bin --verify
+
+# Flash a sub-image at a partition offset (e.g. app partition only)
+./nrflash write --offset 0x10000 app.bin
+
+# Flash bootloader + partition table + app in one session
+./nrflash write 0x0:bootloader.bin 0x8000:partitions.bin 0x10000:app.bin
+
+# Stand-alone MD5 check against a file already on disk
+./nrflash verify --chip esp32c3 --offset 0x0 firmware.bin
+
+# Explicitly erase the write range first via ERASE_REGION
+./nrflash write --offset 0x0 firmware.bin --erase
+
+# Stay in the bootloader after flashing instead of rebooting
+./nrflash write --offset 0x0 firmware.bin --no-reboot
+```
+
+First run on no-root Termux pops the same USB permission dialog every
+time — tap **OK**. The permission persists until you unplug.
+
+## What actually flashes — single binary vs. esptool's three images
+
+Real `esptool.py write_flash` usually takes **three** files at three
+offsets (bootloader, partition table, app), e.g.:
+
+```
+0x0      bootloader.bin
+0x8000   partition-table.bin
+0x10000  app.bin
+```
+
+`nrflash write` can take all three in one call (see the multi-file
+example above), or one file per invocation if you prefer. If your build
+only produces a single merged/combined `.bin` (PlatformIO can do this —
+check for a `firmware.factory.bin` or similar after `pio run`), one call
+at `0x0` is all you need.
+
+## How bootloader entry works
+
+- **UART-bridge boards** (CP2102/CH340/CH9102/FTDI) have real DTR/RTS
+  lines wired into EN/BOOT. `usb_device.py`'s `init_uart_bridge()`
+  configures the bridge's line coding and baud divisor via its own
+  vendor control transfers, then `uart_reset.py` pulses DTR/RTS in the
+  classic auto-reset pattern.
+- **Native USB CDC boards** have no bridge chip — the chip's internal
+  USB-Serial-JTAG peripheral watches the CDC class's
+  `SET_CONTROL_LINE_STATE` DTR/RTS bits in hardware and maps specific
+  transitions to an internal EN/BOOT reset, the software-only
+  equivalent of the same trick. That sequence lives in `cdc_reset.py`,
+  separate from `usb_device.py`'s bridge-chip logic since the two have
+  nothing in common at the wire level.
+
+## Files
+
+```
+src/nrflash/
+  __init__.py          package version
+  __main__.py          enables `python3 -m nrflash.cli`
+  cli.py               CLI: argv parsing, fd bootstrap, flash/verify/probe commands
+  rom_loader.py        SLIP framing + ROM bootloader command/response protocol,
+                        chip auto-detection, baud-change command
+  usb_device.py        USB backend detection, fd wrapping, UART-bridge register
+                        init/baud reprogramming, endpoint discovery
+  cdc_reset.py         native-USB-CDC bootloader entry/exit (DTR/RTS bit tricks)
+  uart_reset.py        UART-bridge bootloader entry/exit (DTR/RTS pulse pattern)
+  stub_flasher_data.py vendored ESP-IDF RAM stub binaries (Apache-2.0/MIT, Espressif)
+```
+
+`pip install nrflash` puts a `nrflash` console script on `PATH` — no
+`chmod +x`, no flat-directory requirement. Log/state files live under
+`~/.nrflash` (override with `NRFLASH_DATA_DIR`) rather than next to the
+installed package, since site-packages isn't guaranteed writable.
+
+## Troubleshooting
+
+**`probe` reports no response from bootloader**
+Some clone boards need the physical BOOT button held while plugging in,
+or the CH340/CP2102/FTDI wired to EN+GPIO0 for auto-reset to work at
+all. Try unplugging/replugging the OTG cable once before assuming it's a
+protocol problem.
+
+**Flashing is slow / progress bar looks stuck**
+On UART-bridge boards, check the log for a `Baud rate raised to ... and
+verified` line — if it's missing or stuck at 115200, your specific
+board/cable couldn't hold anything higher and the tool already fell back
+automatically. If the progress bar itself looks frozen and then jumps to
+100% all at once, make sure you're on a build with the live-progress fix
+(see "What's supported" above) rather than an older buffered-tail-thread
+build.
+
+**`Verify MISMATCH` after a successful-looking write**
+Don't trust a partial flash. Re-run `write --verify` rather than
+assuming the device is fine — a flaky OTG link or an unstable baud rate
+can drop bytes mid-transfer in a way that still returns "success" status
+on a given block.
+
+## Legal
+
+For use on hardware you own. Flashing arbitrary firmware to a device you
+don't own or have written permission to modify can violate warranty
+terms or, depending on the device and jurisdiction, the law.