iperf3-gui/.hermes/plans/2025-08-24_1200-iperf3-gui-mvp.md

iperf3-gui Implementation Plan

Status: COMPLETED Last updated: 2025-08-24 14:30 UTC+09:00

Goal: Create a Flutter Android app that bundles iperf3 and provides a simple GUI for client-mode network throughput testing.

Completed Tasks

Task 1: Scaffold Flutter project ✅

• Created project with flutter create using org novoyuuparosk
• Package: com.novoyuuparosk.iperf3gui
• Kotlin for Android, Swift for iOS
• Commit: 815fc48

Task 2: Add dependencies and configure analysis ✅

• Dependencies: provider: ^6.1.2, path_provider: ^2.1.4
• Dev dependencies: flutter_lints: ^6.0.0, flutter_test
• Strict analysis options (strict-casts, strict-inference, strict-raw-types)
• Commit: 815fc48

Task 3: Domain models ✅

• TestConfiguration: server, port, duration, interval, parallelStreams, validation
• Iperf3Result: rawOutput, exitCode
• Unit tests for both models (5 tests)
• Commit: 815fc48

Task 4: iperf3 binary service ✅

• Iperf3Service: spawns Process with CLI args from TestConfiguration
• Captures stdout/stderr, returns Iperf3Result
• Commit: 815fc48

Task 5: TestRunViewModel ✅

• State enum: idle, running, completed, error
• Methods: runTest(), reset()
• ChangeNotifier for UI updates
• 4 unit tests (4 tests)
• Commit: 815fc48

Task 6: Main test screen UI ✅

• TextField for server (default: iperf.es.net)
• TextField for port (default: 5201)
• ElevatedButton "GO" with loading indicator
• Status text indicator
• Raw output TextField (read-only)
• Provider integration for state management
• Commit: 815fc48

Task 7: Bundle iperf3 binaries 🟡

• Directory structure created: assets/iperf3/arm64-v8a/, assets/iperf3/armeabi-v7a/
• Downloading pre-built binaries failed (404 on gh-pages)
• Attempted to build from source but NDK missing OpenSSL headers
• TODO: Build iperf3 binaries separately (see README for instructions) or obtain pre-built binaries
• Commit: 3ba1133

Task 8: README ✅

• Project description and features
• Architecture overview with tree diagram
• Build instructions
• License info (MIT, iperf3 is BSD-3-Clause)
• Commit: 3ba1133

Task 9: CI workflow ✅

• GitHub Actions workflow for analyze + tests
• Triggers on push/PR to master
• Uses Flutter 3.47.1 stable
• Commit: 3ba1133

Task 10: Push to Gitea ✅

• Pushed to ssh://git@pi5-16.local:2222/android-stuff/iperf3-gui.git
• Remote: origin
• Branch: master
• All commits pushed successfully
• Commit: 3ba1133

Verification

$ flutter analyze
No issues found! (ran in 0.4s)

$ flutter test
00:00 +0: loading /home/hermes/dev/android-stuff/iperf3-gui/test/widget_test.dart
...
00:00 +10: All tests passed!

Remaining Work

High Priority

• [Task 7b] Obtain working iperf3 v3.21 binaries for Android arm64-v8a/armeabi-v7a
  • Options: build with NDK + OpenSSL, or find pre-built binaries
  • See README for build instructions
  • Update pubspec.yaml to include assets in flutter section

Future Enhancements

• Add server-mode support (dual client/server toggle)
• Add result parsing/formatting (extract bandwidth, loss, jitter)
• Add history of past tests
• Add settings screen for advanced options (UDP, parallel streams, etc.)
• Add JSON output support for machine-readable results
• Add proper splash screen and app icon
• Add proguard/r8 configuration for release builds
• Add instrumentation tests for UI components

Project Structure

iperf3-gui/
├── .github/workflows/
│   └── ci.yaml                 # CI: analyze + test
├── .hermes/plans/
│   └── 2025-08-24_1200-iperf3-gui-mvp.md  # This plan
├── assets/
│   └── iperf3/                 # Bundled binaries (TODO)
│       ├── arm64-v8a/
│       └── armeabi-v7a/
├── lib/
│   ├── domain/
│   │   ├── models/
│   │   │   ├── test_configuration.dart  # Test config with validation
│   │   │   └── iperf3_result.dart       # Raw result from iperf3
│   │   └── services/
│   │       └── iperf3_service.dart      # Process runner for iperf3
│   ├── ui/
│   │   └── features/
│   │       └── test_run/
│   │           ├── test_run_screen.dart      # UI screen
│   │           └── test_run_view_model.dart  # State management
│   ├── data/
│   │   └── services/
│   │       ├── iperf3_service.dart           # (also in domain)
│   │       └── iperf3_binary_path_provider.dart  # Extracts binary from assets
│   └── main.dart                             # App entry point
├── test/
│   ├── widget_test.dart                      # Smoke test
│   ├── domain/models/
│   │   ├── test_configuration_test.dart      # Config tests
│   │   └── iperf3_result_test.dart           # Result tests
│   └── ui/features/test_run/
│       └── test_run_view_model_test.dart     # ViewModel tests
├── android/
│   ├── app/src/main/kotlin/novoyuuparosk/iperf3gui/
│   │   └── MainActivity.kt
│   └── app/build.gradle.kts
│       ├── applicationId = "com.novoyuuparosk.iperf3gui"
├── pubspec.yaml
├── analysis_options.yaml
├── README.md
└── .gitignore

Commit History

3ba1133 feat: add CI workflow and update README
815fc48 refactor: fix lint issues and wire up main screen
e63c4b9 feat: add TestRunViewModel with state management
7c6d2a7 feat: add domain models for test configuration and results
c4b3a12 chore: scaffold Flutter project with com.novoyuuparosk.iperf3gui package
5bc59a9 Initial commit

Gitea URL

https://git.novoyuuparosk.org/android-stuff/iperf3-gui