mtjk

mtjk is a maintained fork of the Meshtastic Python library. It keeps the existing meshtastic Python import namespace while publishing under a separate package name so the work maintained here can be installed independently.

The fork began as an exploration of BLE connection reliability for MMRelay. What initially looked like a transport-specific problem turned out to touch lifecycle ownership, concurrency, typing, dependency management, testability, and several large implementation boundaries. The work expanded incrementally and was repeatedly cleaned up and tested rather than carried as one very large upstream patch. Over time that working branch became the maintained fork that exists today.

The upstream project remains the primary Meshtastic Python project. The goal of this fork is narrower: maintain the changes developed here, keep them coherent and well-tested, preserve familiar Meshtastic Python usage where practical, and make isolated improvements available for upstreaming when they can be separated cleanly.

Project goals

The main priorities are:

• preserve the established Meshtastic Python API and import namespace where practical;
• improve connection and lifecycle reliability, especially for long-running integrations;
• keep concurrency, resource ownership, and failure handling explicit;
• maintain strong typing, linting, tests, and dependency hygiene;
• track current firmware behavior, including Meshtastic 2.8 protocol and CLI features;
• keep internal architecture maintainable without forcing downstream callers to follow those internal changes.

The repository does not currently accept external pull requests. General Meshtastic community development should continue to go to meshtastic/python. Issues that are specific to mtjk can be reported in this repository.

Compatibility

mtjk is designed to be usable as a replacement dependency for applications that already use Meshtastic Python, but it does not claim perfect behavioral identity with every upstream release.

Compatibility that is intentionally maintained includes:

• import meshtastic remains the Python package namespace;
• mtjk is the preferred CLI command, while the historical meshtastic command remains installed as a silent compatibility entry point;
• established Node, MeshInterface, BLE, utility, and configuration entry points are guarded by API and behavioral compatibility tests;
• historical camelCase and documented legacy aliases remain callable where the compatibility policy says they do;
• newer structured BLE exceptions remain catchable as BLEInterface.BLEError, including the historical .kind classification contract.

There are also deliberate behavioral differences where retaining the old behavior would make the library harder or less safe to embed. The most important example is error handling: library code generally raises exceptions instead of terminating the host process with sys.exit(). Safer defaults and internal logging behavior may also differ from older upstream releases.

Local CLI configuration writes are verified against fresh device state. After a local --set batch is written and committed, and after a local --configure reconnect/reload, the CLI re-reads the affected LocalConfig/LocalModuleConfig sections from the device and compares them to the requested values. A value mismatch, a section that never reloads, or a failed verification readback exits nonzero with an error naming the affected fields/sections (for example ERROR: --set was sent, but fresh device state reports different values for: <fields>. The device did not apply the requested value(s). or ERROR: configuration was sent, but fresh device state did not confirm the requested settings.); a verified apply prints a confirming line. --dry-run never writes or verifies, noProto --set runs skip verification (exit 0) and never report a device-verified success, and remote (--dest) targets keep their existing behavior. This changes CLI exit behavior only; public library setters keep their timing and return values.

See COMPATIBILITY.md for the maintained compatibility contract and known behavioral differences.

Notable work maintained here

The exact change set evolves with the upstream project, but the larger areas of work include:

• BLE connection, reconnect, shutdown, ownership, and notification lifecycle hardening;
• request/response correlation and concurrency fixes for long-running clients;
• decomposition of large MeshInterface, Node, CLI, and BLE implementation paths behind compatibility facades;
• stronger typing, linting, static analysis, API baselines, and regression coverage;
• dependency and CI cleanup;
• current firmware protocol support and validation, including Meshtastic 2.8 features;
• simplified Trusted Publisher-based PyPI releases.

For current design details, see ARCHITECTURE.md. BLE-specific implementation and integration notes live in BLE.md.

Installation

CLI installation with pipx

pipx is recommended for command-line use so the package runs in an isolated environment.

If upstream meshtastic is already installed in that environment, remove it first. The two distributions intentionally share the meshtastic Python namespace and historical CLI command, so they are not designed to coexist in one environment.

pipx uninstall meshtastic || true
pipx install mtjk

Verify the installation:

mtjk --version

The package installs both mtjk and meshtastic console commands. New shell usage should prefer mtjk; existing automation that invokes meshtastic continues to use the same implementation.

Install the latest develop

pipx uninstall mtjk || true
pipx install "git+https://github.com/jeremiah-k/mtjk.git@develop"

Upgrade or uninstall

pipx upgrade mtjk
pipx uninstall mtjk

CLI installation with uv

uv's tool installer also installs the CLI in an isolated environment.

uv tool install mtjk
mtjk --version

Upgrade with uv tool upgrade mtjk, or uninstall with uv tool uninstall mtjk. To install the unreleased develop branch, use:

uv tool install "git+https://github.com/jeremiah-k/mtjk.git@develop"

If mtjk is not found after installation, run uv tool update-shell and restart your shell. For development inside a cloned checkout, use the project environment described in CONTRIBUTING.md.

Using mtjk as a Python dependency

The distribution name is mtjk, but the import namespace remains meshtastic.

Use mtjk in dependency declarations:

mtjk

or, for the unreleased develop branch:

mtjk @ git+https://github.com/jeremiah-k/mtjk.git@develop

Install the dependency into your application's environment with its package manager: for example, uv add mtjk in a uv project, or python -m pip install mtjk inside an activated virtual environment. The isolated environments created by pipx and uv tool install are for CLI use and do not provide imports to a separate application.

The CLI niceties (segno for --qr, print-color, argcomplete, wcwidth) are core dependencies — a plain mtjk install gets the full CLI, including QR rendering. The cli extra is still accepted as a no-op, so mtjk[cli] keeps working for existing scripts.

--qr, --qr-all, and --qr-contact use compact Unicode blocks. Interactive output selects the strongest error correction that fits the terminal while preserving the QR quiet zone. If no complete code fits, enlarge the terminal or open the displayed URL. Redirected output keeps maximum error correction; output encodings without block glyphs use ANSI rendering.

Python code continues to use the familiar imports:

import meshtastic
import meshtastic.serial_interface

with meshtastic.serial_interface.SerialInterface() as interface:
    interface.sendText("hello mesh")

There is intentionally no import mtjk package.

Documentation

The maintained project documentation is intentionally small:

• ARCHITECTURE.md — current architecture and design boundaries;
• COMPATIBILITY.md — compatibility policy, aliases, and intentional behavioral differences;
• CONTRIBUTING.md — local maintenance workflow and CI checks;
• BLE.md — detailed BLE architecture and integration guidance;
• ADMIN_RESPONSE_CONTRACTS.md — admin request/response invariants;
• LOCKDOWN.md — lockdown/authentication behavior;
• REGION_PRESETS.md — region-preset API behavior.

Older refactor plans, dependency campaign notes, and device-specific manual test logs are intentionally not maintained as active documentation; Git history is the source for that development history.

Support

Report mtjk-specific issues here:

• https://github.com/jeremiah-k/mtjk/issues

Please do not file mtjk-specific issues with upstream maintainers.

Release notes for maintainers

• Versions follow the upstream version with a .postN suffix, for example 2.7.11.post8.
• Publish a GitHub release with tag vX.Y.Z[.postN] (or the same version without the leading v).
• The PyPI workflow verifies that the release tag matches pyproject.toml, runs the standard python -m build, and publishes the generated source and wheel distributions with PyPI Trusted Publishing.
• The PyPI Trusted Publisher is configured for jeremiah-k/mtjk + .github/workflows/pypi-publish.yml + pypi-release.