Akita Meshtastic ZModem

Version: 1.1.0

Adds reliable, targeted node-to-node file transfers to Meshtastic LoRa networks.

Contents:

• AkitaMeshZmodem — Arduino library embedding a non-blocking ZModem engine.
• ZmodemModule — Meshtastic firmware module for in-firmware operation.

License: GNU GPLv3 — see LICENSE.

Features

• Zero External Dependencies: The ZModem protocol stack is entirely built-in (src/utility/ZModemEngine), eliminating reliance on external, unstable, or missing ZModem libraries.
• Non-Blocking Operation: The implementation is designed to run seamlessly within the main Meshtastic firmware loop, ensuring the device remains responsive, routing packets, and managing the mesh network during transfers.
• Targeted Sending: Files are sent directly to a specified Node ID, not broadcast across the entire mesh, which is efficient and network-friendly.
• Reliable Protocol: Utilizes simplified ZModem state handling and CRC checks optimized for robust, 8-bit clean LoRa links.
• Dedicated Port Handling: Uses separate, configurable Meshtastic PortNums for command initiation and data transmission to prevent conflicts.
• Filesystem Agnostic: Uses the standard Arduino FS API for compatibility with SPIFFS, LittleFS, or SD cards.

Requirements

• Hardware: Meshtastic-compatible devices (ESP32-based recommended) with sufficient flash memory for the firmware and a filesystem (SPIFFS/LittleFS) to store files.
• Required Arduino Libraries (Minimal):
  • Meshtastic (Official Meshtastic device library/firmware source)
  • StreamUtils (A common utility library, included in PlatformIO/Arduino)
  • FS (Part of the ESP32 core)

Installation

Option 1: Using the Library in a Custom Sketch

1. Install Dependencies: Ensure Meshtastic and StreamUtils are installed via the Arduino Library Manager or PlatformIO.
2. Install AkitaMeshZmodem Library:
   • PlatformIO (Recommended): Add the library directly to your platformio.ini dependencies:

     lib_deps =
         meshtastic/Meshtastic
         bblanchon/ArduinoStreamUtils
         https://github.com/AkitaEngineering/Meshtastic-Zmodem.git

   • Arduino IDE: Download this repository as a ZIP and install it via the Arduino IDE's Sketch -> Include Library -> Add .ZIP Library... option.

Option 2: Integrating the Module into Meshtastic Firmware

This is the preferred method for running file transfers as a service and requires building the Meshtastic firmware from source using PlatformIO.

1. Prepare Files: Copy the files from the src/ directory into a library folder (lib/Akita_Meshtastic_Zmodem) within the Meshtastic firmware source tree.
2. Install Module: Copy src/modules/ZmodemModule.h and src/modules/ZmodemModule.cpp into the Meshtastic firmware's src/modules/ directory.
3. Register Module: Edit the main firmware file (src/mesh-core.cpp or similar) to include the module header and instantiate the module, allowing it to hook into the main loop:

   #include "modules/ZmodemModule.h"
   // ...
   modules.push_back(new ZmodemModule(*this));

Usage

Control is handled by sending specific text commands to the device on the Command Port (AKZ_ZMODEM_COMMAND_PORTNUM, default 250).

Command Structure

Action	Format	Example (using CLI)
Start Send	SEND:!NodeID:/local/file.bin	meshtastic --sendtext "SEND:!a1b2c3d4:/test.txt" --portnum 250
Start Receive	RECV:/save/path.bin	meshtastic --sendtext "RECV:/received.bin" --portnum 250

API Reference (Library Integration)

When integrating into custom code:

• begin(mesh, Filesystem, &Serial): Initialize the engine and set up the transport streams.
• loop(): Must be called continuously in your main loop to process the ZModem state machine.
• processDataPacket(MeshPacket& packet): CRITICAL. This method is used to push raw data packets received on the Data Port (AKZ_ZMODEM_DATA_PORTNUM) directly into the ZModem engine's input buffer.

Additional tools and testing

Two helper scripts have been added under tools/ to simplify exercising the module on a host machine:

• serial_proxy.py – creates a PTY and proxies it to a real serial device. Run your host-side XMODEM/SZ/SX tool against the PTY to talk to the board.
• auto_xmodem_test.py – automation harness that invokes sz --xmodem and validates the received file. Useful for CI or sanity checks without hardware.

The internal ZModem engine now includes XMODEM compatibility (CRC or checksum), automatic retransmit/backoff, and a cached‑block sender mode to avoid file seeks on retry.

Building without Meshtastic

The PlatformIO project has been configured to allow the code to compile with only stubbed versions of the Meshtastic and StreamUtils libraries (see lib/…); this makes it possible to verify the ZModem engine builds even when the real dependencies are not available. To perform a full build the real Meshtastic package from the Arduino registry is required.

Documentation updates (recent)

• Fixed several protocol/parser bugs in the internal ZModem engine (src/utility/ZModemEngine.cpp) including proper ZDLE-escaping and header scanning for robustness over noisy links.
• Resolved incorrect TransferState mappings and stream-handling issues in the library wrapper (src/AkitaMeshZmodem.cpp).
• The example sketch examples/Basic_Transfer/Basic_Transfer.ino was corrected for proper packet handling and command parsing.
• Stub headers and library stubs were improved so the library can be compiled and verified with PlatformIO even when the full Meshtastic firmware is not present.

These fixes were verified by building the project with PlatformIO on ESP32 (env: esp32dev). See the quick build steps in USAGE.md.