# 快速开始指南 - SkyLink Android App

## 🎯 5 分钟快速上手

### 1️⃣ 打开项目

```powershell
# 在 Windows PowerShell 中
cd d:\code\skyLink\skylink_android_app
# 然后用 Android Studio 打开此目录
```

### 2️⃣ 同步依赖

打开 Android Studio 后，点击：
- `File` -> `Sync Now` 或按 `Ctrl + Shift + O`

等待 Gradle 下载依赖（首次可能需要 2-5 分钟）

### 3️⃣ 连接设备

选择以下任一方式：
- **选项 A**: 连接 Android 手机（需启用 USB 调试）
- **选项 B**: 启动 Android 模拟器

### 4️⃣ 运行应用

点击工具栏的 ▶️ (Run) 按钮，或按 `Shift + F10`

### 5️⃣ 测试功能

应用启动后，您会看到：

**首页标签页 🏠**
- 视频显示区（黑色背景，等待视频流）
- GPS 信息显示
- 统计信息（FPS、速度、丢包率）
- 保存帧和录制按钮

**设置标签页 ⚙️**
- UDP 端口配置
- Ping 诊断工具
  - 输入主机地址（例：8.8.8.8）
  - 选择 Ping 参数
  - 点击 🎯 单个 Ping 或 📊 多个 Ping

---

## 🎮 功能演示

### 测试 Ping 功能

#### 场景 1：Ping 谷歌 DNS

1. 点击底部 "⚙️ 设置" 标签页
2. 在 "目标主机" 框输入：`8.8.8.8`
3. 点击 "🎯 单个 Ping" 按钮
4. 等待结果显示（通常 1-5 秒）

**预期结果：**
```
✅ Ping 成功!
主机: 8.8.8.8
最小延迟: 20 ms
最大延迟: 50 ms
平均延迟: 35 ms
丢包率: 0.0%
```

#### 场景 2：并行诊断常见主机

1. 在设置页面点击 "📊 多个 Ping" 按钮
2. 系统将自动 Ping：
   - 8.8.8.8 (谷歌 DNS)
   - 1.1.1.1 (Cloudflare DNS)
   - 114.114.114.114 (国内 DNS)
   - 192.168.1.1 (本地网关)

**预期结果：** 并行显示所有主机的连接状态

---

## 📱 页面导航

### 底部导航栏

```
┌─────────────────────────────┐
│  [🏠 首页]  [⚙️ 设置]       │  ← 点击切换
└─────────────────────────────┘
```

### 返回导航

- 顶部左上角：返回上一页面（如果可用）
- Android 返回键：返回上一个 Fragment

---

## 🔧 常见配置

### 修改 UDP 监听端口

**当前默认**: 9999

在设置页面修改：
1. 点击 "⚙️ 设置" 标签页
2. 修改 "UDP 接收端口" 字段
3. 设置将自动保存

### 调整 Ping 参数

- **Ping 次数**: 1、2、4、8、16 可选
- **超时时间**: 1秒、3秒、5秒、10秒 可选

更长的超时时间适合网络较差的环境。

---

## 📊 首页数据说明

| 项目 | 说明 | 示例 |
|------|------|------|
| **FPS** | 视频帧率 | 30 fps |
| **Speed** | 接收速度 | 5000 KB/s |
| **Packet Loss** | 丢包率 | 0.5% |
| **Latitude** | 纬度 | 39.904030° |
| **Longitude** | 经度 | 116.407526° |
| **Altitude** | 高度 | 50.0 m |

---

## ⚠️ 故障排查

### 应用闪退

**解决方案：**
1. 检查 Android Studio 中的错误日志
2. 试试重新构建项目
3. 查看 Build 输出窗口

### Ping 无法工作

**检查清单：**
- [ ] 设备已连接网络？
- [ ] 输入的主机地址正确？
- [ ] 目标主机可达？（试试 8.8.8.8）
- [ ] 网络权限已授予？

### 导航栏不显示

**解决方案：**
1. 重新启动应用
2. 清理项目：`Build` -> `Clean Project`
3. 重新构建并运行

---

## 📚 进阶使用

### 在 Android 代码中使用 Ping

```kotlin
// 在 Fragment 或 Activity 中
lifecycleScope.launch {
    val result = PingUtil.ping(
        host = "8.8.8.8",
        count = 4,
        timeout = 5
    )
    
    if (result.isSuccess) {
        println("✅ 连接成功，延迟: ${result.avgTime} ms")
    } else {
        println("❌ 连接失败: ${result.errorMessage}")
    }
}
```

### 并行 Ping 多个主机

```kotlin
val hosts = listOf("8.8.8.8", "1.1.1.1", "114.114.114.114")
val results = PingUtil.pingMultipleParallel(hosts, count = 4, timeout = 5)

results.forEach { result ->
    if (result.isSuccess) {
        println("${result.host}: ${result.avgTime} ms")
    }
}
```

---

## 🎓 学习资源

- 📖 [Android Fragments 文档](https://developer.android.com/guide/fragments)
- 📖 [Android Navigation 文档](https://developer.android.com/guide/navigation)
- 📖 [Kotlin Coroutines 指南](https://kotlinlang.org/docs/coroutines-overview.html)

---

## ❓ 常见问题

**Q: 应用启动后黑屏？**
A: 这是正常的！首页等待 UDP 视频流数据。确保有设备在发送数据到 UDP 端口 9999。

**Q: 如何修改 UDP 端口？**
A: 在设置页面修改 "UDP 接收端口" 字段，然后重启应用。

**Q: Ping 时间很长？**
A: 这可能是网络延迟或目标主机不可达。试试 Ping 谷歌 DNS (8.8.8.8)。

**Q: 如何保存数据？**
A: 首页的 "💾 保存帧" 按钮可保存当前视频帧。

---

## 📞 获取帮助

遇到问题？试试以下步骤：

1. 查看应用的 logcat 输出
2. 检查网络连接
3. 清理项目并重新构建
4. 重启 Android Studio

---

**祝您使用愉快！🚀**

最后更新: 2026-01-19  
版本: 1.1.0