119 lines
3.9 KiB
Markdown
119 lines
3.9 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.
|
||
|
||
## 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
|
||
```
|
||
|
||
## 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. |