Initial code commit.

README.md

@@ -1,2 +1,119 @@
 # 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.