Metadata-Version: 2.4
Name: mtjk
Version: 2.7.11.post8
Summary: Python API & client shell for talking to Meshtastic devices
Author: Meshtastic Developers (upstream project authors)
License-Expression: GPL-3.0-only
License-File: LICENSE.md
Requires-Dist: pyserial>=3.5,<4.0
Requires-Dist: protobuf>=5.29.5
Requires-Dist: typing-extensions>=4.15.0 ; python_full_version < '3.13'
Requires-Dist: tabulate>=0.10.0,<0.11.0
Requires-Dist: requests>=2.33.0,<3.0.0
Requires-Dist: pyyaml>=6.0.1,<7.0.0
Requires-Dist: pypubsub>=4.0.7,<5.0.0
Requires-Dist: bleak>=3.0.1,<4.0.0
Requires-Dist: packaging>=26.0,<27.0
Requires-Dist: argcomplete>=3.5.2,<4.0.0
Requires-Dist: segno>=1.6.6,<2.0.0
Requires-Dist: print-color>=0.4.6,<0.5.0
Requires-Dist: wcwidth>=0.9.0,<0.10.0
Requires-Dist: dash>=4.0.0,<5.0.0 ; extra == 'analysis'
Requires-Dist: dash-bootstrap-components>=2.0.4,<3.0.0 ; extra == 'analysis'
Requires-Dist: parse>=1.20.2,<2.0.0 ; extra == 'analysis'
Requires-Dist: platformdirs>=4.2.2,<5.0.0 ; extra == 'analysis'
Requires-Dist: plotly>=7.0.0,<8.0.0 ; extra == 'analysis'
Requires-Dist: pandas>=2.2.2,<3.0.0 ; extra == 'analysis'
Requires-Dist: pandas-stubs>=2.3.3.260113,<3.0.0.0 ; extra == 'analysis'
Requires-Dist: pyarrow>=25.0.0,<26.0.0 ; extra == 'analysis'
Maintainer: Jeremiah K.
Maintainer-email: Jeremiah K. <jeremiahk@gmx.com>
Requires-Python: >=3.11, <3.15
Project-URL: Homepage, https://github.com/jeremiah-k/mtjk
Project-URL: Repository, https://github.com/jeremiah-k/mtjk
Provides-Extra: analysis
Provides-Extra: cli
Description-Content-Type: text/markdown

# 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](https://github.com/jeremiah-k/meshtastic-matrix-relay).
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](https://github.com/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](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](ARCHITECTURE.md). BLE-specific
implementation and integration notes live in [BLE.md](BLE.md).

## Installation

### CLI installation with pipx

[pipx](https://pipx.pypa.io/stable/) 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.

```bash
pipx uninstall meshtastic || true
pipx install mtjk
```

Verify the installation:

```bash
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`

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

### Upgrade or uninstall

```bash
pipx upgrade mtjk
pipx uninstall mtjk
```

### CLI installation with uv

[uv's tool installer](https://docs.astral.sh/uv/guides/tools/) also installs
the CLI in an isolated environment.

```bash
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:

```bash
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](CONTRIBUTING.md#local-setup-and-validation).

## Using mtjk as a Python dependency

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

Use `mtjk` in dependency declarations:

```text
mtjk
```

or, for the unreleased `develop` branch:

```text
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:

```python
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](ARCHITECTURE.md) — current architecture and design
  boundaries;
- [COMPATIBILITY.md](COMPATIBILITY.md) — compatibility policy, aliases, and
  intentional behavioral differences;
- [CONTRIBUTING.md](CONTRIBUTING.md) — local maintenance workflow and CI checks;
- [BLE.md](BLE.md) — detailed BLE architecture and integration guidance;
- [ADMIN_RESPONSE_CONTRACTS.md](ADMIN_RESPONSE_CONTRACTS.md)
  — admin request/response invariants;
- [LOCKDOWN.md](LOCKDOWN.md) — lockdown/authentication
  behavior;
- [REGION_PRESETS.md](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`.
