meshcore-packet-capture git:20260712.7100271A

Immutable. This exact content is served forever at /api/v1/blob/cf6ce3b314a4bcf2.

---
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](https://github.com/agessaman/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:
   ```bash
   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:

```toml
[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.