---
# System prepended metadata

title: Jubox Restful IOT API

---

# 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=
{ }

```





