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

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

    }
  }
}
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",
    }
  }
Field Description Note
ENDPOINT_UNREACHABLE Device offline
NO_SUCH_ENDPOINT Have no this device
INVALID_REQ Wrong request format
DEVICE_RESET Device have been reseted
INVALID_DIRECTIVE Wrong command
INVALID_ACCESSTOKEN Invaild token
INVALID_SIGNATURE Illegal signature
INTERNAL_ERROR Other errors
VALUE_OUT_OF_RANGE
FUNCTION_NOT_SUPPORT
UNDERSTAND_FAILURE
SERVICE_UNAVAILABLE Server unavailable Returns when the service timeout or exception
NETWOEK_TIME_OUT Network time out
Field Description Note
0 Success
-49001 Network timeout
-49002 Server error
-3 Device offline
-49004 Error params
-5 Device no response
-49006 Error request
-7 Device rest
-49008 Error request command
-49010 Have no this device
-49011 Error request content
-49039 Error server cache
-49019 Error ip whitelist
-49024 Have no AC GZ file
-49037 Vaule is out of range
-49103 Don’t support this function
-49022 Function parameters are not supported
-49026 Request length exceeded limit
-49021 IR code is too long
-49018 Signature check fails