mtjk

mtjk is a separately published distribution of the Meshtastic Python library, maintained while changes are validated and selectively upstreamed.

Work began in September 2025 to stabilize connection interfaces and message delivery for mmrelay. The modernization work keeps existing Meshtastic Python usage compatible:

• package import namespace remains meshtastic
• preferred CLI command is mtjk
• historical meshtastic CLI command remains available as a compatibility entry point
• existing API compatibility is intentionally preserved

It is intended to be a drop-in, backward-compatible replacement for upstream.

Project Status

This is a temporary fork of meshtastic/python. It exists to ship fixes and improvements while they are validated and upstreamed selectively.

This repository does not accept pull requests. Community development efforts should be directed to the upstream project. If you find a fix or improvement here that you would like to carry upstream, please do so.

Notable Changes

• major BLE and interface internals were refactored for maintainability while keeping compatibility shims in place
• concurrency and lifecycle paths were tightened to reduce race-condition and shutdown edge cases
• CI and release workflows were modernized, including Trusted Publisher-based PyPI release flow

For technical details, see:

• REFACTOR_PROGRAM.md: rationale and early change log for the major refactor work maintained here.
• COMPATIBILITY.md: canonical inventory of compatibility shims, deprecations, and migration mapping.
• CONTRIBUTING.md: local setup, CI-equivalent checks, and contributor workflow conventions.

Install the CLI (recommended: pipx)

pipx is recommended for CLI tools so each app gets an isolated environment.

1) Remove prior installs first (recommended)

If you previously installed upstream meshtastic, remove it before installing mtjk.

# If installed with pipx:
pipx uninstall meshtastic || true

# If installed with pip in a Python environment:
python3 -m pip uninstall -y meshtastic

2) Install mtjk

pipx install mtjk

3) Verify

mtjk --version
# mtjk 2.7.11.post5   # example output; version varies by release

The package installs both mtjk and meshtastic. New shell usage should prefer mtjk; the meshtastic command is retained as a silent compatibility entry point for existing workflows. No shell alias is required because both commands are installed.

Do not install the upstream meshtastic distribution alongside mtjk in the same environment: the two distributions share both the meshtastic Python namespace and the historical CLI name and are not designed to coexist. Keep them in separate virtual/pipx environments and invoke mtjk explicitly.

Install latest from Git (develop)

To install the latest unreleased version from this repository (clean install):

# If you previously installed upstream via pipx, remove it first:
pipx uninstall meshtastic || true

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

Upgrade / Uninstall

pipx upgrade mtjk
pipx uninstall mtjk

Developer Usage (existing Meshtastic API)

Dependency name is mtjk, but import namespace remains meshtastic.

Important:

• If your dependency spec says meshtastic, you will install upstream.
• Use mtjk in dependency specs for this package.
• The package does not provide import mtjk.

requirements.txt

mtjk

Unreleased from Git:

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

If you need optional CLI extras in a dependency spec:

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

pyproject.toml (PEP 621)

[project]
dependencies = [
  "mtjk",
]

Unreleased from Git:

[project]
dependencies = [
  "mtjk @ git+https://github.com/jeremiah-k/mtjk.git@develop",
]

setup.cfg

[options]
install_requires =
    mtjk

Unreleased from Git:

[options]
install_requires =
    mtjk @ git+https://github.com/jeremiah-k/mtjk.git@develop

Python import (unchanged)

import meshtastic
import meshtastic.serial_interface

interface = meshtastic.serial_interface.SerialInterface()
interface.sendText("hello mesh")
interface.close()

Structured traceroute results

Library callers can request a traceroute without parsing CLI-oriented log output:

from meshtastic.serial_interface import SerialInterface

with SerialInterface() as interface:
    result = interface.requestTraceRoute("!ba4bf9d0", hopLimit=5)

for hop in result.route_towards:
    print(hop.node_id, hop.snr_db)

Each route contains the source and destination plus any intermediate hops. snr_db describes the link into a hop and is None when firmware omits a complete SNR sequence. route_back is None unless firmware reports a reverse route; incomplete reverse SNR data preserves the route with unknown link values. The historical sendTraceRoute() API and its logging behavior remain unchanged.

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 (Maintainers)

• Versions match upstream releases with a .postN suffix (e.g., 2.7.8.post1 is the first mtjk release based on upstream 2.7.8).
• Create a GitHub release with tag vX.Y.Z[.postN] (or push the tag manually). This triggers the PyPI publish workflow via Trusted Publisher.
• Trusted Publisher workflow expects the git tag version to match pyproject.toml exactly.
• Supported tag formats are vX.Y.Z... or X.Y.Z... (both map to the same package version check).
• PyPI Trusted Publisher must match this repo/workflow/environment tuple: jeremiah-k/mtjk + .github/workflows/pypi-publish.yml + pypi-release.