---
# System prepended metadata

title: P5 顯示器 MQTT 通訊規格

---

# P5 顯示器 MQTT 通訊規格

## MQTT Broker

- version: v3.1.1 min 
- security: 
    - username/password
    - x509 certificate (optional)

### MQTT Topic format
```jsonld=
/{vendor}/{deviceId}/{direction}/{topic}/{subTopic}
```
|API  |型別|描述  |範例   |Note|
|-----|----|-----|------|-----|
|{vendor}| string |廠商縮名|'chengwei'| 必要 |
|{deviceId}| string |設備 ID|'廠商前頭-wifi_mac_addr'| 必需為 uniqueId |
|{direction}| string |topic/payload 方向|'upstream' 'downstream' | 必要 |
|{topic}| string |MQTT話題|'topic'| 必要
|{subTopic} | string | Sub 話題 |'sub topic'| 非必要 (最多兩階) |


## MQTT Downstream Topics (後台: broker 對 設備: client)

### 事件新增 API
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/disp_event/add
```

#### payload
```jsonld=
[
    {
        eventId: "mhvXdrZT4jP5T8vBxuvm75",
        event_line_1: "離床過久",
        event_line_2: "王張阿明 302A",
        priority: 1,
        ring_tone: true
    },
    {
        eventId: "P5T8vBxumhvXdrZT4jvm75",
        event_line_1: "離床",
        event_line_2: "林阿琳 401B",
        priority: 0,
        ring_tone: false
    },
    {
        eventId: "rZT4jP5TmhvXd8vBxuvm75",
        event_line_1: "久臥",
        event_line_2: "陳啊勳 102D",
        priority: 1,
        ring_tone: false
    }
]

```
#### priority logic
|high priority|low priority|
|--|--|
|1|0|
|插入下一個顯示輪巡|按照目前輪巡排列最後|

#### ring tone logic
|true|false|
|--|--|
|play ring tone | no ring tone|

### 事件刪除 API
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/disp_event/del
```

#### payload
```jsonld=
{
    eventId: "mhvXdrZT4jP5T8vBxuvm75",    
}
```

### 事件輪詢週期設定 API
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/disp_event/rotate
```
#### payload
```jsonld=
{
    display_time: true    // 輪巡末顯示萬年曆與否
    period: 3000         // unit = milli-second
}
```

### 文宣 Notice 新增 API
> (6字2行) 
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/disp_notice/add
```

#### payload
```jsonld=
{
    notice_id: "jP5T8vBxuvm75mhvXdrZT4",
    notice_line_1: "勤洗手保健康",
    notice_line_2: "武肺嘸免驚驚",    
}
```
### 文宣 Notice 刪除 API
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/disp_notice/del
```
#### payload
```jsonld=
{
    notice_id: "jP5T8vBxuvm75mhvXdrZT4"
}
```

### 鈴聲時段音量設定 API
> Question: 請問一台可放多少 *.wav 檔? 如何更新 *.wav
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/config_ringtone
```
#### payload
```jsonld=
{
    filename: "file_name.wav",
    ring_setting: "/001-093-222"    
}
```

### Group 設定 API
> 定義 p5 display 安裝空間位置
#### topic
```jsonld=
/chengwei/{deviceId}/downstream/config_group
```
#### payload
```jsonld=
{
    floor: "1F",
    group: "zone_1"
}
```

### WiFi 設定 API
#### topic
```jsonld=
TBD
```
#### payload
```jsonld=
{
    ssid: "wifi_ssid",
    password: "wifi_password"
}
```

-----
## MQTT Upstream Topics (設備: client -> 後台: broker)

|Topic|Format|描述|
|-----|-----|-----|
|'status'|JSON|定時回報設備狀態|
| |JSON|設定回覆結果|


### Display Status API
> 設備狀態定時回報後台 (Broker)
#### topic
```jsonld=
/chengwei/{deviceId}/upstream/status
```
#### payload
```jsonld=
{
    model: "chengwei_p5_display",
    version: "vx.x",            // firmware version
    wifi: {
        mac: "30AEA4E37424",    // wifi mac
        rssi: -51,              // current wifi rssi
        ssid: "jubo-lte",       // wifi ssid 
        password: "1234567",    // wifi password
    },
    time: 1665647853,           // device time in unix timestamp
    display_events: [           // event_ids displaying, 5 max.
        "mhvXdrZT4jP5T8vBxuvm75",     // shorten uuid
        "73WakrfVbNJBaAmhQtEeDv"...],
    display_notice: "jP5T8vBxuvm75mhvXdrZT4",
    display_period: 3000,  // 幕次輪巡時間間隔
    display_time: true,
    ringtone: {
        filename: "file_name.wav",
        ringtone_setting: "/001-093-222"
    },
    floor: "1F",
    group: "zone_1",
}
```

### Event 設定回覆 API
> 事件顯示設定回報後台 (新增, 刪除, 和 輪巡時間)
#### topic
```jsonld=
/chengwei/{deviceId}/upstream/disp_event
```
#### payload
```jsonld=
{
    original_payload: {
        ...
    }
    success: false,
    reason: "max. 5 events",
}
```


#### topic
```jsonld=
/chengwei/{deviceId}/upstream/disp_event/rotate
```
#### payload
```jsonld=
{
    success: false,
    reason: "invalid_filename / invalid_period",
}
```

### 文宣 Notice 設定回覆 API
#### topic
```jsonld=
/chengwei/{deviceId}/upstream/disp_notice/add
/chengwei/{deviceId}/upstream/disp_notice/del
```

#### payload
```jsonld=
{
    eventId: "jP5T8vBxuvm75mhvXdrZT4",    // shorten uuid
    success: false,
    reason: "too_many_characters / unknown_id",
}
```

### 鈴聲時段音量設定回覆 API
#### topic
```jsonld=
/chengwei/{deviceId}/upstream/config_ringtone
```
#### payload
```jsonld=
{
    filename: "file_name.wav",
    ring_setting: "/001-093-222", 
    success: false,
    reason: "invalid_format / unknown_file"
}
```

### Group 設定回覆 API

#### topic
```jsonld=
/chengwei/{deviceId}/upstream/config_group
```
#### payload
```jsonld=
{
    floor: "1F",
    group: "zone_1",
    success: false,
    reason: "name_too_long"    
}
```

### WiFi 設定回覆 API
#### topic
```jsonld=
TBD
```
#### payload
```jsonld=
TBD
```