Add comprehensive documentation

- docs/architecture.md: module structure, data flow, threading model (Mermaid diagrams) - docs/protocol.md: complete wire protocol specification with packet formats - docs/user-guide.md: server & client usage, CLI reference, troubleshooting - docs/docker.md: Docker, Compose, registry push, deployment options - Update docker-compose.yml with Gitea registry image tags Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-31 13:06:14 +04:00
parent d71a3a4e71
commit 6a70e05454
5 changed files with 877 additions and 0 deletions
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -0,0 +1,186 @@
+# btest-rs User Guide
+
+## Quick Start
+
+```bash
+# Server mode (MikroTik connects to you)
+btest -s
+
+# Client mode (you connect to MikroTik)
+btest -c 192.168.88.1 -r
+```
+
+## Server Mode
+
+Run btest-rs as a server and let MikroTik devices connect for bandwidth testing.
+
+### Basic Server
+
+```bash
+btest -s
+```
+
+Listens on TCP port 2000 (default). Any MikroTik device can connect without authentication.
+
+### Server with Authentication
+
+```bash
+btest -s -a admin -p mysecretpassword
+```
+
+MikroTik devices must provide matching credentials. Uses MD5 challenge-response authentication.
+
+### Custom Port
+
+```bash
+btest -s -P 3000
+```
+
+### Verbose/Debug Output
+
+```bash
+btest -s -v      # Show connection info and debug messages
+btest -s -vv     # Show hex dumps of status exchange (for debugging)
+```
+
+### MikroTik Configuration (connecting to our server)
+
+On the MikroTik device (WinBox or CLI):
+
+```
+# CLI
+/tool/bandwidth-test address=<server-ip> direction=both protocol=udp user=admin password=mysecretpassword
+
+# For best results, use 1 connection
+/tool/bandwidth-test address=<server-ip> direction=both protocol=udp connection-count=1
+```
+
+Or via WinBox: **Tools → Bandwidth Test**, enter server address, credentials, and click Start.
+
+## Client Mode
+
+Connect to a MikroTik device's built-in bandwidth test server.
+
+### Prerequisites
+
+Enable btest server on MikroTik:
+```
+/tool/bandwidth-server set enabled=yes
+```
+
+**Note**: If the MikroTik uses RouterOS >= 6.43 with authentication enabled, you'll need to either disable auth or use credentials. EC-SRP5 auth is not yet supported; MD5 auth works on older RouterOS versions.
+
+### Download Test (receive)
+
+```bash
+btest -c 192.168.88.1 -r
+```
+
+Measures download speed from MikroTik to your machine.
+
+### Upload Test (transmit)
+
+```bash
+btest -c 192.168.88.1 -t
+```
+
+Measures upload speed from your machine to MikroTik.
+
+### Bidirectional Test
+
+```bash
+btest -c 192.168.88.1 -t -r
+```
+
+Tests both directions simultaneously.
+
+### UDP Mode
+
+```bash
+btest -c 192.168.88.1 -r -u          # UDP download
+btest -c 192.168.88.1 -t -u          # UDP upload
+btest -c 192.168.88.1 -t -r -u       # UDP bidirectional
+```
+
+### Bandwidth Limiting
+
+```bash
+btest -c 192.168.88.1 -r -b 100M     # Limit to 100 Mbps
+btest -c 192.168.88.1 -t -b 1G       # Limit to 1 Gbps
+btest -c 192.168.88.1 -r -b 500K     # Limit to 500 Kbps
+```
+
+### NAT Traversal
+
+If you're behind NAT and need to receive UDP data:
+
+```bash
+btest -c 192.168.88.1 -r -u -n
+```
+
+The `-n` flag sends a probe packet to open the NAT firewall hole.
+
+### With Authentication
+
+```bash
+btest -c 192.168.88.1 -r -a admin -p password
+```
+
+## Reading the Output
+
+```
+[   1]  TX  264.50 Mbps (33062912 bytes)
+[   2]  TX  263.98 Mbps (32997376 bytes)
+[   2]  RX  263.98 Mbps (32997012 bytes)
+[   3]  RX  430.51 Mbps (53813376 bytes)  lost: 5
+```
+
+| Field | Meaning |
+|-------|---------|
+| `[  N]` | Interval number (1 per second) |
+| `TX` | Data we sent (upload) |
+| `RX` | Data we received (download) |
+| `Mbps` | Megabits per second |
+| `bytes` | Raw bytes transferred in this interval |
+| `lost: N` | UDP packets lost (UDP mode only) |
+
+## CLI Reference
+
+```
+btest-rs — MikroTik Bandwidth Test server & client in Rust
+
+Usage: btest [OPTIONS]
+
+Options:
+  -s, --server              Run in server mode
+  -c, --client <HOST>       Run in client mode, connect to HOST
+  -t, --transmit            Client: upload test
+  -r, --receive             Client: download test
+  -u, --udp                 Use UDP instead of TCP
+  -b, --bandwidth <BW>      Bandwidth limit (e.g., 100M, 1G, 500K)
+  -P, --port <PORT>         Port number [default: 2000]
+  -a, --authuser <USER>     Authentication username
+  -p, --authpass <PASS>     Authentication password
+  -n, --nat                 NAT traversal mode
+  -v, --verbose             Increase log verbosity (-v, -vv)
+  -h, --help                Show help
+  -V, --version             Show version
+```
+
+## Tips
+
+- **Use 1 connection** when MikroTik connects to your server. Multi-connection mode causes MikroTik's per-connection speed adaptation to throttle.
+- **TCP mode** generally gives more stable results than UDP due to TCP flow control.
+- **UDP mode** is better for measuring raw link capacity without TCP overhead.
+- **First interval** may show higher or lower numbers as the connection stabilizes. Look at intervals 3+ for steady-state throughput.
+- **WiFi testing**: bidirectional tests on WiFi will show lower per-direction speeds because WiFi is half-duplex at the MAC layer.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `EC-SRP5 authentication not supported` | Disable auth on MikroTik btest server, or use older RouterOS |
+| `Connection refused` | Check port 2000 is open, firewall allows it |
+| Server shows 0 RX | Check MikroTik is actually sending (direction setting) |
+| Speed drops over time (server mode) | MikroTik client behavior — use 1 connection, or use our client mode instead |
+| UDP `lost` packets high | Network congestion or MTU issues, try reducing bandwidth with `-b` |