MeshCore Packet Capture

A standalone Python script for capturing and analyzing packets from MeshCore companion radios. The script connects to MeshCore devices via Bluetooth Low Energy (BLE) or serial connection, captures incoming packets, and outputs structured data to console, file, and MQTT broker.

Based on the original meshcoretomqtt project by Cisien and uses the official meshcore Python package.

Features

• Packet Capture: Captures incoming packets from MeshCore devices
• Multiple Output Formats: Console output, file logging, and MQTT publishing
• Connection Types: Supports both BLE and serial connections
• Packet Analysis: Parses packet headers, routes, payloads, and metadata
• RF Data: Captures signal quality metrics (SNR, RSSI)
• MQTT Integration: Publishes packet data to MQTT topics for integration with other systems

Requirements

• Python 3.7+
• meshcore package (official MeshCore Python library)
• paho-mqtt package (for MQTT functionality)

Installation

pip install meshcore paho-mqtt

Configuration

The script uses a config.ini file for configuration. A default configuration file is created automatically on first run.

Connection Settings

• connection_type: ble or serial
• ble_address: Specific BLE device address (optional)
• ble_device_name: BLE device name to scan for (optional)
• serial_port: Serial port path (for serial connections)

MQTT Settings

• server: MQTT broker address
• port: MQTT broker port
• username/password: Authentication credentials
• topics: MQTT topic structure for different data types

Usage

# Basic usage with default config
python packet_capture.py

# Specify custom config file
python packet_capture.py --config my_config.ini

# Save output to file
python packet_capture.py --output packets.json

# Disable MQTT publishing
python packet_capture.py --no-mqtt

# Enable verbose logging
python packet_capture.py --verbose

Output Format

Captured packets are output in JSON format with the following structure:

{
  "origin": "Device Name",
  "origin_id": "device_public_key",
  "timestamp": "2024-01-01T12:00:00.000000",
  "type": "PACKET",
  "direction": "rx",
  "time": "12:00:00",
  "date": "01/01/2024",
  "len": "45",
  "packet_type": "4",
  "route": "F",
  "payload_len": "32",
  "raw": "F5930103807E5F1EDE680070B9F3FCF238AA6B64BDEA8B4FDC4E2A",
  "SNR": "12.5",
  "RSSI": "-65",
  "hash": "A1B2C3D4E5F67890"
}

MQTT Topics

• meshcore/status: Device online/offline status
• meshcore/packets: Full packet data
• meshcore/raw: Raw packet data
• meshcore/decoded: Decoded packet content

Files

• packet_capture.py: Main capture script
• enums.py: Packet type and flag definitions
• config.ini: Configuration file (auto-generated)

Contributing

Contributions are welcome! I welcome pull requests and feature requests. Here are some ways you can contribute:

• Bug Reports: Found an issue? Please open a GitHub issue with details about the problem
• Feature Requests: Have an idea for a new feature? Open an issue to discuss it
• Pull Requests: Submit PRs for bug fixes, new features, or improvements
• Documentation: Help improve the README, add examples, or clarify usage instructions

Credits

This project is based on the original meshcoretomqtt project by Cisien, which provides a foundation for MeshCore packet capture and MQTT integration. The project uses the official meshcore Python package for device communication.