# Jubox Restful IOT API ## Authentication 新增設備後通知 Jubo 後台註冊。 | Protocol | Type | Method | URL | |-----------|-------|--------|-----| | HTTP(s) |Auth/Login|POST|{baseURL}/api/v1/iot/auth/login| ### Auth body ###### api: ```json= { "username": username, "password": password } ``` ###### example: ```json= { "username": 'vendor01', "password": 'xxxxxxxx' } ``` ### Auth Response ###### api: ```json= { "token": "token-body", "user": { "tokenExpiry": "ISO8601 format timestamp", "organization": "organization_name" } } ``` ###### example: ```json= { "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJOdXJzaW5nIEJlbGwiLCJhcHBJZCI6Ikp1Ym8gQm94IiwiaXNzIjoiSnVibyBJbmMuIiwidmVuZG9ySWQiOiIwMkEwRjEzQjI5NEEiLCJleHAiOiIxNjI3MjgxOTg0IiwiaWF0IjoiMTYyNzg4Njc4MyJ9.3JMy_dEOWWhqenxfiQUi57EEs0KPf22E-4uYtljwOT4", "user": { "tokenExpiry": "2021-08-02T06:46:23.976643Z", "organization": "Vendor IOT Account" } } ``` ## JSON Web Token * Algorithm: RS256 ## JWT format ### JWT Header ```json= { "alg": "RS256", "typ": "JWT", } ``` ### JWT Payload ```json= { "iss": "Jubo Health" "iat": 1627886783, "exp": 1627281984, "organizationId" : "60feb7555a27d5a1cc38b0e9", "sub": "Device Application Name" "appId": "TBD" } ``` ## Device Register 新增設備後通知 Jubo 後台註冊。 | Protocol | Type | Method | URL | |-----------|-------|--------|-----| | HTTP(s) |Register New Device|POST|{baseURL}/api/v1/iot/{vendorName}/register| ### Register Header Authorization: Bearer {{ JWT }} ### Register Body | Type | Content | |------|------| | JSON | [register_body](#register_body) | ### Register Response | Type | Content | |------|------| | JSON | [register_response](#register_response) | #### register_body ###### api: ```json { "vendorId": "vendorId", // 廠商定義 "brand": "brandName", "name": "中文名稱", "type": "categoryType", } ``` ###### example: ```json= { "vendorId": "02A0F13B294A", // 廠商定義 "brand": "BRAND", "name": "中文名稱", "type": "description", } ``` #### register_response ###### api: ```json= 200 OK { "vendorId": "Vendor Device Idenfitication", "deviceId": "Device Identification", // 智齡定義 "name": "中文名稱", "type": "categoryType", "state": "Active", "config": null, } 401 Unauthorized // JWT Auth Fail 409 Duplicate // Record Already Exists ``` ###### example: ```json= { "vendorId": "02A0F13B294A", "deviceId": "tada-bell-000001", // 智齡定義 "name": "中文名稱", "type": "description", "state": "Active", "config": null, } ``` # Jubox MQTT IOT API ------- ## MQTT Specification * version: v3.1.1 * Qos: 1 ## Security Options * Login: username/password * ------- ## MQTT API ### MQTT Topic Format ```jsonld= /{vendor}/{deviceType}/{vendorId}/{topics}/{subTopic} ``` |API |型別|描述 |範例 |Note| |-----|----|-----|------|-----| |{vendor}| string |廠商縮名|'jubo'|4個英數文字為限 | |{deviceType}|string|設備類別|gateway/end-point | 有樹狀結構設備者為必要 | |{deviceId}| string |設備型號|'廠商定義'| 必需為 uniqueId | |{topic}| string |MQTT話題|'topic'| 通常為 event |{subTopic} | string | Sub 話題 |'sub topic'| 非必要 (最多兩階) | ----- ### MQTT Upstream Topics * 以下為 Jubox MQTT 標準上行 Topic (Device to Broker) |Topic|Format|描述|範例| |-----|-----|-----|-----| |'connect'|JSON|連線提供JWT |[connect](#connect)| |'state' |JSON|回報設備狀態 |[state](#state) | |'events/config'|JSON|被設定回報設定內容 |[events/config](#events/config) | |'events' |JSON|回報應用事件 |[events](#events) | #### connect * CONNACK 成功後需發出的第一個 Topic ###### example ```json= { password: Bearer {{ JWT }} } ``` #### state * 回報設備狀態 * 定時回報 * 0: online, 1: offline, 2: normal-power, 3: battery-power, 4. tamper ###### example ``` /brand/device_class/02A0F13B294A/state ``` ```json= { state: stateEnum, // additional info such as connection, battery info wifi: { rssi: "-15dbm", ssid: "jubo-lte", }, battery: "75%", } ``` #### events/config * 遠端設定後回報新設定值 ###### example ``` /tada/nursingBell/02A0F13B294A/events/config ``` ```json= { config: { ... } } ``` #### events * 標準設備 events ###### example ``` /tada/nursingBell/02A0F13B294A/events ``` ```jsonld= { // 廠商定義 } ``` ----- ### MQTT Downstream Topics * 以下為 Jubox MQTT 標準下行 Topic (Broker to Device) /{vendor}/{deviceType}/{vendorId}/{topics} |Topic|Format|描述|範例| |-----|-----|-----|-----| |'config' |JSON|定時回報設備狀態 |[config](#config) | |'restart'|JSON|被設定回報設定內容 |[restart](#restart) | #### config ###### example ``` /brand/device_class/02A0F13B294A/config ``` ```jsonld= { config: { ... // 依照廠商設備設定定義 } } ``` #### restart ###### example ``` /brand/device_class/02A0F13B294A/restart ``` ```jsonld= { } ```