agessaman/meshcore-packet-capture
1
0
Fork 0
mirror of https://github.com/agessaman/meshcore-packet-capture.git synced 2026-04-20 23:23:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add TCP connection support and improve documentation

Browse source
This commit is contained in:
agessaman 2025-10-14 19:34:43 -07:00
parent 2e4350d488
commit 620e7bbc8a
3 changed files with 64 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

100
README.md
View file

@ -1,6 +1,6 @@
# 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.
A standalone Python script for capturing and analyzing packets from MeshCore companion radios. The script connects to MeshCore devices via Bluetooth Low Energy (BLE), serial, or TCP connection, captures incoming packets, and outputs structured data to console, file, and MQTT broker.
Based on the original [meshcoretomqtt](https://github.com/Cisien/meshcoretomqtt) project by [Cisien](https://github.com/Cisien) and uses the official [meshcore](https://github.com/meshcore-dev/meshcore_py) Python package.
@ -8,7 +8,7 @@ Based on the original [meshcoretomqtt](https://github.com/Cisien/meshcoretomqtt)
- **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
- **Connection Types**: Supports BLE, serial, and TCP connections
- **Packet Analysis**: Parses packet headers, routes, payloads, and metadata
- **RF Data**: Captures signal quality metrics (SNR, RSSI)
- **Multi-Broker MQTT**: Supports up to 4 MQTT brokers simultaneously
@ -57,7 +57,7 @@ See the [Docker Deployment](#docker-deployment) section below for detailed instr
## Configuration
The script uses environment files for configuration. This modern approach is more secure, container-friendly, and follows industry best practices.
The script uses environment files for configuration.
### Environment Files
@ -80,10 +80,12 @@ This will create a `.env.local` file with your current settings.
### Environment Variables
#### Connection Settings
- `PACKETCAPTURE_CONNECTION_TYPE`: `ble` or `serial`
- `PACKETCAPTURE_CONNECTION_TYPE`: `ble`, `serial`, or `tcp`
- `PACKETCAPTURE_BLE_ADDRESS`: Specific BLE device address (optional)
- `PACKETCAPTURE_BLE_DEVICE_NAME`: BLE device name to scan for (optional)
- `PACKETCAPTURE_SERIAL_PORTS`: Comma-separated list of serial ports to try
- `PACKETCAPTURE_TCP_HOST`: TCP host address (default: localhost)
- `PACKETCAPTURE_TCP_PORT`: TCP port number (default: 5000)
- `PACKETCAPTURE_TIMEOUT`: Connection timeout in seconds
- `PACKETCAPTURE_MAX_CONNECTION_RETRIES`: Maximum MeshCore connection retry attempts (0 = infinite)
- `PACKETCAPTURE_CONNECTION_RETRY_DELAY`: Delay between MeshCore reconnection attempts (seconds)
@ -118,12 +120,7 @@ The script supports up to 4 MQTT brokers (MQTT1, MQTT2, MQTT3, MQTT4). Each brok
- `PACKETCAPTURE_PRIVATE_KEY`: Device private key for auth token authentication (hex string)
- `PACKETCAPTURE_PRIVATE_KEY_FILE`: Path to file containing device private key
**Note**: You can provide the private key in multiple ways:
1. Environment variable: `PACKETCAPTURE_PRIVATE_KEY=your_key_here`
2. File path: `PACKETCAPTURE_PRIVATE_KEY_FILE=/path/to/key_file`
3. `.env.local` file: Create a `.env.local` file with `PACKETCAPTURE_PRIVATE_KEY=your_key_here`
The `.env.local` file is automatically ignored by git and is perfect for local development.
**Note**: Private keys can be provided via environment variable, file path, or `.env.local` file.
#### Topic Templates
Topics support template variables:
@ -151,7 +148,7 @@ PACKETCAPTURE_PRIVATE_KEY=your_private_key_here
# OR
PACKETCAPTURE_PRIVATE_KEY_FILE=/path/to/private_key_file
```
**Note**: Auth token authentication requires the device's private key. You can provide the private key manually via environment variable, file, or `.env.local` file.
**Note**: Auth token authentication requires the device's private key.
**Transport Options:**
- `tcp`: Standard TCP connection
@ -165,12 +162,9 @@ PACKETCAPTURE_MQTT1_TLS_VERIFY=true # Verify certificates
#### Exit Behavior
The script handles MQTT disconnections intelligently:
The script handles MQTT disconnections by continuing to run and attempting reconnection. On reconnection failure, it exits after maximum retry attempts (configurable).
- **On Disconnect**: Script continues running and attempts reconnection
- **On Reconnection Failure**: Script exits after maximum retry attempts (configurable)
This approach is ideal for BLE connections where disconnections may be transient:
For BLE connections where disconnections may be transient:
```bash
# Exit when reconnection attempts fail (recommended for BLE)
@ -181,26 +175,8 @@ PACKETCAPTURE_EXIT_ON_RECONNECT_FAIL=false
PACKETCAPTURE_MAX_MQTT_RETRIES=0
```
#### Legacy config.ini 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)
- `timeout`: Connection timeout in seconds
- `max_connection_retries`: Maximum MeshCore connection retry attempts (0 = infinite)
- `connection_retry_delay`: Delay between MeshCore reconnection attempts (seconds)
- `health_check_interval`: How often to check connection health (seconds)
### MQTT Settings
- `server`: MQTT broker address
- `port`: MQTT broker port
- `username`/`password`: Authentication credentials
- `topics`: MQTT topic structure for different data types
- `max_mqtt_retries`: Maximum MQTT connection retry attempts (0 = infinite)
- `mqtt_retry_delay`: Delay between MQTT reconnection attempts (seconds)
### Advert Settings
- `advert_interval_hours`: Send flood adverts at this interval (0 = disabled, default = 11 hours)
#### Advert Settings
- `PACKETCAPTURE_ADVERT_INTERVAL_HOURS`: Send flood adverts at this interval (0 = disabled, default = 11 hours)
## Usage
@ -225,13 +201,12 @@ python packet_capture.py --debug
## Docker Deployment
The project includes Docker support for easy deployment and scaling. Docker deployment is recommended for production environments and provides better isolation and management.
The project includes Docker support for deployment.
### Prerequisites
- Docker and Docker Compose installed
- Linux host system (recommended for full BLE support)
- MeshCore device accessible via BLE or serial connection
- Linux host system (recommended for BLE support)
### Quick Start with Docker Compose
@ -260,13 +235,7 @@ The project includes Docker support for easy deployment and scaling. Docker depl
### Docker Compose Configuration
The `docker-compose.yml` file includes:
- **Privileged mode**: Required for BLE and device access
- **Device mounting**: Serial port access (`/dev/ttyUSB0`, etc.)
- **Volume mounts**: Persistent data storage and configuration
- **Environment variables**: All configuration options
- **Network configuration**: Bridge network for MQTT connectivity
The `docker-compose.yml` file includes privileged mode for device access, volume mounts for data storage, and environment variable configuration.
### Manual Docker Commands
@ -288,34 +257,24 @@ docker run --privileged \
-e PACKETCAPTURE_CONNECTION_TYPE=serial \
-e PACKETCAPTURE_SERIAL_PORTS=/dev/ttyUSB0 \
meshcore-capture
# Run with TCP connection
docker run \
-v $(pwd)/data:/app/data \
-e PACKETCAPTURE_CONNECTION_TYPE=tcp \
-e PACKETCAPTURE_TCP_HOST=your-tcp-server \
-e PACKETCAPTURE_TCP_PORT=5000 \
meshcore-capture
```
### Configuration in Docker
Configuration can be provided via:
1. **Environment variables** (recommended):
```bash
-e PACKETCAPTURE_MQTT1_SERVER=mqtt.example.com
-e PACKETCAPTURE_MQTT1_USERNAME=user
-e PACKETCAPTURE_MQTT1_PASSWORD=pass
```
2. **Volume-mounted .env.local file**:
```bash
-v $(pwd)/.env.local:/app/.env.local:ro
```
3. **Docker Compose environment section**:
```yaml
environment:
- PACKETCAPTURE_MQTT1_SERVER=mqtt.example.com
```
Configuration can be provided via environment variables or volume-mounted `.env.local` files.
### Platform Considerations
- **Linux**: Full support for BLE and serial connections
- **macOS**: Limited BLE support in containers, may require host networking
- **Linux**: Full BLE and serial support
- **macOS**: Limited BLE support in containers
- **Windows**: Limited BLE support, serial connections work with proper device mounting
### Troubleshooting Docker Deployment
@ -424,12 +383,7 @@ This will show:
## 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
Contributions are welcome! Please open GitHub issues for bug reports and feature requests, or submit pull requests for improvements.
## Credits

38
install.sh
View file

@ -435,9 +435,9 @@ select_connection_type() {
echo " • Direct USB or serial cable connection"
echo " • More reliable for continuous operation"
echo ""
echo " 3) TCP Connection - For network-connected devices (Coming Soon)"
echo " • Connect over network"
echo " • Not yet implemented"
echo " 3) TCP Connection - For network-connected devices"
echo " • Connect to your node over the network"
echo " • Works with ser2net or other TCP-to-serial bridges"
echo ""
while true; do
@ -509,10 +509,11 @@ select_connection_type() {
break
;;
3)
print_warning "TCP connection is not yet implemented"
echo "Please select another connection type."
CONNECTION_TYPE="tcp"
print_info "Selected: TCP Connection"
echo ""
continue
configure_tcp_connection
break
;;
*)
print_error "Invalid choice. Please enter 1, 2, or 3"
@ -590,6 +591,28 @@ select_serial_device() {
done
}
# Configure TCP connection
configure_tcp_connection() {
echo ""
print_header "TCP Connection Configuration"
echo ""
print_info "TCP connections work with ser2net or other TCP-to-serial bridges"
print_info "This allows you to access serial devices over the network"
echo ""
TCP_HOST=$(prompt_input "TCP host/address" "localhost")
TCP_PORT=$(prompt_input "TCP port" "5000")
# Validate port number
if ! [[ "$TCP_PORT" =~ ^[0-9]+$ ]] || [ "$TCP_PORT" -lt 1 ] || [ "$TCP_PORT" -gt 65535 ]; then
print_error "Invalid port number. Using default port 5000"
TCP_PORT="5000"
fi
print_success "TCP connection configured: $TCP_HOST:$TCP_PORT"
echo ""
}
prompt_yes_no() {
local prompt="$1"
local default="${2:-n}"
@ -819,7 +842,8 @@ EOF
echo "PACKETCAPTURE_SERIAL_PORTS=$SELECTED_SERIAL_DEVICE" >> "$ENV_LOCAL"
;;
"tcp")
echo "# TCP configuration (not yet implemented)" >> "$ENV_LOCAL"
echo "PACKETCAPTURE_TCP_HOST=$TCP_HOST" >> "$ENV_LOCAL"
echo "PACKETCAPTURE_TCP_PORT=$TCP_PORT" >> "$ENV_LOCAL"
;;
esac

6
packet_capture.py
View file

@ -388,6 +388,12 @@ class PacketCapture:
serial_port = serial_port.split(',')[0].strip()
self.logger.info(f"Connecting via serial port: {serial_port}")
self.meshcore = await meshcore.MeshCore.create_serial(serial_port, debug=False)
elif connection_type == 'tcp':
# Create TCP connection
tcp_host = self.get_env('TCP_HOST', 'localhost')
tcp_port = self.get_env_int('TCP_PORT', 5000)
self.logger.info(f"Connecting via TCP to {tcp_host}:{tcp_port}")
self.meshcore = await meshcore.MeshCore.create_tcp(tcp_host, tcp_port, debug=False)
else:
# Create BLE connection (default)
# Support both BLE_ADDRESS and BLE_DEVICE for MAC address