PacketScope is a terminal-based live packet monitor for MeshCore, designed especially for Linux devices such as the ClockworkPi uConsole and Raspberry Pi.
It reads live packet activity from the systemd journal produced by meshcore-packet-capture and presents it in a cleaner, interactive TUI with packet statistics, signal information, MQTT delivery health, filtering, search, pause/resume, logging, Unicode, and emoji support.
Important: PacketScope is a viewer and diagnostics interface. It does not connect directly to a MeshCore radio and it does not replace
meshcore-packet-capture.
MeshCore Companion Radio
|
v
meshcore-packet-capture
|
+---- MQTT broker(s)
|
v
systemd journal
|
v
PacketScope
PacketScope follows the journal for:
meshcore-packet-capture.service
Equivalent raw command:
journalctl -u meshcore-packet-capture -fPacketScope currently targets Linux systems using systemd.
Required:
- Linux with systemd
- A working
meshcore-packet-captureinstallation meshcore-packet-capture.servicerunning- Go installed to build PacketScope
- Permission to read the systemd journal
- A UTF-8 capable terminal
Recommended platform:
- Debian / Raspberry Pi OS
- ARM64 or AMD64
- ClockworkPi uConsole or Raspberry Pi
PacketScope depends on the separate meshcore-packet-capture project:
https://github.com/agessaman/meshcore-packet-capture
meshcore-packet-capture is designed for MeshCore Companion radios and supports BLE, serial, and TCP connections. It can also publish captured packets to one or more MQTT brokers.
For repeaters and RoomServers, the upstream project recommends meshcoretomqtt instead.
The upstream project currently provides a managed-service installer:
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)"Follow the upstream setup instructions to configure the Companion radio connection and optional MQTT brokers.
After installation, verify:
systemctl status meshcore-packet-capture --no-pager -lYou should see:
Active: active (running)
Then confirm packets are being logged:
sudo journalctl -u meshcore-packet-capture -fIf packet lines are appearing there, PacketScope has a source to monitor.
Clone the repository:
git clone git@github.com:wykweb/PacketScope.git
cd PacketScopeBuild:
go mod download
go test ./...
go build -o packetscope ./cmd/packetscopeRun:
./packetscopeIf your user cannot read the systemd journal:
sudo -E ./packetscopeA better permanent solution is to grant your user journal access.
Check your groups:
groupsIf systemd-journal is not listed:
sudo usermod -aG systemd-journal $USERThen log out and back in, or reboot.
Test:
journalctl -u meshcore-packet-capture -n 5 --no-pagerIf that works without sudo, PacketScope can also run without sudo.
PacketScope uses Unicode and emoji icons.
If your desktop terminal session has an incorrect locale, launch PacketScope with a clean UTF-8 environment:
env -u LC_ALL LANG=en_CA.UTF-8 LC_CTYPE=en_CA.UTF-8 \
lxterminal --no-remote -e /home/dragon/start-packetscope.shExample launcher:
cat >~/start-packetscope.sh <<'EOF'#!/bin/bashunset LC_ALLexport LANG=en_CA.UTF-8export LC_CTYPE=en_CA.UTF-8cd /home/dragon/packetscopeexec ./packetscopeEOF
chmod +x ~/start-packetscope.shCreate:
cat >~/Desktop/PacketScope.desktop <<'EOF'[Desktop Entry]Version=1.0Type=ApplicationName=PacketScopeComment=MeshCore Packet Capture MonitorExec=env -u LC_ALL LANG=en_CA.UTF-8 LC_CTYPE=en_CA.UTF-8 lxterminal --no-remote -e /home/dragon/start-packetscope.shIcon=utilities-terminalTerminal=falseCategories=Network;EOF
chmod +x ~/Desktop/PacketScope.desktopIf your desktop environment asks whether to trust or allow the launcher, choose Allow Launching.
PacketScope parses packet-capture journal lines such as:
Captured packet #3585: F type 6, 102 bytes, SNR: 11.25, RSSI: -36, hash: 57A146E2A50D8E9B (MQTT: 5/5)
The UI can display:
- packet number
- route value (
F/D) - MeshCore packet type
- packet size
- RSSI
- SNR
- packet hash
- MQTT delivery result
- live packet rate
- packet history
- signal history
- pause/resume
- filters
- search
- save-to-log
A value such as:
MQTT: 5/5
comes from meshcore-packet-capture.
PacketScope does not independently connect to those five brokers. It displays the delivery result reported by the capture service.
The current journal format provides aggregate delivery status only. For example, 4/5 tells PacketScope that one delivery failed, but it does not identify which broker failed unless the upstream capture service logs per-broker details.
Current builds may include controls such as:
P Pause / resume
C Clear current view
F Filter
S Search
Q Quit
Refer to the footer shown inside PacketScope for the controls supported by the installed version.
First test the source directly:
journalctl -u meshcore-packet-capture -fIf no packet events appear there, troubleshoot meshcore-packet-capture first.
Use:
sudo -E ./packetscopeor add your user to:
systemd-journal
as described above.
Check:
locale charmapIt should return:
UTF-8
If not, use the UTF-8 launcher described above.
systemctl status meshcore-packet-capture --no-pager -ljournalctl -u meshcore-packet-capture -n 50 --no-pagerFormat:
gofmt -w .Test:
go test ./...Build:
go build -o packetscope ./cmd/packetscopeCommit and push:
git add .
git commit -m "Update PacketScope"
git push origin mainPacketScope and MeshScope are separate applications.
MeshScope
- Derived from
corescope-tui - Uses the CoreScope REST/WebSocket backend
- Commonly connects to
https://live.meshcore.ca - Focuses on nodes, observers, channels, maps, analytics, and messages
PacketScope
- Independent project
- Reads the local
meshcore-packet-capturejournal - Focuses on raw packet activity, RF signal metrics, packet types, hashes, MQTT delivery, filtering, and diagnostics
They complement each other but do not depend on each other.
PacketScope relies on the excellent meshcore-packet-capture project for radio capture and MQTT integration:
https://github.com/agessaman/meshcore-packet-capture
PacketScope is a separate project and is not part of or endorsed by the upstream meshcore-packet-capture project.