mwtchahrd/README.md

mwtchahrd

mwtchahrd is a Rust-based command‑line tool designed for monitoring AGWPE frames from a Direwolf TNC. It connects to an AGWPE server over TCP, sends a monitor command, receives and parses AGWPE frames, and outputs a human‑readable summary of the session. The tool is written with a focus on Rust idiomatic practices, safety, and efficiency.

Features

• TCP Connection & Keepalive: Connects to an AGWPE server over TCP and uses socket options to enable TCP keepalive.
• Frame Parsing: Decodes AGWPE frame headers and payloads, extracting useful information such as callsigns, data kind, and payload length.
• Debug Logging: In debug mode, prints detailed hex dumps of the raw frame data along with timestamps.
• Session Buffering: Buffers and processes multi‑line frames, displaying session information in a clear, formatted output.
• Filtering Options: Filters out frames based on the destination (ignoring “NODES”) and payload content (ignoring XID frames). Optionally, it can restrict output to only UI frames.

Prerequisites

• Rust (version 1.XX or later)
• Cargo package manager (comes with Rust)

Installation

Clone the repository:

git https://gitea.farpn.net/n6cta/mwtchahrd.git
cd mwtchahrd

Build the project in release mode:

cargo build --release

The compiled executable will be located in the target/release directory.

Usage

Run the executable with the required arguments:

mwtchahrd -i <IP> -p <PORT> [-c <CHANNEL>] [-d] [-u] 

Command‑Line Arguments

• -i, --ip <IP>
  The IP address of the AGWPE server (e.g. 127.0.0.1).

• -p, --port <PORT>
  The TCP port of the AGWPE server (e.g. 8000). Must be greater than 0.

• -c, --channel <CHANNEL>
  The AGWPE channel to monitor (default is 0). Must be between 0 and 255.

• -d, --debug
  Enable debug mode. When active, the tool prints detailed hex dumps and additional frame information.

• -u, --ui_only
  Only display frames with a UI payload. When this flag is set, frames that are not UI are skipped.

• -b, --uip <UIP> Send UDP to what IP address (e.g. 127.0.0.1) [default: 127.0.0.1].

• -k, --uport <UPORT> Send UDP to what port (e.g. 8000; 55555 disables UDP) [default: 55555].

• -s, --spotter <SPOTTER>
  Spotter callsign (e.g. W1CDN).

• -o, --spothole
  Spot UI frames to a Spothole server.

• -O, --spothole-alt <SPOTHOLE_ALT> Provide a different URL than https://spothole.app/api/v1/spot.

• -f, --freq <FREQ>
  Spotting frequency [default: 14105000].

• -h, --help
  Print help.

• -V, --version
  Print version.

Examples

Monitoring All Frames

Connect to an AGWPE server at 127.0.0.1:8000 on channel 0 and display all frames:

mwtchahrd -i 127.0.0.1 -p 8000

Debug Mode

Enable debug mode to see detailed frame information including hex dumps:

mwtchahrd -i 127.0.0.1 -p 8000 -d

UI Frames Only

Monitor only UI frames:

mwtchahrd -i 127.0.0.1 -p 8000 -u

Spotting to Spothole.app API

cargo run -- --ip 192.168.0.6 --port 8000 --spotter W1CDN --spothole --freq 14105000

Code Overview

• Validation Functions:

  • validate_port and validate_channel ensure that the provided port and channel values are within valid ranges.

• Command‑Line Parsing:

  • Uses the Clap crate to handle command‑line argument parsing and help message generation.

• Frame Parsing:

  • The parse_header and parse_frame functions read the raw TCP stream, extract header fields and payload data, and convert them into Rust types.

• Debug Logging & Text Filtering:

  • debug_log_frame prints detailed debug information.
  • filter_text cleans the payload for printable ASCII characters.

• Session Buffering:

  • A BufferManager handles incomplete multi‑line frames and extracts complete lines for further processing.

• Main Loop:

  • The main function repeatedly connects to the AGWPE server, sends a monitor command, reads data, and processes frames. On disconnection, it waits briefly before reconnecting.

Binary Releases

Binary releases are provided for the following targets for your convinience. They were generated using using Cross.

• aarch64-unknown-linux-gnu
• aarch64-apple-darwin
• x86_64-unknown-linux-gnu
• armv7-unknown-linux-gnueabihf
• arm-unknown-linux-gnueabihf

Contributing

Contributions are welcome! Feel free to fork the repository and submit pull requests. For major changes, please open an issue first to discuss your ideas.