openproxy cloud API reference

1.overview

The use process of the final customer includes: device configuration, discovery and pairing, device registration, device state query, device control, device data reporting, RM panel addition and other processes.

Pls see the below callflow：

2.Cloud API

Note： you can get “devicePairedInfo” from configurate sdk after configurating a device, the third cloud need to save it. and pass it to Broadlink API when you operate this device.

2.1 Device registration

Note：you need call this API if you want to do data reporting.

POST https://(OpenproxyURL)//openproxy/v2/register?license=(license)

Request：
{
    "directive": {
        "header": {
            "namespace": "DNA.Register",
            "name": "Register",
            "interfaceVersion": "2",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "device": {
              "devicePairedInfo": {
                "mac":"",
                "did":"",
                "pid":"",
                "cookie":base64(cookieStu) 
              }      
            },
            "uploadinfo":{
                "lid":"xxxxxxxxx",
            }//when you want to do data reporting, you should add this field, otherwise,this field don't need to be token.(this function haven't open yet)
        }
    }
}

Response：
{
    "context": {},
    "event": {
        "header": {
            "namespace": "DNA.Register",
            "name": "Response",
            "interfaceVersion": "2",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
        },
        "endpoints": [
            {
                "endpointId": "appliance-001"，//device id
                "friendlyName": "bedroom lamp",//default device name
                "description": "Lamp produced by BroadLink",
                "manufacturerName": "Sample Manufacturer",
                "icon":"product icon URL",
                "brand":"brand",
                "displayCategories": [
                    "LIGHT"
                ],
                "cookie": {
                },
                "capabilities": [
                    {
                        "type": "DNAInterface",
                        "interface": "DNA.PowerControl",
                        "version": "2",
                        "properties": {
                            "supported": [
                                {
                                    "name": "powerState"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                       "actions": {
                           "supported": [
                            {
                                 "name": "ChangePowerState"
                            }
                           ]
                       }
                    }
                ]
            }
        ]
    }
}

2.2 Control API

POST https://(OpenproxyURL)/openproxy/v2/opencontrol?license=(license)
Request：
{
  "directive": {
    "header": {
       "namespace": "DNA.PowerControl",
       "name": "ChangePowerState",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"//random string
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",//device id
      "devicePairedInfo":{}
    },
    "payload": {
        "powerState":"OFF"
    }
  }
}
Response：
{
  "context": {
    "properties": [ {
       "namespace": "DNA.PowerControl",
       "name": "powerState",
       "value": “ON”,
       "timeOfSample": "2017-02-03T16:20:50.52Z",
    } ]
  },
  "event": {
    "header": {
       "namespace": "DNA.PowerControl",
       "name": "Response",
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoint": {
      "endpointId": "appliance-001"
    },
    "payload": {
    }
  }
}

2.3 Batch query online/offline status of device

Query 32 devices’ online/offline status at most at one time

POST https://(OpenproxyURL)/openproxy/v2/querystate?license=(license)
Request：
{
  "directive": {
    "header": {
       "namespace": "DNA.QueryState",
       "name": "QueryState",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoints": [{
      "endpointId": "Some-Device-ID",
       "devicePairedInfo":{}
    }],
    "payload": {
    }
  }
}
Response：
{
  "context": {
    "properties": []
  },
  "event": {
    "header": {
       "namespace": "DNA.QueryState",
       "name": "Response",
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoints": [{
      "endpointId": "appliance-001",
      "state": "online"
    }],
    "payload": {
    }
  }
}

2.4 Query on/off status of device

POST https://(OpenproxyURL)/openproxy/v2/opencontrol?license=(license)
Request：
{
  "directive": {
    "header": {
       "namespace": "DNA",
       "name": "ReportState",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",
       "devicePairedInfo":{}
    },
    "payload": {
    }
  }
}
Response：
{
  "context": {
"properties": [
        {
           "namespace": "DNA",
           "name": "powerState",
           "value":{
                "value":"ON",
                "scale":"",
                "attributeName":""
                "scaleName":"",
                "valueName":""
           },
           "timeOfSample": "2017-02-03T16:20:50.52Z",
        }
    ]

  },
  "event": {
    "header": {
       "namespace": "DNA.QueryState",
       "name": "Response",
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoint": {
      "endpointId": "appliance-001",
    },
    "payload": {
    }
  }
}

2.5 Device management API

• Query OTA Version

POST https://(OpenproxyURL)/openproxy/v2/firmware?license=(license)
Request：
{
  "directive": {
    "header": {
       "namespace": "DNA.ManagerControl",
       "name": "QueryVersion",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",
      "devicePairedInfo":{}
    },
    "payload": {
        "getServerVersion":true
    }
  }
}
Response：
{
  "context": {
    
  },
  "event": {
    "header": {
       "namespace": "DNA.ManagerControl",
       "name": "Response",
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoint": {
      "scope": {
      },
      "endpointId": "appliance-001"
    },
    "payload": {
	       "serverversion": {
                "url": "http://fwversions.ibroadlink.com/firmware/download/10039/55.bin",//updating url of the newest firmware on server
                "devtype": "10039", //device type
                "version": "55"     //the newest firmware
            },
            "version": "55"        //the device's firmware version which you are querying

    }
  }
}

• Update OTA version

POST https://(OpenproxyURL)/openproxy/v2/firmware?license=(license)
Request：
{
  "directive": {
    "header": {
       "namespace": "DNA.ManagerControl",
       "name": "OTAUpgrade",
       "interfaceVersion": "2",
       "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
    },
    "endpoint": {
      "endpointId": "Some-Device-ID",
      "devicePairedInfo":{}
    },
    "payload": {
        "url":"xxxx"
    }
  }
}
Response：
{
  "context": {
    "properties": [ {
       "namespace": "DNA.ManagerControl",
       "name": "OTAUpgrade",
       "value": "b445sdfafad112224sdf",
       "timeOfSample": "2017-02-03T16:20:50.52Z",
    } ]
  },
  "event": {
    "header": {
       "namespace": "DNA.ManagerControl",
       "name": "Response",
       "interfaceVersion": "2",
       "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
    },
    "endpoint": {
      "endpointId": "appliance-001"
    }
    "payload": {
	    
    }
  }
}

2.6 Device data reporting

POST https://YOURURL

1.online/offline

{
	"context": {},
	"event": {
		"header": {
			"namespace": "DNA",
			"name": "ChangeReport",
			"payloadVersion": "3",
			"messageId": "qlo4-vr2mjbygqx9hymif"
		},
		"endpoint": {
			"endpointId": "00000000000000000000780f7781087d",
			"devtype": "32013"
		},
		"payload": {
			"change": {
				"cause": {
					"type": "PHYSICAL_INTERACTION",
					"msgtype": 10003
				},
				"properties": [{
					"namespace": "DNA.EndpointHealth",
					"name": "connectivity",
					"value": {
						"value": "UNREACHABLE"
					},
					"timeOfSample": "2018-09-06T11:46:55.52Z",
					"uncertaintyInMilliseconds": 0
				}]
			}
		}
	}
}
2.on/off（message type is 34）

{
	"context": {},
	"event": {
		"header": {
			"namespace": "DNA",
			"name": "ChangeReport",
			"payloadVersion": "3",
			"messageId": "8kua-vviwdgkmxutb5s3r"
		},
		"endpoint": {
			"devtype": "32009",
			"endpointId": "00000000000000000000780f774fc726"
		},
		"payload": {
			"change": {
				"cause": {
					"type": "PHYSICAL_INTERACTION",
					"msgtype": 34
				},
				"properties": [{
					"namespace": "DNA.PowerControl",
					"name": "powerState",
					"value": "ON",
					"timeOfSample": "2019-01-17T11:39:11.52Z",
					"uncertaintyInMilliseconds": 0
				}]
			}
		}
	}
}
3.heartbeat

{
	"context": {},
	"event": {
		"header": {
			"namespace": "DNA",
			"name": "HeartBeat",
			"payloadVersion": "3",
			"messageId": "smrn-xr615ouot38qd431"
		},
		"endpoint": {
			"endpointId": "00000000000000000000780f7751ecfb",
			"devtype": "10178"
		},
		"payload": {
			"change": {
				"cause": {
					"type": "PHYSICAL_INTERACTION",
					"msgtype": 10007
				},
				"properties": [{
					"namespace": "DNA.HeartBeat",
					"name": "HeartBeat",
					"value": {
						"ip": [67, 193, 1, 69],
						"port": 49161,
						"res": 0
					},
					"timeOfSample": "2019-01-17T11:38:05.52Z",
					"uncertaintyInMilliseconds": 0
				}]
			}
		}
	}
}
4.passthrough report, apply to other message type

{
	"context": {},
	"event": {
		"endpoint": {
			"endpointId": "00000000000000000000c411e004a2b1",
			"devtype": "32512"
		},
		"header": {
			"namespace": "DNA.TransmissionReport",
			"name": "Report",
			"payloadVersion": "3",
			"messageId": "nupp-xge3vtpwgy22fn6y"
		},
		"payload": {
			"data": "7b22707772223a302c226d6178776f726b74696d65223a302c22706964223a223030303030303030303030303030303030303030303030303030376630303030222c22646964223a223030303030303030303030303030303030303030633431316530303461326231227d",
			"change": {
				"cause": {
					"msgtype": 54
				}
			}
		}
	}
}
5. device field's data reporting（message type is 54）
{
	"context": {},
	"event": {
		"header": {
			"namespace": "DNA",
			"name": "ChangeReport",
			"payloadVersion": "3",
			"messageId": "5ike-psu4w0f2ounvpqkg"
		},
		"endpoint": {
			"endpointId": "00000000000000000000b4430d96b522",
			"devtype": "20010"
		},
		"payload": {
			"change": {
				"cause": {
					"type": "54"
				},
				"properties": [{
					"namespace": "DNA",
					"name": "temperatureAmbient",
					"value": 23,
					"timeOfSample": "2019-02-28T06:40:40.89Z",
					"uncertaintyInMilliseconds": 0
				}, {
					"namespace": "DNA",
					"name": "mode",
					"value": "DEHUMI",
					"timeOfSample": "2019-02-28T06:40:40.89Z",
					"uncertaintyInMilliseconds": 0
				}, {
					"namespace": "DNA",
					"name": "windSpeed",
					"value": "LOW",
					"timeOfSample": "2019-02-28T06:40:40.89Z",
					"uncertaintyInMilliseconds": 0
				}, {
					"namespace": "DNA",
					"name": "fixedTargetTemperature",
					"value": 24,
					"timeOfSample": "2019-02-28T06:40:40.89Z",
					"uncertaintyInMilliseconds": 0
				}, {
					"namespace": "DNA",
					"name": "powerState",
					"value": "ON",
					"timeOfSample": "2019-02-28T06:40:40.89Z",
					"uncertaintyInMilliseconds": 0
				}]
			}
		}
	}
}

2.7 Error response

-Error response format

For example：
{
  "context": {},
  "event": {
      "header": {
      "namespace": "DNA.PowerControl",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "name": "ErrorResponse",
      "payloadVersion": "2"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
        "type": "ENDPOINT_UNREACHABLE", //error type
        "message":"xxx",
    }
  }

• Error code

• status chart