Metadata-Version: 2.4
Name: mtjk
Version: 2.7.9.post1
Summary: Python API & client shell for talking to Meshtastic devices
License: GPL-3.0-only
License-File: LICENSE.md
Author: Meshtastic Developers (upstream project authors)
Maintainer: Jeremiah K.
Maintainer-email: jeremiahk@gmx.com
Requires-Python: >=3.10,<3.15
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: analysis
Provides-Extra: cli
Provides-Extra: tunnel
Requires-Dist: argcomplete (>=3.5.2,<4.0.0) ; extra == "cli"
Requires-Dist: bleak (>=3.0.1,<4.0.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: dotmap (>=1.3.30,<2.0.0) ; extra == "cli"
Requires-Dist: packaging (>=26.0,<27.0)
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: plotly (>=6.6.0,<7.0.0) ; extra == "analysis"
Requires-Dist: print-color (>=0.4.6,<0.5.0) ; extra == "cli"
Requires-Dist: protobuf (>=5.29.5)
Requires-Dist: pypubsub (>=4.0.7,<5.0.0)
Requires-Dist: pyqrcode (>=1.2.1,<2.0.0) ; extra == "cli"
Requires-Dist: pyserial (>=3.5,<4.0)
Requires-Dist: pytap2 (>=2.3.0,<3.0.0) ; extra == "tunnel"
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: requests (>=2.33.0,<3.0.0)
Requires-Dist: tabulate (>=0.10.0,<0.11.0)
Requires-Dist: typing-extensions (>=4.15.0) ; python_version < "3.13"
Requires-Dist: wcwidth (>=0.8.0,<0.9.0) ; extra == "cli"
Project-URL: Homepage, https://github.com/jeremiah-k/mtjk
Project-URL: Repository, https://github.com/jeremiah-k/mtjk
Description-Content-Type: text/markdown

# 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](https://github.com/jeremiah-k/meshtastic-matrix-relay).
The modernization work keeps existing Meshtastic Python usage compatible:

- package import namespace remains `meshtastic`
- CLI command remains `meshtastic`
- 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](https://github.com/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](https://github.com/meshtastic/python). 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](REFACTOR_PROGRAM.md): rationale and early change log for the major refactor work maintained here.
- [COMPATIBILITY.md](COMPATIBILITY.md): canonical inventory of compatibility shims, deprecations, and migration mapping.
- [CONTRIBUTING.md](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`.

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

```bash
pipx install mtjk
```

### 3) Verify

```bash
meshtastic --version
```

### Install latest from Git (`develop`)

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

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

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

```text
mtjk
```

Unreleased from Git:

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

If you need optional CLI extras in a dependency spec:

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

### pyproject.toml (PEP 621)

```toml
[project]
dependencies = [
  "mtjk",
]
```

Unreleased from Git:

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

### setup.cfg

```ini
[options]
install_requires =
    mtjk
```

Unreleased from Git:

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

### Python import (unchanged)

```python
import meshtastic
import meshtastic.serial_interface

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

## 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`.

