Meshcore Packet Capture

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 (v2.2.0): the parser exposes --output, --verbose, --debug, --no-mqtt, repeatable --config, and the neighbors on-demand pair --neighbors-now / --neighbors-exit (run one zero-hop neighbor discovery + scopes cycle immediately; with --neighbors-exit, quit when the cycle finishes). 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"
# ble_pin = "123456"   # optional six-digit PIN for BLE connections

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

[[broker]]
name = "home"
enabled = true
server = "mqtt.example.com"
port = 1883
transport = "tcp"
# include_decoded = true   # publish the nested "decoded" object to this broker
# neighbors = true         # publish the neighbors snapshot to this broker

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

Optional feature blocks (v2.1.0+)

• Payload decoding (decode_payloads, include_decoded, decode_hashtag_channels, decode_channel_keys, decode_include_public): adds a nested decoded object with plain-text / structured fields. GRP_TXT channel messages are decrypted (sender, text), ADVERTs are parsed (name, role, lat/lon), and human-readable type/route labels plus path are included. Raw fields are unchanged. Direct messages (TXT_MSG) cannot be decrypted by a passive observer. Off by default; opt in per broker with include_decoded = true in its [[broker]] block.
• Neighbors publishing (neighbors per broker plus neighbors_interval_hours, neighbors_discover_window, neighbors_command_timeout, neighbors_scope_timeout, neighbors_scope_min_timeout, neighbors_scope_gap, neighbors_cycle_timeout, neighbors_max, neighbors_self_scopes): publishes a periodic zero-hop neighbor table plus each neighbor's region scopes to the neighbors topic. Off by default; the cycle only runs when at least one enabled broker sets neighbors = true. Requires an IATA (or an explicit [broker.topics] neighbors). The interval is clamped to 12–336 hours to match the observer firmware. --neighbors-now / --neighbors-exit trigger a cycle on demand.
• Log rotation (log_rotation = off|size|time, log_max_bytes, log_rotation_when, log_backup_count): only applies when an output file is given with --output.

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. Topics per broker: status, packets, decoded, debug, raw, neighbors. The decoded topic carries the nested decoded object when include_decoded is enabled; the neighbors topic carries the periodic neighbor snapshot when neighbors is enabled.
• Per-broker owner and email override the global capture.owner_public_key / capture.owner_email for token-auth brokers.
• LetsMesh Analyzer brokers require a configured IATA. Do not silently accept the default LOC for a LetsMesh deployment.