Metadata-Version: 2.3
Name: mmqtt
Version: 1.1.3
Summary: This library may be useful for testing Meshtastic networks connected to an MQTT server.
License: GPL-3.0-only
Author: Ben Lipsey
Author-email: ben@pdxlocations.com
Requires-Python: >=3.9,<3.14
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: cryptography (>=43.0.3,<44.0.0)
Requires-Dist: meshtastic (>=2.6.0,<3.0.0)
Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
Project-URL: Homepage, https://github.com/pdxlocations/mmqtt
Project-URL: Issues, https://github.com/pdxlocations/mmqtt/issues
Description-Content-Type: text/markdown

This project is useful for testing Meshtastic networks connected to an MQTT server. Functions can be called via the `mmqtt` command or imported and used programmatically.

# Installation

```bash
pip install mmqtt
```


# Functions (see examples for further information):

```python
from mmqtt import (
    send_nodeinfo,
    send_device_telemetry,
    send_position,
    send_environment_metrics,
    send_power_metrics,
    send_health_metrics,
    send_text_message,
)

send_nodeinfo(node_id, long_name, short_name)
send_device_telemetry()
send_position(latitude, longitude)
send_environment_metrics()
send_power_metrics()
send_health_metrics()
send_text_message("text")
```

Optional Arguments for all message types:

- to=INT
- hop_limit=INT
- hop_start=INT
- want_ack=BOOL
- want_response=BOOL

Example:
```bash
send_text_message("Happy New Year" to=12345678, hop_limit=5)
```

Supported keyword arguments for nodeinfo:

- id (required)
- long_name (required)
- short_name (required)
- hw_model
- is_licensed
- role
- public_key

Supported keyword arguments for device metrics:

 - battery_level
 - voltage
 - channel_utilization
 - air_util_tx
 - uptime_seconds

Supported keyword arguments for position metrics:

- latitude (required)
- longitude (required)
- latitude_i
- longitude_i
- altitude
- precision_bits
- HDOP
- PDOP
- VDOP
- altitude_geoidal_separation
- altitude_hae
- altitude_source
- fix_quality
- fix_type
- gps_accuracy
- ground_speed
- ground_track
- next_update
- sats_in_view
- sensor_id
- seq_number
- timestamp
- timestamp_millis_adjust

Supported keyword arguments for environment metrics:

- temperature
- relative_humidity
- barometric_pressure
- gas_resistance
- voltage
- current
- iaq
- distance
- ir_lux
- lux
- radiation
- rainfall_1h
- rainfall_24h
- soil_moisture
- soil_temperature
- uv_lux
- weight
- white_lux
- wind_direction
- wind_gust
- wind_lull
- wind_speed

Supported keyword arguments for power metrics:

 - ch1_voltage
 - ch1_current
 - ch2_voltage
 - ch2_current
 - ch3_voltage
 - ch3_current

Supported keyword arguments for health metrics:
 
 - heart_bpm
 - spO2
 - temperature

# Command Line Interface:

```bash
mmqtt --args
```

## Available arguments:

```
  -h, --help             show this help message and exit
  --config CONFIG        Path to the config file
  --message MESSAGE      Message to send. You can use this multiple times.
  --message-file FILE    Path to a file containing messages, one per line
  --nodeinfo             Send NodeInfo from my config
  --telemetry            Send telemetry from my config
  --lat LAT              Latitude coordinate
  --lon LON              Longitude coordinate
  --alt ALT              Altitude
  --precision PRECISION  Position Precision
  --position             Send position from config unless overridden by --lat, --lon, or --alt
  --listen               Stay connected and listen for incoming MQTT messages
```

## Examples:

To publish a message to the broker using settings defined in `config-example.json`:
```
mmqtt --message "I need an Alpinist"
```

To publish a message to the broker using settings defined in `my-config.json`:
```
mmqtt --config "my-config.json" --message "I need an Alpinist"
```

## Example config.json:

```yaml
{
  "mqtt": {
    "broker": "mqtt.meshtastic.org",
    "port": 1883,
    "user": "meshdev",
    "password": "large4cats",
    "root_topic": "msh/US/2/e/"
  },
  "channel": {
    "preset": "LongFast",
    "key": "AQ=="
  },
  "nodeinfo": {
    "id": "!deadbeef",
    "short_name": "q",
    "long_name": "mmqtt",
    "hw_model": 255
  },
  "position": {
    "lat": 45.43139,
    "lon": -122.37354,
    "alt": 9,
    "location_source": "LOC_MANUAL",
    "precision": 16
  },
  "telemetry": {
    "battery_level": 99,
    "voltage": 4.0,
    "chutil": 3,
    "airtxutil": 1,
    "uptime": 420
  },
  "message": {
    "text": "Happy New Year",
    "destination_id": "4294967295"
  },
  "mode": {
    "listen": "False"
  }
}
  ```

## Build and install locally:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install poetry
poetry build
pip install dist/mmqtt*.whl
```

## Install in development (editable) mode:
```bash
pip install -e .
```
