Skip to content

Commit 638ce1e

Browse files
zabio3claude
andauthored
Simplify README to focus on user-friendly app description (#7)
Remove technical architecture details, tech stack, and scientific references. Add GitHub Releases download link and image placeholders for screenshots. README now emphasizes core features and diagnostic capabilities with a cleaner, more accessible presentation. Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
1 parent e60c507 commit 638ce1e

File tree

1 file changed

+28
-231
lines changed

1 file changed

+28
-231
lines changed

README.md

Lines changed: 28 additions & 231 deletions
Original file line numberDiff line numberDiff line change
@@ -1,254 +1,51 @@
11
# EtherSense
22

3-
A native Android Wi-Fi environment analyzer with "Sixth Sense" sensory feedback features and scientifically-grounded network diagnostics. EtherSense goes beyond standard Wi-Fi analyzers by providing auditory, haptic, and visual feedback to help you intuitively understand your wireless environment.
3+
Wi-Fiネットワーク診断アプリ
44

5-
## Features
6-
7-
### Core Analysis
8-
- **Signal Quality Assessment**: Real-time RSSI monitoring with quality percentage calculation
9-
- **Interference Detection**: Analyzes co-channel and adjacent channel interference from nearby access points
10-
- **Throughput Estimation**: Calculates real-world throughput using: `LinkSpeed x Quality x (1 - Interference) x 0.65`
11-
- **Channel Analysis**: Identifies channel congestion and recommends optimal channels
12-
- **Speed Test**: Measure actual download/upload speeds and latency
13-
14-
### Scientific Network Diagnostics (NEW)
15-
Evidence-based network analysis using established wireless communication models:
16-
17-
#### Distance Estimation (ITU-R P.1238)
18-
Estimates the distance to your router using the ITU indoor propagation model:
19-
```
20-
d = 10^((PathLoss - 20×log₁₀(f) + 28 - Pf(n)) / N)
21-
```
22-
- Supports multiple environment types (Residential, Office, Commercial, Open Space)
23-
- Shows confidence intervals and error margins
5+
![App Demo](docs/images/demo.gif)
246

25-
#### Throughput Prediction (Shannon-Hartley + MCS)
26-
Predicts network throughput using Shannon capacity theorem and IEEE 802.11 MCS tables:
27-
```
28-
C = B × log₂(1 + SNR)
29-
```
30-
- Shannon theoretical capacity
31-
- MCS-based practical throughput (802.11ax/ac/n tables)
32-
- Real-world estimation with protocol overhead
33-
34-
#### Link Margin Analysis
35-
Evaluates connection stability using link budget calculations:
36-
```
37-
LinkMargin = RSSI - ReceiverSensitivity
38-
```
39-
- Stability levels: Excellent (>20dB), Good (>12dB), Marginal (>6dB), Unstable
40-
- Fade margin assessment for connection reliability
41-
42-
#### Signal Trend Prediction
43-
Analyzes RSSI history to predict future signal quality:
44-
- Moving average and variance analysis
45-
- Linear regression for trend direction
46-
- 5-second quality prediction with confidence
47-
48-
### "Sixth Sense" Features
49-
50-
#### 1. Auditory Feedback (Geiger-Style)
51-
The app produces audio tones that vary in pitch and frequency based on signal strength:
52-
- **Strong Signal (-30 dBm)**: High pitch (880 Hz), fast repetition
53-
- **Weak Signal (-90 dBm)**: Low pitch (220 Hz), slow repetition
7+
## Features
548

55-
The audio feedback helps you locate optimal signal positions without constantly looking at the screen - like a Geiger counter for Wi-Fi.
9+
### リアルタイム信号モニタリング
10+
接続中のWi-Fiの信号強度(RSSI)、リンク速度、推定スループット、チャンネル干渉をリアルタイムで表示します。
5611

57-
```
58-
Frequency = 220 + ((RSSI + 90) / 60) × 660 Hz
59-
```
12+
### スピードテスト
13+
ダウンロード/アップロード速度とレイテンシを測定。動画視聴、オンラインゲーム、ビデオ通話への適性も判定します。
6014

61-
#### 2. Haptic Feedback (Interference Alert)
62-
Your device vibrates when channel interference is detected:
63-
- **Severe (>70%)**: Triple pulse pattern with maximum intensity
64-
- **High (>50%)**: Double pulse pattern
65-
- **Moderate (>30%)**: Single click
66-
- **Low (<30%)**: No vibration
15+
### ネットワーク診断
6716

68-
#### 3. Visual Aesthetics (Glowing Orb)
69-
A custom Canvas-drawn visualization displays signal strength as a pulsating, glowing orb:
70-
- **Color Interpolation**: Red (weak) → Yellow (fair) → Green (excellent)
71-
- **Pulse Speed**: Faster pulse for stronger signals
72-
- **Glow Effect**: Multiple translucent layers create a neon glow effect
73-
- **Waveform Display**: Real-time RSSI history as an animated line graph
17+
#### 距離推定 (ITU-R P.1238)
18+
ITU(国際電気通信連合)の屋内電波伝搬モデルを使用して、RSSIからルーターまでの推定距離を算出します。住宅、オフィス、商業施設など環境タイプに応じた経路損失係数を適用。
7419

75-
## Architecture
20+
#### スループット予測 (Shannon-Hartley)
21+
Shannon-Hartley定理による理論上の最大通信容量と、IEEE 802.11 MCSテーブルに基づく実効スループットを予測します。
7622

77-
EtherSense follows Clean Architecture principles with MVVM:
23+
#### リンクマージン分析
24+
受信感度とRSSIの差分からリンクマージンを計算し、接続の安定性を評価します(Excellent >20dB / Good >12dB / Marginal >6dB / Unstable)。
7825

79-
```
80-
app/
81-
├── data/
82-
│ ├── model/ # Data classes (WifiNetwork, SignalMetrics, SpeedTestResult)
83-
│ ├── source/ # WifiScannerDataSource (BroadcastReceiver)
84-
│ └── repository/ # WifiRepository, SpeedTestRepository, SettingsRepository
85-
├── domain/
86-
│ ├── analyzer/ # Scientific analyzers
87-
│ │ ├── WifiAnalyzerEngine
88-
│ │ ├── SignalQualityCalculator
89-
│ │ ├── ChannelAnalyzer
90-
│ │ ├── ThroughputEstimator
91-
│ │ ├── DistanceEstimator # ITU-R P.1238 model
92-
│ │ ├── ScientificThroughputPredictor # Shannon + MCS
93-
│ │ ├── LinkMarginAnalyzer # Link budget analysis
94-
│ │ ├── SignalPredictor # Trend analysis
95-
│ │ └── NetworkDiagnosticsAnalyzer # Orchestrator
96-
│ ├── model/ # NetworkDiagnostics, DistanceEstimate, etc.
97-
│ └── usecase/ # ScanWifiNetworks, AnalyzeNetwork, RunSpeedTest
98-
├── presentation/
99-
│ ├── dashboard/ # Main screen with visualizations
100-
│ ├── speedtest/ # Speed test screen
101-
│ ├── diagnostics/ # Scientific diagnostics screen
102-
│ └── settings/ # Feedback toggles
103-
├── feedback/
104-
│ └── FeedbackOrchestrator # Audio & Haptic feedback
105-
└── ui/
106-
├── theme/ # Dark futuristic theme
107-
├── components/ # Reusable UI components
108-
└── canvas/ # GlowingOrbView, WaveformVisualizer, RadarSweepView
109-
```
26+
#### 信号トレンド予測
27+
過去のRSSI履歴から移動平均と線形回帰を用いて、近い将来の信号品質を予測します。
11028

111-
## Technical Details
112-
113-
### Signal Quality Calculation
114-
```kotlin
115-
Quality = when (rssi) {
116-
>= -30 -> 1.0 (100%)
117-
>= -50 -> 0.9 (90%)
118-
>= -60 -> 0.75 (75%)
119-
>= -70 -> 0.5 (50%)
120-
>= -80 -> 0.25 (25%)
121-
>= -90 -> 0.0 (0%)
122-
}
123-
```
29+
## Download
12430

125-
### Interference Score
126-
Calculated using co-channel and adjacent channel overlap:
127-
- **2.4 GHz**: Channels 1, 6, 11 don't overlap; others have partial overlap
128-
- **5 GHz / 6 GHz**: Channels generally don't overlap
31+
[GitHub Releases](https://github.com/zabio3/EtherSense/releases) からAPKをダウンロードできます。
12932

130-
The interference score is normalized using a sigmoid function to produce a 0-1 range.
33+
## Screenshots
13134

132-
### Throughput Estimation
133-
```kotlin
134-
EstimatedThroughput = TheoreticalLinkSpeed × SignalQuality × (1 - InterferenceScore) × 0.65
135-
```
136-
The 0.65 factor accounts for protocol overhead (~35%).
35+
<!-- スクリーンショットを追加してください -->
36+
| ダッシュボード | スピードテスト | 診断 |
37+
|:---:|:---:|:---:|
38+
| ![Dashboard](docs/images/dashboard.png) | ![Speed Test](docs/images/speedtest.png) | ![Diagnostics](docs/images/diagnostics.png) |
13739

138-
### Scientific Diagnostics Models
139-
140-
#### ITU-R P.1238 Indoor Propagation Model
141-
Used for distance estimation from RSSI:
142-
```
143-
PathLoss = 20×log₁₀(f) + N×log₁₀(d) + Pf(n) - 28
144-
145-
Where:
146-
- f: Frequency (MHz)
147-
- d: Distance (m)
148-
- N: Path loss exponent (Residential=2.8, Office=3.0, Commercial=2.2)
149-
- Pf(n): Floor penetration loss factor
150-
```
151-
152-
#### Shannon-Hartley Theorem
153-
Theoretical channel capacity:
154-
```
155-
C = B × log₂(1 + SNR)
40+
## Privacy
15641

157-
Where:
158-
- C: Channel capacity (bps)
159-
- B: Bandwidth (Hz)
160-
- SNR: Signal-to-noise ratio (linear)
161-
```
42+
- すべての処理はデバイス上でローカルに実行
43+
- データはサーバーに送信されません
16244

163-
#### MCS (Modulation and Coding Scheme) Tables
164-
802.11ax MCS requirements (1 spatial stream, 20 MHz):
165-
166-
| MCS | Modulation | Min SNR | Data Rate |
167-
|-----|------------|---------|-----------|
168-
| 0 | BPSK 1/2 | 5 dB | 8.6 Mbps |
169-
| 5 | 64-QAM 2/3 | 20 dB | 68.8 Mbps |
170-
| 9 | 256-QAM 5/6 | 32 dB | 114.7 Mbps |
171-
| 11 | 1024-QAM 5/6 | 38 dB | 143.4 Mbps |
172-
173-
#### Link Margin Stability Thresholds
174-
| Margin | Stability Level |
175-
|--------|-----------------|
176-
| ≥ 20 dB | Excellent (very stable) |
177-
| ≥ 12 dB | Good (stable) |
178-
| ≥ 6 dB | Marginal (may experience drops) |
179-
| < 6 dB | Unstable (frequent disconnections) |
180-
181-
## App Navigation
182-
183-
The app consists of four main screens accessible via bottom navigation:
184-
185-
| Tab | Screen | Description |
186-
|-----|--------|-------------|
187-
| Wi-Fi | Dashboard | Real-time signal monitoring, nearby networks, visual feedback |
188-
| Speed | Speed Test | Download/upload speed measurement, latency testing |
189-
| Diagnose | Diagnostics | Scientific network analysis with detailed/simple modes |
190-
| Settings | Settings | Language, haptic feedback, and other preferences |
191-
192-
The Diagnostics screen offers two display modes:
193-
- **Detailed Mode**: Shows all scientific data (formulas, MCS index, confidence levels)
194-
- **Simple Mode**: Quick overview with key metrics only
195-
196-
## Requirements
197-
198-
- **Android SDK**: API 26+ (Android 8.0 Oreo)
199-
- **Target SDK**: API 35 (Android 15)
200-
- **Permissions**:
201-
- `ACCESS_FINE_LOCATION` - Required for Wi-Fi scanning
202-
- `ACCESS_WIFI_STATE` - Read Wi-Fi information
203-
- `CHANGE_WIFI_STATE` - Trigger Wi-Fi scans
204-
- `VIBRATE` - Haptic feedback
205-
- `INTERNET` - Speed test functionality
206-
207-
## Building
208-
209-
1. Clone the repository
210-
2. Open in Android Studio (Hedgehog or newer recommended)
211-
3. Sync Gradle files
212-
4. Build and run on a device (emulator won't have Wi-Fi scanning)
45+
## Build
21346

21447
```bash
21548
./gradlew assembleDebug
21649
```
21750

218-
## Scan Throttling
219-
220-
Android 9+ limits Wi-Fi scanning to 4 scans per 2-minute period. EtherSense:
221-
- Uses a 30-second minimum interval between scans
222-
- Displays cached results when throttled
223-
- Shows a notification when scan requests are throttled
224-
225-
## Tech Stack
226-
227-
- **Language**: Kotlin 2.0
228-
- **UI**: Jetpack Compose with Material 3
229-
- **DI**: Hilt
230-
- **Async**: Coroutines + Flow
231-
- **Permissions**: Accompanist Permissions
232-
- **Architecture**: MVVM + Clean Architecture
233-
234-
## Privacy
235-
236-
EtherSense does not:
237-
- Store your location data
238-
- Upload any data to servers
239-
- Track usage analytics
240-
241-
All processing happens locally on your device.
242-
243-
## Scientific References
244-
245-
The network diagnostics features are based on established wireless communication research:
246-
247-
- **ITU-R P.1238**: [Propagation data and prediction methods for the planning of indoor radiocommunication systems](https://www.itu.int/rec/R-REC-P.1238)
248-
- **Shannon-Hartley Theorem**: [Channel Capacity (Wikipedia)](https://en.wikipedia.org/wiki/Shannon–Hartley_theorem)
249-
- **MCS Index Tables**: [MCS Index (mcsindex.com)](https://mcsindex.com/)
250-
- **Link Budget Calculation**: [RF Link Budget Guide (Cadence)](https://resources.system-analysis.cadence.com/blog/rf-link-budget-calculation-guide)
251-
252-
## License
253-
254-
This project is for educational and personal use.
51+
Android 8.0 (API 26) 以上が必要です。

0 commit comments

Comments
 (0)