Metadata-Version: 2.4
Name: meshconsole
Version: 2.2.0
Summary: A powerful CLI and web interface for Meshtastic mesh networking devices
Project-URL: Homepage, https://github.com/m9wav/MeshConsole
Project-URL: Repository, https://github.com/m9wav/MeshConsole
Project-URL: Issues, https://github.com/m9wav/MeshConsole/issues
Author-email: M9WAV <m9wav@hackers.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: amateur-radio,ham,lora,mesh,meshtastic,networking,radio
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Communications
Classifier: Topic :: Communications :: Ham Radio
Requires-Python: >=3.9
Requires-Dist: flask-cors>=4.0.0
Requires-Dist: flask>=2.0.0
Requires-Dist: meshtastic>=2.0.0
Requires-Dist: protobuf>=3.20.0
Requires-Dist: pypubsub>=4.0.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.png" alt="MeshConsole" width="400"/>
</p>

<p align="center">
  <strong>A web-based monitoring and control dashboard for Meshtastic mesh networks.</strong>
</p>

<p align="center">
  <a href="https://m9wav.uk/">m9wav.uk</a>
</p>

---

So I got really into Meshtastic after picking up a couple of LoRa radios and wanted a way to monitor my mesh network from my computer. The official app is fine but I wanted something I could leave running on a server, log everything to a database, and maybe poke at later.

This started as a quick script and... well, it grew. Now it's got a web UI and everything. Figured I'd clean it up and share it.

## What it does

- Connects to your Meshtastic device over **USB or TCP/IP** (WiFi)
- Logs all packets to a SQLite database
- Shows a live web dashboard with all the node activity
- Lets you send messages and run traceroutes from the web UI
- Exports your data to JSON/CSV if you want to analyze it elsewhere
- Auto-reconnects if the connection drops

The web interface shows positions on a map, telemetry data (battery, signal strength, etc), and you can see message history. Pretty handy for debugging mesh issues.

## Setup

```bash
pip install -r requirements.txt
cp config.example.ini config.ini
```

Edit `config.ini` with your setup. The main thing is picking USB or TCP:

```ini
[Device]
# "usb" for plugged-in device, "tcp" for network
connection_type = usb

# Only needed for TCP mode
ip = 192.168.1.100

# Usually leave blank for auto-detect, but you can specify
# serial_port = /dev/cu.usbserial-0001
```

If you're using TCP, your device needs to have WiFi enabled and you need to know its IP.

## Running it

**Listen for packets (with web interface):**
```bash
python3 meshconsole.py listen --web
```

Then open http://localhost:5050 in your browser.

**Just listen (no web):**
```bash
python3 meshconsole.py listen --verbose
```

**List nodes your device knows about:**
```bash
python3 meshconsole.py nodes
```

**Send a message:**
```bash
python3 meshconsole.py send --dest !12345678 --message "hey there"
```

**Traceroute to a node:**
```bash
python3 meshconsole.py traceroute --dest !12345678
```

You can also force USB or TCP mode from the command line regardless of what's in your config:

```bash
python3 meshconsole.py listen --usb --web
python3 meshconsole.py nodes --usb --port /dev/cu.usbserial-0001
```

## The web dashboard

When you run with `--web`, you get a dashboard at port 5050. It shows:

- Live packet feed (updates automatically)
- Node list with signal info
- Map with positions (if nodes are reporting GPS)
- Stats about your network

There's a password for sending messages/traceroutes so you can leave the dashboard open without worrying about someone messing with your network. Set it in `config.ini` under `[Security]`. Leave `auth_password` blank if you don't care.

## Files

After running for a while you'll have:
- `meshtastic_messages.db` - SQLite database with all your packets
- `meshtastic_tool.log` - Logs (rotates automatically)

The database is useful if you want to do your own analysis. The `packets` table has everything including the full raw packet data as JSON.

## Exporting data

```bash
python3 meshconsole.py export --format json
python3 meshconsole.py export --format csv
```

Spits out `meshtastic_data.json` or `meshtastic_data.csv`.

## Troubleshooting

**Can't connect via USB:**
- Make sure you have the right drivers (CP2102/CH340/etc)
- Check `ls /dev/cu.usb*` (Mac) or `ls /dev/ttyUSB*` (Linux) to see if the device shows up
- Try specifying the port explicitly with `--port`

**Can't connect via TCP:**
- Make sure WiFi is enabled on your Meshtastic device
- Check you can ping the IP
- The device uses port 4403 by default

**Web interface not loading:**
- Check if port 5050 is already in use
- Try a different port in `config.ini` under `[Web]`

**Seeing your own messages in the log:**
- Shouldn't happen - the tool auto-detects your local node and filters it out
- If it's not working, check the logs for the detected node ID

## Dependencies

- meshtastic
- flask
- flask-cors
- protobuf
- pypubsub

All in `requirements.txt`.

## License

MIT. Do whatever you want with it.

---

Built by [M9WAV](https://m9wav.uk/). If you find bugs or have ideas, feel free to open an issue.
