meshcore-packet-capture

name	meshcore-packet-capture
description	Capture MeshCore Companion packets via BLE, serial, or TCP.
license	MIT
compatibility	Requires Python 3.11+, a MeshCore Companion radio, and the project's runtime dependencies.

MeshCore Packet Capture

Use this skill when operating, configuring, deploying, or troubleshooting meshcore-packet-capture, especially requests involving Companion radios, BLE/serial/TCP capture, MQTT publishing, LetsMesh, TOML configuration, Docker, systemd, launchd, or NixOS.

Scope boundary

This project captures from MeshCore Companion radios only. Do not route repeater or RoomServer capture here; use meshcoretomqtt instead.

Operating workflow

1. Identify the transport before changing configuration:
   • ble: direct address, device name, or general scan.
   • serial: one or more serial ports; the runtime uses the first configured port.
   • tcp: host and port, with SDK auto-reconnect enabled by default.
2. Prefer the installed CLI:

   meshcore-packet-capture --help
   meshcore-packet-capture --debug
   

   For a checkout, use python3 -m meshcore_packet_capture or python3 packet_capture.py. Verified CLI boundary: the current parser exposes --output, --verbose, --debug, --no-mqtt, and repeatable --config. It does not expose --show-config or a dry-run flag. Run the exact installed binary with --help before documenting or using any other flag; do not invent a configuration-preview command.
3. Configure one IATA code and at least one MQTT broker before expecting network uploads. LOC is a placeholder, not a useful deployment identity.
4. Start with --no-mqtt when isolating radio connectivity. Add MQTT only after the device captures packets locally.
5. Verify the actual boundary after every change: device connection logs, packet output, broker connection, and service/container status. Do not treat a successful install as proof of a working capture.

Mutation gate: when the request is read-only or plan-only, do not present stop/start/edit/delete/restart commands as actions to perform. Describe future mutations separately, label every example as unexecuted, and require target, scope, and rollback confirmation before the first mutation.

Configuration rules

Configuration precedence is highest to lowest:

1. Real PACKETCAPTURE_* process environment.
2. TOML: /etc/meshcore-packet-capture/config.toml, then sorted config.d/*.toml.
3. Legacy .env.local, then .env in the working/package directory.

Use --config PATH more than once to load only the named TOML files in order. Later files override earlier files. TOML broker blocks merge by name; enabled brokers are flattened into sequential PACKETCAPTURE_MQTT<n>_* slots. Keep user overrides in config.d/99-user.toml.

Minimal TOML shape:

[general]
iata = "SEA"

[capture]
connection_type = "serial"

[serial]
ports = ["/dev/ttyUSB0"]

[[broker]]
name = "home"
enabled = true
server = "mqtt.example.com"
port = 1883
transport = "tcp"

[broker.auth]
method = "password"
username = "user"
password = "secret"

Read references/configuration.md for the complete option map, broker authentication, topic templates, packet filters, and precedence edge cases.

MQTT and authentication

• Brokers are sequential and have no fixed upper limit. A missing MQTT<n>_ENABLED terminates discovery, so do not leave a numbering gap.
• Supported transports are tcp and websockets; use TLS explicitly for secure transport.
• Password auth uses username and password.
• Token auth uses Ed25519 JWT-style tokens. On-device signing is preferred when a connected radio supports it; Python signing is the fallback when a valid 64-byte private key is available.
• Never put private keys in a public skill, command transcript, committed .env, or shared Docker Compose file. Prefer a protected key file or secret injection.
• Topic placeholders are {IATA}, {IATA_lower}, {PUBLIC_KEY}, and {TOKEN}. Per-broker topics override global topics. RAW is not published unless explicitly configured.
• LetsMesh Analyzer brokers require a configured IATA. Do not silently accept the default LOC for a LetsMesh deployment.

Deployment defaults

Legacy hybrid installs are possible: a systemd or launchd unit may wrap a checkout under a user's home directory and load .env.local, without /opt or /etc TOML files. Inspect the running command, working directory, service unit, and environment/config source before choosing the modern managed-install path.

• Manual/PyPI: pipx install meshcore-packet-capture gives the CLI and does not install a background service.
• Managed Linux/macOS: the root bootstrap installer creates /opt/meshcore-packet-capture, /etc/meshcore-packet-capture, a virtual environment, and a system service. It installs the latest published release by default; use --tag or --branch to pin.
• macOS BLE: use the per-user LaunchAgent because Bluetooth permission belongs to the login user. Serial/TCP can use a LaunchDaemon.
• Docker: use the published image or docker compose up -d; serial needs a device mapping, while BLE generally needs privileged: true and may need host networking. Linux is the most reliable container host for hardware access.
• NixOS: use services.meshcore-packet-capture and rebuild with sudo nixos-rebuild switch.

Read references/deployment-and-troubleshooting.md for service commands, Docker hardware access, migration/update behavior, and bounded diagnostics.

Output and verification

Normal mode prints minimal packet information. --verbose adds JSON packet data; --debug adds connection, retry, packet parsing, and MQTT diagnostics. --output PATH writes packet data to a file. Captured records include device identity, timestamp, packet type, route, payload length, raw hex, SNR, RSSI, and a hash.

When troubleshooting, collect evidence in this order:

1. meshcore-packet-capture --debug --no-mqtt and confirm a real BLE, serial, or TCP connection.
2. Confirm packet records appear in console or the --output file.
3. Enable one broker and inspect broker connection/reconnect messages.
4. Check the resolved environment/config and topic names, without printing secrets.
5. For a managed service, inspect the service's own logs and status. For Docker, use docker compose config, docker compose ps, and docker compose logs.

Do not delete the install directory, state directory, or configuration during diagnosis. The uninstaller is interactive and backs up user configuration, but it still performs destructive removal only after confirmation.

When not to use

Do not use this skill for MeshCore repeater or RoomServer packet capture, generic MQTT administration, or implementing changes inside the upstream repository. For code changes, use the repository's contribution workflow and verify the project tests separately.

References

File	Load when
references/configuration.md	Writing TOML/env configuration, MQTT topics, authentication, or packet filters
references/deployment-and-troubleshooting.md	Installing, upgrading, running Docker/systemd/launchd/NixOS, or debugging a failed service
references/source-index.md	Checking source coverage, version markers, or revalidating this skill against upstream

Completion condition

Stop when the selected transport connects, a packet is observed locally, the intended MQTT topic receives data if MQTT is in scope, and the relevant service/container reports healthy. If hardware, credentials, or broker access is unavailable, report that exact unverified boundary instead of claiming success.