====== MQTT 通訊協定 ======

===== 系統概述 =====

本文檔描述小碧潭捷運站與侑盈能源管理系統之間的 MQTT 通訊協定，涵蓋設備監控數據傳輸、警戒值管理及復歸控制等功能。

===== 連線資訊 =====

  * **MQTT 版本**：v3.1.1
  * **連接埠**：1883、8883 (SSL)
  * **連線網址**：''emst.yo-win.com''
  * **連線帳密**：與技術窗口聯絡取得
  * **數據更新頻率**：每秒
  * **訂閱主題 (Topic)**：
    * 正式機
      * 規則：''/mrt/xiaobitan/{站號}/{資料類型}''
      * 範例：''/mrt/xiaobitan/1/raw_data''
    * 測試機
      * 規則：''/test/mrt/xiaobitan/{站號}/{資料類型}''
      * 範例：''/test/mrt/xiaobitan/1/raw_data''
  * **站號定義**：
    * 該站點設備的流水號，主要用途為定義出口。
    * 此設計是為了保留其他站點可配置多道門的彈性。
    * 以 **小碧潭捷運站** 為例，其站號為 **1**。
    * 以 **台北火車捷運站** 為例，站號可為 1:東、2:西、3:南、4:北門，以此類推。
==== Topic 命名規則 ====

<code>
/mrt/xiaobitan/{station_id}/{data_type}
</code>

^ 參數 ^ 說明 ^ 範例 ^
| station_id | 站台編號 | 1, 2, 3... |
| data_type | 資料類型 | raw_data, alert_setting, alert_log, switch_light |



===== 系統架構圖 =====
==== 使用者案例圖 ====
{{public:mrt:mqtt.diagram.png}}

==== 時間序列圖 ====
<mermaid>
%%{init: {'theme':'dark', 'themeVariables': { 'primaryColor': '#bb2528', 'primaryTextColor': '#fff', 'primaryBorderColor': '#7C0000', 'lineColor': '#F8B229', 'secondaryColor': '#006100', 'tertiaryColor': '#fff', 'background': '#1a1a1a', 'mainBkg': '#2d2d2d', 'secondBkg': '#3d3d3d', 'tertiaryBkg': '#4d4d4d'}}}%%
sequenceDiagram
    participant M as MRT
    participant E as EMS
    participant U as User
    
    Note over M, E: 功能 1: 數據傳輸
    loop 監控
        M->>E: 原始數據
        Note right of E: 顯示於畫面
    end
    
    Note over M, E: 功能 2: 警戒報告
    alt 超過警戒值
        M->>E: 警戒報告
        Note right of E: 顯示警戒
    end
    
    Note over U, M: 功能 3: 修改警戒值
    U->>E: 修改警戒值
    E->>M: 新警戒值
    
    Note over U, M: 功能 4: 復歸操作
    U->>E: 復歸按鈕
    E->>M: 燈號變更
</mermaid>
===== MQTT 資料格式定義 =====

==== 1. 原始監控資料 (Raw Data) ====

=== 基本資訊 ===
  * **Topic**: ''/mrt/xiaobitan/{station_id}/raw_data''
  * **方向**: 捷運站 → 侑盈系統
  * **頻率**: 每秒傳送
  * **用途**: 即時設備狀態監控

=== 資料結構 ===

<code javascript [enable_line_numbers="true"]>
{
    "temperature": 25.3,
    "x_displacement": 2,
    "y_displacement": 3,
    "z_displacement": 4,
    "x_frequency": 2,
    "y_frequency": 4,
    "z_frequency": 5,
    "avg_ele_current": 1.5,
    "avg_ele_volt": 220.0,
    "light": 0,
    "info": {
        "position": "xiaobitan_station",
        "device_id": "IRM-001",
        "timestamp": "2025-06-04 12:47:11"
    }
}
</code>

=== 欄位說明 ===

^ 欄位名稱         ^ 資料型別  ^ 單位  ^ 說明          ^ 最小值  ^  最大值 ^ 間距  ^ 警戒值     ^ 備註                                     ^
| position         | String    |       | 安裝位置      |         |         |       |            | xiaobitan_station                        |
| device_id        | String    |       | 裝置編號      |         |         |       |            | IRM-001                                  |
| temperature      | Float     | °C    | 環境溫度      |      20 |      50 |     5 |         49 |                                          |
| x_displacement   | Integer   | um    | X軸位移量     |       0 |      40 |    10 |         30 |                                          |
| y_displacement   | Integer   | um    | Y軸位移量     |       0 |      40 |    10 |         30 |                                          |
| z_displacement   | Integer   | um    | Z軸位移量     |       0 |      40 |    10 |         30 |                                          |
| x_frequency      | Integer   | Hz    | X軸頻率       |       0 |      50 |    10 |         45 |                                          |
| y_frequency      | Integer   | Hz    | Y軸頻率       |       0 |      50 |    10 |         45 |                                          |
| z_frequency      | Integer   | Hz    | Z軸頻率       |       0 |      50 |    50 |         45 |                                          |
| avg_ele_current  | Float     | A     | 平均電流      |       0 |       5 |     1 |          4 |                                          |
| avg_ele_volt     | Float     | V     | 平均電壓      |     190 |     250 |    10 |  198\\ 242 |                                          |
| light            | Integer   |       | 燈號啟動狀態  |         |         |       |            | 0 為異常燈號（橘）\\ 1 為正常燈號（綠）  |

==== 2. 警戒值設定資料 (Alert Settings) ====

=== 基本資訊 ===
  * **Topic**: ''/mrt/xiaobitan/{station_id}/alert_setting''
  * **方向**: 侑盈系統 -> 捷運站；當使用者在侑盈 EMS 上進行數值變更的時候，通知捷運站 IPC
  * **用途**: 動態調整監控閾值

=== 資料結構 ===

<code javascript [enable_line_numbers="true"]>
{
    "v_high": 242,
    "v_low": 198,
    "i_high": 1.9,
    "i_low": 0,
    "dxyz_displacement_high": 30,
    "dxyz_displacement_low": 0,
    "dxyz_fz_high": 45,
    "dxyz_fz_low": 0,
    "temp_high": 48.0,
    "temp_low": 0,
    "info": {
        "position": "xiaobitan_station",
        "device_id": "IRM-001",
        "timestamp": "2025-06-04 12:47:11"
    }
}
</code>

=== 警戒值對照表 ===

^ 監控項目 ^ 高警戒值 ^ 低警戒值 ^ 正常範圍 ^ 備註 ^
| 電壓 | 242V | 198V | 190V~250V | Y軸監控 |
| 電流 | 1.9A | 0A | - | 超過即警報 |
| 位移量 | 30mm | 0mm | 0~50mm | XYZ軸綜合 |
| 頻率 | 45Hz | 0Hz | 0~50Hz | XYZ軸綜合 |
| 溫度 | 48.0°C | 0°C | - | 環境溫度 |

=== 告警值接收資料欄位說明 ===
^ 鍵（Key）               ^ 資料說明          ^ 型別     ^ 單位  ^
| v_high                  | 電壓過高警報      | Float    | V     |
| v_low                   | 電壓過低警報      | Float    | V     |
| i_high                  | 電流過高警報      | Float    | A     |
| i_low                   | 電流過低警報      | Float    | A     |
| dxyz_displacement_high  | 三軸位移過高警報  | Integer  | um    |
| dxyz_displacement_low   | 三軸位移過低警報  | Integer  | um    |
| dxyz_fz_high            | 三軸頻率過高警報  | Integer  | Hz    |
| dxyz_fz_low             | 三軸頻率過低警報  | Integer  | Hz    |
| temp_high               | 溫度過高警報      | Float    | °C    |
| temp_low                | 溫度過低警報      | Float    | °C    |

==== 3. 警報記錄資料 (Alert Log) ====

=== 基本資訊 ===
  * **Topic**: ''/mrt/xiaobitan/{station_id}/alert_log''
  * **方向**: 捷運站 → 侑盈系統
  * **用途**: 異常事件記錄與追蹤

=== 資料結構 ===

<code javascript [enable_line_numbers="true"]>
{
    "v_high_alert": 250, // 電壓過高警報
    "temp_low_alert": 10, // 溫度過低警報
    // ... (略)
    "info": {
        "position": "xiaobitan_station", // 小碧潭捷運站
        "device_id": "IRM-001", // 設備代號
        "timestamp": "2025-06-04 12:47:11" // 發生時間戳
    }
}
</code>

=== 事件記錄範例 ===

^ 時間戳記             ^ 事件類型    ^ 詳細內容            ^
| 2025-10-11 03:05:06  | 系統操作    | 執行復歸程序        |
| 2025-10-10 03:05:06  | 觸及警戒值  | 電壓過高警報：250V  |
| 2025-10-10 03:05:06  | 觸及警戒值  | 溫度過低警報：10°C  |

==== 4. 復歸控制訊號 (Switch Light) ====

=== 基本資訊 ===
  * **Topic**: ''/mrt/xiaobitan/{station_id}/switch_light''
  * **方向**: 侑盈系統 → 捷運站
  * **用途**: 遠端復歸控制

=== 資料結構 ===

<code javascript [enable_line_numbers="true"]>
{
    "light": 0,
    "info": {
        "position": "xiaobitan_station",
        "device_id": "IRM-001",
        "timestamp": "2025-06-04 12:47:11"
    }
}
</code>

=== 燈號說明 ===

^ 指令值  ^ 功能  ^ 說明      ^
| 0       | 橘燈  | 異常燈號  |
| 1       | 綠燈  | 正常燈號  |

===== 公共資料結構 =====

==== Info 物件規格 ====
  * 所有 MQTT 訊息都包含統一的 ''info'' 物件
  * 符合 [[https://zh.wikipedia.org/zh-tw/ISO_8601|ISO 8601]] 標準的一個變體，台灣日光節約使用 +8

<code javascript>
"info": {
    "position": "xiaobitan_station",    // 站台識別碼
    "device_id": "IRM-001",            // 設備編號
    "timestamp": "2025-06-04 12:47:11" // 資料時間戳記 (YYYY-MM-DD HH:mm:ss)
}
</code>


===== 注意事項 =====

==== QoS 設定建議 ====
  * 原始監控資料: QoS 0 (頻繁傳輸，允許遺失)
  * 警戒值設定: QoS 1 (確保送達)
  * 警報記錄: QoS 1 (重要事件記錄)
  * 復歸控制: QoS 2 (關鍵控制指令)

==== 錯誤處理 ====
  * 連線中斷時自動重連
  * 資料格式驗證失敗時記錄錯誤
  * 超過警戒值時立即發送警報

==== 安全考量 ====
  * 建議使用 TLS/SSL 加密傳輸
  * 實作適當的認證機制
  * 定期更新密碼或憑證