The Predictive Discovery Endpoint utilizes device fingerprinting techniques to retrieve information about a device , such as type, brand, and model , with varying degrees of confidence using different types of signatures such as SSDP (Simple Service Discovery Protocol), TCP/IP mDNS, and MAC Address. The input to this API is a ueiRC and an inputJSON. The inputJSON provides the data needed for QuickSet Cloud to identify all characteristics of a device.
The inputJSON provides the data needed for QuickSet Cloud to identify all characteristics of a device using SSDP, mDNS or MAC signatures.
The following elements are required:
Note that depending on the signature passed in, the value of signatures will be different. The following signature types are currently available :
The following examples will show how to format the inputJSON depending on whether the SSDP, mDNS or MAC type is chosen.
The SSDP information is a Base64-encoded string of the device description XML, retrieved from the device over the network. This requires searching for available devices and services by multicasting an SSDP M_SEARCH message using an HTTP multicast over UDP request and must be converted to a Base64 encoded string prior to passing it as a parameter.
Please Note: The Base64 encoding for SSDP is only required for the general Predictive Discovery endpoint, not for the Predictive Discovery SSDP endpoint. When utilizing the Predictive Discovery SSDP endpoint, you can provide the unencoded SSDP device description in the body of the request.
{
'Devices':[
{
'DeviceID':1,
'Signatures':{
'SSDP':[
'PHJvb3QgeG1sbnM9InhtbG5zPSZxdW90O3VybjpzY2hlbWFzLXVwbnAtb3JnOmRldmljZS0xLTAmcXVvdDsiPjxzcGVjVmVyc2lvbiB4bWxucz0iIj48bWFqb3I+MTwvbWFqb3I+PG1pbm9yPjA8L21pbm9yPjwvc3BlY1ZlcnNpb24+PGRldmljZSB4bWxucz0iIj48ZnJpZW5kbHlOYW1lPltUVl0gSG9tZTwvZnJpZW5kbHlOYW1lPjxtYW51ZmFjdHVyZXI+U2Ftc3VuZyBFbGVjdHJvbmljczwvbWFudWZhY3R1cmVyPjxtYW51ZmFjdHVyZXJVUkw+aHR0cDovL3d3dy5zYW1zdW5nLmNvbS9zZWM8L21hbnVmYWN0dXJlclVSTD48bW9kZWxEZXNjcmlwdGlvbj5TYW1zdW5nIFRWIE5TPC9tb2RlbERlc2NyaXB0aW9uPjxtb2RlbE5hbWU+VUU0MEY2NDAwPC9tb2RlbE5hbWU+PG1vZGVsTnVtYmVyPjEuMDwvbW9kZWxOdW1iZXI+PC9kZXZpY2U+PC9yb290Pg=='
]
},
'FormatVersion':1
}
]
}
You can use the mDNS Signature to pass in the ’ServiceNames’ and/or ’HostNames’ of a device advertised by the device (see below for example of Apple TV).
{
'ServiceNames':[
'Apple TV._airplay._tcp.local',
'C869CD6720CF@Apple TV._raop._tcp.local',
'Apple TV._mediaremotetv._tcp.local',
'2d7d5e98003e7579f88167836cc59e8f8f4ceb4f._touch-able._tcp.local',
'70-35-63-60.1 Apple TV._sleep-proxy._udp.local'
],
'HostNames':[
'Apple-TV.local'
]
}
After forming your mDNS Signature, you can add the signature to your inputJSON object. Here is an example inputJSON using mDNS:
{
'Devices':[
{
'DeviceID':1,
'Signatures':{
'mDNS':[
{
'ServiceNames':[
'Apple TV._airplay._tcp.local',
'C869CD6720CF@Apple TV._raop._tcp.local',
'Apple TV._mediaremotetv._tcp.local',
'2d7d5e98003e7579f88167836cc59e8f8f4ceb4f._touch-able._tcp.local',
'70-35-63-60.1 Apple TV._sleep-proxy._udp.local'
],
'HostNames':[
'Apple-TV.local'
]
}
]
},
'FormatVersion':1
}
]
}
The MAC Signature can be used to pass in MAC address and MAC type of a device. The MAC type refers to the source of the MAC address. Currently the only MACType available is MAC_IP_WLAN for Wi-Fi.
The following is an example of a MAC address signature for an Apple TV:
{
'MACAddress': 'd8-61-62-02-A8-77',
'MACType': 'MAC_IP_WLAN',
'FormatVersion': '1'
}
After forming your MAC Signature, you can add the signature to your inputJSON object. Here is an example inputJSON using MAC:
{
'Devices':[
{
'FormatVersion':1,
'DeviceID':1,
'Signatures':{
'MAC':[
{
'MACAddress': 'd8-61-62-02-A8-77',
'MACType': 'MAC_IP_WLAN',
'FormatVersion': '1'
}
]
}
}
]
}
It is possible to pass in additional options to refine the predicted results. These include:
PredictiveOptions - lists out options governing Predictive Discovery for this Device.
Devices - Within the device object, in addition to the signature that is passing in, the user has the choice of passing in the following information:
{
'PredictiveOptions':{
'OnlyUseAtrtributes':null,
'ExcludeAttributes':null,
'RequestAttributes':null,
'FormatVersion':1
},
'Devices':[
{
'DeviceID':1,
'Signatures':{
'SPD':[
'gwEZ1URpcmVjVFYASFIyMAAAAAAAAAAAAAAAAAE='
]
},
'DefiniteAttributes':{
'Attributes':{
'Region':'NA',
'Country':'US'
},
'FormatVersion':1
},
'PotentialAttributes':null,
'PredictiveOptions':null,
'FormatVersion':1
}
],
'FormatVersion':1
}
PredictiveDiscoveryResult Status Code | Status Message |
---|---|
0 | Success |
1 | Data Service Failure |
3 | No data available for product |
10 | Incorrect authentication parameters |
11 | Incorrect registration code |
12 | Project ID has not been configured |
13 | Authorization access denied |
14 | Authorization access denied (privilege level) |
15 | Authorization access denied (quota exceeded) |
20 | The language is not available |
21 | The region is not available |
22 | Plugin is not available |
23 | Configuration error |
30 | Invalid parameter values |
40 | Threshold too low |
PredictiveDiscoveryResult Status Code | Status Message |
---|---|
0 | Success |
1 | Data Service Failure |
3 | No data available for product |
10 | Incorrect authentication parameters |
11 | Incorrect registration code |
12 | Project ID has not been configured |
13 | Authorization aces denied |
14 | Authorization access denied (privilege level) |
15 | Authorization access denied (quota exceeded) |
20 | The language is not available |
21 | The region is not available |
22 | Plugin is not available |
23 | Configuration error |
30 | Invalid parameter values |
40 | Threshold too low |