FogCloud设备端接口文档（V3.1）

V3.1

服务地址

• https://cnapitest.fogcloud.io

ErrorCode说明

• 所有接口里，成功的code为0，其他code请参考接口说明。

参数说明

• GET/DELETE参数：请封装在请求的URL中
• POST/PUT参数：请封装在请求的body里

设备激活接口

POST /v3_1/device/activation/

• 设备端使用该接口进行激活。如果设备首次激活，接口调用成功后，会在IOT Server上注册设备和设置Topic权限;并返回相关数据用于登录MQTT Server；如果是二次激活，密码正确，返回登录MQTT相关数据，密码错误，接口报错

请求参数

返回值

    {
    "meta": {
        "message": "activate ok",
        "code": 0
    },
    "data": {
        "host": "4701f1c4f7...",
        "common_port": 1883,
        "endpoint_name": "4701f1c4f78411e7...",
        "ssl_port": 1884,
        "password": "i7wZWg+rXH0fH9Gju9k...",
        "device_id": "eee4f85ef78511e..."
    }
}

登录MQTT数据说明

• username为endpoint_name/device_id（注意“/”）
• client_id使用device_id

Topic规则：

• status：设备数据主题；设备端发布，控制端（前端或手机APP等）订阅；
• command：设备指令主题；控制端发布，设备端订阅；
• online：设备在离线状态主题；设备端发布，控制端订阅；设备上/下线时需要往该主题发布数据；
• api：MQTT方式调用云端接口的主题；仅设备端可以使用，权限为发布；
• sys：接口Response主题；由云端Admin账户发布数据，设备端订阅该主题来接收api主题的Response等

错误码

设备端superuser检查

PUT /v3_1/device/superuser/check/

• 设备端主动检查设备是否已经绑定超级用户

请求参数

说明

req_type:0 → 消费者程序使用

• 此种方式时，设备不调用http接口，而是需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"superuser",
    "data":{
        "req_id":123...  
    }
}

• 设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "data":{
        "has_superuser":false
    },
    "meta":{
        "message":"check ok",
        "code":0
    },
    "type":"superuser",
    "req_id":123..
}

req_type:1 → 设备端通过HTTP方式check

返回值

{
    "meta":{
        "message":"check ok",
        "code":0
    },
    "data":{
        "is_virtual":true,
        "has_superuser":true,
        "phone":"",
        "req_id":123...,
        "enduser_id":"4d1939513ede...",
        "email":""
    }
}

字段说明

错误码

设备端解绑接口

PUT /v3_1/device/unbind/

• 设备端主动触发解绑动作，会解除所有用户。提供http和mqtt两种方式调用，公版项目使用mqtt方式调用，详见下面说明。

请求参数

req_type:0 → 消费者程序使用

• 此种方式时，设备需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"unbind",
    "data":{
        "password": "fabax..."
        "req_id":123...
    }
}

• 设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "data":{
    },
    "meta":{
        "message":"unbind success",
        "code":0
    },
    "type":"unbind",
    "req_id":123...
}

req_type:1 → 设备端通过HTTP方式解绑

返回值

{
    "meta": {
        "message": "unbind success",
        "code": 0
    },
    "req_id": 123,
    "data": {
    }
}

字段说明
无

错误码

FOG设备通过设备ID检查OTA

PUT /v3_1/ota/device/

• 设备自检查OTA，可以使用http和mqtt两种方式调用。

请求参数

req_type:0 → 消费者程序使用

• 此种方式时，设备需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"ota_check",
    "data":{
        "password": "112xx...",
        "component": "xxxx"  # 可选参数
        "req_id":123...
    }
}

• 设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "type": "ota_check",
    "meta":{
        "message":"ota file info",
        "code":0
    },
    "data":{
        "files":[
            {
                "file_url":"https://test.com/a.bin",
                "component":"test1",
                "md5":"1abx..",
                "version":"1.0.1",
                "customize":""
            },
            {
                "file_url":"https://test.com/a.bin",
                "component":"test2",
                "md5":"1safa...",
                "version":"1.0.1",
                "customize":""
            }
        ],
        "ot_id":25,
        "req_id": 123...
    }
}

req_type:1 → 设备端通过HTTP方式解绑

返回值

{
    "meta":{
        "message":"ota file info",
        "code":0
    },
    "data":{
        "files":[
            {
                "file_url":"https://test.com/a.bin",
                "component":"test1",
                "md5":"1abx..",
                "version":"1.0.1",
                "customize":""
            },
            {
                "file_url":"https://test.com/a.bin",
                "component":"test2",
                "md5":"1safa...",
                "version":"1.0.1",
                "customize":""
            }
        ],
        "ot_id":25
    }
}

字段说明

说明

• ot_id：对应该升级文件的OTA任务ID；更新完成，需调用OTA完成的通知接口，上报更新完成状态给云端，此接口参数中用到ot_id。

错误码

设备发送OTA完成的通知

PUT /v3_1/ota/device/log/

• 设备发送OTA完成的通知

请求参数

req_type:0 → 消费者程序使用

• 此种方式时，设备需要向api/json topic中发送mqtt消息，请求的消息格式为:

{
    "type":"ota_log",
    "data":{
        "password": "112xx...",
        "ot_id": 1
        "is_finished": true,
        "components": ["bbbb", "aavc"]  # 可选参数
        "req_id":123...
    }
}

• 设备还需订阅sys/json topic用来接收云端返回的api结果，返回的消息格式为：

{
    "type":"ota_log",
    "meta":{
        "message":"ota log ok",
        "code":0
    },
    "req_id":123，
    "data":{
    }
}

req_type:1 → 设备端通过HTTP方式调用

返回值

{
    "meta":{
        "message":"ok",
        "code":0
    },
    "data":{
    }
}

错误码

设备获取时区信息

PUT /v3_1/device/timezone/

• 设备获取当前管理员的时区作为自己的时区。

请求参数

req_type:1 → 设备端通过HTTP方式调用

返回值

{
    "meta": {
        "message": "check ok",
        "code": 0
    },
    "data": {
        "timezone": "+8"
    }
}

错误码