102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# MicroMesh
|
|
|
|
MicroMesh is a small, dependency-free Meshtastic client for MicroPython. It talks to a
|
|
Meshtastic device over its serial API and implements the protobuf wire format directly,
|
|
so `google.protobuf`, threads, and `pyserial` are not required.
|
|
|
|
The initial release supports:
|
|
|
|
- serial `ToRadio` / `FromRadio` framing and resynchronization;
|
|
- the configuration handshake and a small in-memory node list;
|
|
- text, arbitrary data, and position packets;
|
|
- routing acknowledgements, node/user data, waypoints, and device metrics;
|
|
- familiar generated-protobuf methods: `SerializeToString`, `ParseFromString`,
|
|
`CopyFrom`, `HasField`, `ClearField`, and `WhichOneof`;
|
|
- preservation of unknown protobuf fields for forward compatibility.
|
|
|
|
This is intentionally not a complete replacement for the desktop
|
|
[`meshtastic`](https://github.com/meshtastic/python) package. Configuration and admin
|
|
messages are currently returned as raw encoded bytes.
|
|
|
|
## Install
|
|
|
|
From a checkout of this repository, install with a current `mpremote`:
|
|
|
|
```sh
|
|
mpremote mip install package.json
|
|
```
|
|
|
|
Alternatively, copy the `micromesh` directory to `/lib` on the board. After this
|
|
repository is published on GitHub it can also be installed as
|
|
`mpremote mip install github:ORG/micromesh`.
|
|
|
|
It can also be installed on CPython for development:
|
|
|
|
```sh
|
|
python -m pip install .
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```python
|
|
from machine import UART, Pin
|
|
from micromesh import PortNum, SerialInterface
|
|
|
|
uart = UART(1, baudrate=115200, tx=Pin(17), rx=Pin(16), timeout=0)
|
|
|
|
def received(packet):
|
|
if packet.WhichOneof("payload_variant") != "decoded":
|
|
return
|
|
if packet.decoded.portnum == PortNum.TEXT_MESSAGE_APP:
|
|
print("from !%08x:" % packet.from_, packet.decoded.payload.decode())
|
|
|
|
mesh = SerialInterface(uart, on_packet=received)
|
|
mesh.connect()
|
|
mesh.sendText("hello mesh")
|
|
|
|
while True:
|
|
mesh.poll()
|
|
```
|
|
|
|
The UART baud rate and pins depend on the attached Meshtastic device. `poll()` is
|
|
non-blocking when the UART is configured with `timeout=0`.
|
|
|
|
Direct messages accept either an integer or Meshtastic's hexadecimal node ID:
|
|
|
|
```python
|
|
mesh.sendText("hello", destinationId="!a1b2c3d4", wantAck=True)
|
|
mesh.sendPosition(45.5152, -122.6784, altitude=15)
|
|
mesh.sendData(b"custom", portNum=PortNum.PRIVATE_APP)
|
|
```
|
|
|
|
## Protobufs
|
|
|
|
Messages can be used without a radio:
|
|
|
|
```python
|
|
from micromesh import Data, PortNum
|
|
|
|
data = Data(portnum=PortNum.TEXT_MESSAGE_APP, payload=b"hello")
|
|
encoded = data.SerializeToString()
|
|
decoded = Data().ParseFromString(encoded)
|
|
```
|
|
|
|
Generated-module-style imports are available as `micromesh.mesh_pb2` and
|
|
`micromesh.portnums_pb2` for easier porting from the desktop library.
|
|
|
|
Only the commonly useful schemas are modeled. Unknown fields survive a decode/encode
|
|
round trip, but their contents are not interpreted. A field named `from` is accessed as
|
|
`packet.from_` because `from` is a Python keyword.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
python -m unittest discover -s tests
|
|
```
|
|
|
|
The API protocol is defined by the
|
|
[`meshtastic/protobufs`](https://github.com/meshtastic/protobufs) project. Update the
|
|
field declarations in `micromesh/messages.py` when adopting newer schemas.
|
|
|
|
`manifest.py` is also included for freezing the package into custom MicroPython firmware.
|