forked from n6cta/mwtchahrd
151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
# 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](https://www.rust-lang.org/tools/install) (version 1.XX or later)
|
||
- Cargo package manager (comes with Rust)
|
||
|
||
## Installation
|
||
|
||
Clone the repository:
|
||
|
||
```bash
|
||
git https://gitea.farpn.net/n6cta/mwtchahrd.git
|
||
cd mwtchahrd
|
||
```
|
||
|
||
Build the project in release mode:
|
||
|
||
```bash
|
||
cargo build --release
|
||
```
|
||
|
||
The compiled executable will be located in the `target/release` directory.
|
||
|
||
## Usage
|
||
|
||
Run the executable with the required arguments:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
mwtchahrd -i 127.0.0.1 -p 8000
|
||
```
|
||
|
||
### Debug Mode
|
||
|
||
Enable debug mode to see detailed frame information including hex dumps:
|
||
|
||
```bash
|
||
mwtchahrd -i 127.0.0.1 -p 8000 -d
|
||
```
|
||
|
||
### UI Frames Only
|
||
|
||
Monitor only UI frames:
|
||
|
||
```bash
|
||
mwtchahrd -i 127.0.0.1 -p 8000 -u
|
||
```
|
||
|
||
### Spotting to [Spothole.app](https://spothole.app) API
|
||
|
||
Sends only UI frames and mode is hardcoded as `PKT`. Spot from callsign `W1CDN` and report fixed frequency 14.105 MHz:
|
||
|
||
```bash
|
||
mwtchahrd --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](https://github.com/clap-rs/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. |