EMOS Deploy Android

將 Android 手機作為 EMOS 設備的現場部署伺服器。App 可編輯並預覽 deploy.txt、建立／使用手機 Wi‑Fi 熱點，並以 HTTP 持續提供設定檔給不定時加入的設備。

目前版本：0.1.12。部署前請先閱讀「平台限制」與「安全性」。

主要功能

• 編輯備份來源、MQTT、設備 Wi‑Fi、NTP 等 17 個設定欄位。
• 以 Android 原生儲存保存完整設定，App 重新開啟後自動還原。
• 即時產生及預覽完整 deploy.txt。
• 以 UTF-8、CRLF (0D 0A) 提供 deploy.txt，相容 EMOS 逐行命令解析。
• 提供 GET /deploy.txt，優先監聽 TCP Port 80，失敗時回退 8080。
• 部署服務會持續等待多台設備，不會在單台下載後自動停止。
• 顯示運行時間、成功下載數與設備來源 IP。
• 操作者關閉服務前需二次確認。
• Android 16／API 36 會顯示按鈕，由操作者自行開啟系統個人熱點設定頁；只有偵測到 Wi-Fi tethering 介面真正啟用後才檢查設定並啟動 HTTP 服務。
• 可讀取系統熱點設定時會比對 SSID UNiNUS-deploy 與密碼；不符時顯示警告但仍允許服務啟用，OEM 不允許讀取時則標示無法完整驗證。
• 提供獨立「設備探索」頁，預設透過 _http._tcp.local. 搜尋已連上場域 Wi-Fi 的 EMOS 設備，使用可搜尋的緊湊清單顯示解析後的 IPv4 與 Port。
• 點選設備後以底部抽屜顯示一般資訊及 DNS-SD TXT 欄位；支援 UTF-8、無值旗標與 Binary Hex，常用欄位優先並以 +N 展開其餘內容。
• 支援複製已探索設備的 IP／TXT，或以系統瀏覽器開啟其 HTTP 管理頁；離開探索頁或 App 進入背景時停止掃描。
• 保留狀態列安全區，App 前景執行時以沉浸模式隱藏底部導航列；從底部滑動可暫時叫回。

EMOS 相容流程

1. App／系統提供部署 SSID UNiNUS-deploy（2.4 GHz）。
2. EMOS Client 掃描並連入該 SSID。
3. Client 取得熱點 Gateway IP。
4. Client 請求：

GET http://<gateway>/deploy.txt

5. App 回傳目前編輯器產生的設定檔，並記錄來源 IP。

平台限制

平台	行為
Android 16／API 36	App 顯示「開啟系統熱點設定」按鈕，由使用者自行按下；之後等待 Wi-Fi tethering 介面實際啟用，再驗證可讀取的 SSID／密碼並啟動只綁定該介面的 HTTP 服務。
Android 8–15	公開 API 通常不能由一般 App 固定熱點 SSID；需在系統熱點設定手動設定。
系統個人熱點	一般 App 沒有權限可靠讀取、修改、備份、還原 SSID／密碼或自主開關個人熱點；完整自動化需要系統／OEM 特權、Device Owner 專用能力或 root，故本 App 不冒險模擬系統操作。
iOS	一般 App 無法啟動或設定 Personal Hotspot，因此目前不支援完整部署流程。

手機熱點原本已經開啟

App 不建立 Local-only Hotspot。按下「開啟並持續運行」後，App 先註冊系統 tethering callback；若尚未偵測到個人熱點，只顯示設定指引與「開啟系統熱點設定」按鈕，不會自動跳轉或提前顯示設定不符。

此時請確認系統熱點：

• 名稱為 UNiNUS-deploy
• 密碼與 EMOS 韌體端一致
• 使用 2.4 GHz
• 已關閉「無裝置時自動關閉」或設定足夠長的時間

偵測到唯一 Wi-Fi tethering 介面及 IPv4 位址後，App 才檢查 OEM 允許讀取的熱點設定並啟動 HTTP。若熱點關閉，HTTP 服務會暫停；重新開啟後重新解析介面及位址，成功 bind 後才恢復運行。

建置需求

• JDK 17
• Android SDK Platform 36
• Android Build Tools 36.0.0
• USB 實機測試時需要 Android Platform Tools／ADB

專案已包含 Gradle Wrapper，不需另外安裝 Gradle。

建置與測試

Windows：

gradlew.bat testDebugUnitTest assembleDebug

macOS／Linux：

./gradlew testDebugUnitTest assembleDebug

APK 輸出：

app/build/outputs/apk/debug/app-debug.apk

安裝至 USB 裝置：

adb install -r app/build/outputs/apk/debug/app-debug.apk

使用方式

1. 安裝並開啟 App，授予「附近 Wi‑Fi 裝置」權限。
2. 進入「設定檔」，填入現場實際參數；預設值不包含正式環境帳密。
3. 預覽 deploy.txt，確認巨集（例如 ^sn^、^hostname^）及縮排正確。
4. 點「開啟並持續運行」。
5. 若 App 顯示現有／手動熱點模式，開啟系統熱點設定並確認 SSID、密碼及頻段。
6. 保持 App 在前景，等待所有設備完成下載。
7. 完成後點「關閉服務」並再次確認。

專案結構

app/src/main/java/tw/com/uninus/emosdeploy/
  MainActivity.java             # WebView bridge、熱點及 HTTP Server
  HotspotStartState.java        # callback watchdog 狀態機
  HotspotFailurePolicy.java     # 熱點錯誤回退策略
  HotspotIdentity.java          # 預期／實際 SSID 比對
  HotspotSettingsAction.java    # 系統熱點設定 Intent
app/src/main/assets/index.html  # 行動 UI 與 deploy.txt 產生器
app/src/test/                   # JVM 單元測試

測試範圍

• SSID 相符、不符及無法讀取。
• 既有熱點不相容模式的回退策略。
• 熱點啟動 callback 成功、逾時、取消及延遲 callback。
• 系統熱點設定 Intent。

安全性

目前 EMOS 相容協定使用固定部署 SSID／共用密碼與明文 HTTP，適合受控的現場區域，不應直接暴露於公共場所。正式產品建議加入：

• 設定檔簽章或雜湊驗證。
• 短效 Token／每台設備授權。
• 敏感欄位加密保存，避免寫入原始碼或版本控制。
• 正式簽署的 Release APK；本專案 Debug APK 僅供測試。

如發現安全問題，請勿在公開 Issue 張貼正式帳密或部署檔，請依 SECURITY.md 回報。

授權

Copyright © 合一智聯科技。保留所有權利。除非取得書面授權，不授予複製、散布或商業使用權。