Difference between revisions of "Websockets Documentation"
From SecuriWiki
(→DynamicAllClientsRemoved) |
(→Device Commands) |
||
| Line 94: | Line 94: | ||
"Success":"true/false" | "Success":"true/false" | ||
} | } | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
===Getdeviceindex=== | ===Getdeviceindex=== | ||
Command to get the value of a device index. | Command to get the value of a device index. | ||
Revision as of 12:10, 2 September 2016
Websocket is the protocol for establishing an interaction channel between an external application and Almond. It is also possible to receive event-based notifications. Websocket can be used to control smart devices that are paired with Almond and build smart applications around it.
Note: WebSocket API new Rules Commands are being updated according to the new firmware R089 and please click here to access the old Rules Commands which would work with the old firmware R085.
Contents
- 1 Authentication
- 2 Device Commands
- 3 Rules Commands
- 4 ClientList
- 5 ScenesCommands
- 6 Notification and Event Updates
- 6.1 SensorUpdate
- 6.2 DeviceAdded
- 6.3 DeviceRemoved
- 6.4 DeviceRemoveAll
- 6.5 DeviceUpdated
- 6.6 DynamicRuleAdded
- 6.7 DynamicRuleUpdated
- 6.8 DynamicRuleRemoved
- 6.9 DynamicAllRulesRemoved
- 6.10 DynamicAlmondModeUpdated
- 6.11 DynamicClientAdded
- 6.12 DynamicClientJoined
- 6.13 DynamicClientLeft
- 6.14 DynamicClientUpdated
- 6.15 DynamicClientRemoved
- 6.16 DynamicAllClientsRemoved
- 6.17 DynamicSceneAdded
- 6.18 DynamicSceneUpdated
- 6.19 DynamicSceneActivated
- 6.20 DynamicSceneRemoved
- 6.21 DynamicAllScenesRemoved
Authentication
In order to connect to the webserver - first specify a web-interface url, then the portid - 7681 followed by web-interface login password.
<webinterfaceUrl>:<portid>/<Login>/<password>
Example ws://10.10.10.254:7681/root/frank
Device Commands
Note: mii is a random key that is generated by the client and should be used for matching the received response to the corresponding request.
Maximum string length of mii is 32 characters. A unique mii should be used for each request
Devicelist
Command to get the list of sensors and other smart devices associated with the almond.
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"DeviceList"
}
Response
{
"MobileInternalIndex":"<random key>",
"CommandType":"DeviceList",
"Action":"addAll",
"Devices":{
"1":{
"Data":{
"ID":"1",
"Name":"ContactSwitch #1",
"AssociationTimestamp":"1462172879",
"Type":"12",
"Location":"Default",
"LastActiveEpoch":"1462172879",
"Manufacturer":"Sercomm Co",
"Version":"16",
"Model":"Unknown"
},
"DeviceValues":{
"1":{
"Name":"STATE",
"Value":"true"
},
"2":{
"Name":"LOW BATTERY",
"Value":"0"
},
"3":{
"Name":"TAMPER",
"Value":"true"
}
}
},
"2":{
"Data":{
"ID":"2",
"Name":"BinarySwitch #2",
"FriendlyDeviceType":"BinarySwitch",
"Type":"1",
"ID":"2",
"Location":"Default"
},
"DeviceValues":{
"1":{
"Name":"SWITCH BINARY",
"Value":"true"
}
}
}
}
}
Updatedeviceindex
Request
{
"MobilInternalIndex":"<random key>",
"CommandType":"UpdateDeviceIndex",
"ID":"<device id>",
"Index":"<deviceindex>",
"Value":"<indexvalue>"
}
Response
{
"MobileInternalIndex":"<random key>",
"CommandType":"UpdateDeviceIndex",
"Success":"true/false"
}
Getdeviceindex
Command to get the value of a device index.
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"GetDeviceIndex",
"ID":"<deviceid>",
"Index":"<deviceindex>"
}
Response
{
"MobileInternalIndex":"<random key>",
"CommandType":"GetDeviceIndex",
"Success":"true/false",
"Value":"<indexvalue>"
}
UpdateDeviceName
Command to edit name and location of a device.
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"UpdateDeviceName",
"ID":"6",
"Name":"newswitchsss",
"Location":"default"
}
Response
{
"MobileInternalIndex":"<random key>",
"CommandType":"UpdateDeviceName",
"Success":"true/false"
}
Updatealmondmode
Command to change the almond mode.
Request
{ "MobileInternalIndex":"<random key>", "CommandType":"UpdateAlmondMode", "Mode":"<mode i.e. 2/3>", "EmailId":"<email id>" } Response
{ "MobileInternalIndex":"<random key>", "CommandType":"UpdateAlmondMode", "Success":"true/false" }
Rules Commands
Note: mii is a random key that is generated by the client and should be used for matching the received response to the corresponding request. Maximum string length of mii is 32 characters. A unique mii should be used for each request.
Ruleslist
Command to get the list of existing rules.
Request:
{
"CommandType":"RuleList",
"MobileInternalIndex":"111"
}
Response:
{
"CommandType": "RuleList",
"Action": "addAll",
"Rules": {
"12": {
"Name": "mynewrule",
"Valid": "true",
"ID":"12",
"Triggers": [{
"Type": "<type of trigger>",
"ID": "<device id>",
"Index": "<device index>",
"Value": "<index value>",
"Grouping": "< AND/OR>",
"Condition": "<condition type ie.eq/le/ge/lt/gt>",
"Duration": "
Addrule
Command to create a new rule.
Request
{
"MobileInternalIndex": "111",
"CommandType": "AddRule",
"Name": "rule",
"Valid":"true",
"Triggers": [
{
"Type": "<type of trigger>",
"ID": "<device id>",
"Index": "<device index>",
"Value": "<index value>",
"Grouping": "< AND/OR>",
"Condition": "<condition type ie.eq/le/ge/lt/gt>",
"Duration": "<time in sec>",
"Valid": "true"
},
{
"Type": "<type of trigger>",
"ID": "<event id>",
"EventType": "<event type>",
"value": "<event value>",
"Grouping": "<AND/OR>",
"Condition": "<condition type ie.eq/le/ge/lt/gt>",
"Duration": "<time in sec>",
"Valid": "true"
}
],
"Results": [
{
"Type": "<type of result>",
"ID": "<device id>",
"Index": "<device index>",
"Value": "<index value>",
"PreDelay": "<time in sec>",
"Valid": "true"
},
{
"Type": "<type of result>",
"ID": "<event id>",
"EventType": "<event type>",
"Value": "<event value>",
"PreDelay": "<time in sec>",
"Valid": "true"
}
]
}
Response
{
"CommandType":"AddRule",
"Success":"true",
"MobileInternalIndex":"111",
"ReasonCode":"1"
}
Updaterule
Command to update an existing rule.
Request
{
"MobileInternalIndex": "111",
"CommandType": "UpdateRule",
"Name": "ruleNAME",
"Valid":"true",
"ID": "2",
"Triggers": [
{
"Type": "<type of trigger>",
"ID": "<device id>",
"Index": "<device index>",
"Value": "<index value>",
"Grouping": "< AND/OR>",
"Condition": "<condition type ie.eq/le/ge/lt/gt>",
"Duration": "<time in sec>",
"Valid":"true"
},
{
"Type": "<type of trigger>",
"ID": "<event id>",
"EventType": "<event type>",
"Value": "<event value>",
"Grouping": "<AND/OR>",
"Condition": "<condition type ie.eq/le/ge/lt/gt>",
"Duration": "<time in sec>",
"Valid":"true"
}
],
"Results": [
{
"Type": "<type of result>",
"ID": "<device id>",
"Index": "<device index>",
"Value": "<index value>",
"PreDelay": "<time in sec>"
},
{
"Type": "<type of result>",
"ID": "<event id>",
"EventType": "<event type>",
"Value": "<event value>",
"PreDelay": "<time in sec>"
}
]
}
Response
{
"CommandType":"UpdateRule",
"Success":"true",
"MobileInternalIndex":"111",
"ReasonCode":"1"
}
Removerule
Command to remove an existing rule.
Request
{
"CommandType": "RemoveRule",
"Rules": {
"ID": "1"
},
"MobileInternalIndex": "111"
}
Response
{
"CommandType":"RemoveRule",
"Success":"true",
"MobileInternalIndex":"111",
"ReasonCode":"0"
}
Removeallrules
Command to remove all rules.
Request
{
"CommandType":"RemoveAllRules",
"MobileInternalIndex":"111"
}
Response
{
"CommandType":"RemoveAllRules",
"Success":"true",
"MobileInternalIndex":"111",
"ReasonCode":"0"
}
Validaterule
Command to validate an existing rule.
Request
{
"CommandType":"ValidateRule",
"ID":"1",
"Value":"true"
"MobileInternalIndex":"111"
}
Response
{
"CommandType":"ValidateRule",
"MobileInternalIndex":"111",
"ReasonCode":"0",
"Success":"false",
"Data":{
"Value":"true",
"ID":"1"
}
}
ClientList
Command to get clientlist.
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"ClientList"
}
Response
{
"MobileInternalIndex":"<random key>",
"CommandType":"ClientList",
"Success":"true",
"Clients":[
{
"ID":"1",
"Name":"iphone_4s",
"Connection":"wireless",
"MAC":"other",
"Type":"other",
"LastKnownIP":"10.2.2.11",
"Active":"false",
"UseAsPresence":"true",
"LastActiveEpoch":"1433920922",
"Wait":"6"
},
{
"ID":"2",
"Name":"buildserver.lan",
"Connection":"wired",
"MAC":"d8:50:e6:54:1b:9c",
"Type":"other",
"LastKnownIP":"10.10.10.1",
"Active":"true",
"UseAsPresence":"false",
"LastActiveEpoch":"1433920922",
"Wait":"6"
}
]
}
Note - Success Tag in response:
If the Almond is in AP mode or Range Extender mode then Success tag will be set to ‘false’.
UpdateClient
Command to Update the data of a client.
ID - Clientid
Name - name of the client
Connection - wired/wireless
Type - pc
laptop
tablet
smartphone
ipod
ipad
iphone
mac
printer
router_switch
hub
tv
chromecast
appleTV
android_stick
camera
nest
other
Use as Presence - true/false
Request
{ "CommandType":"UpdateClient", "Clients":{ "ID": "1", "Name": "device1", "Connection": "wired", "MAC": "1c:75:08:32:2a:6d", "Type": "other", "LastKnownIP": "10.2.2.11", "Active": "false", "UseAsPresence": "false", "Wait":"6", "Block":"0/1/2", "Category:"Kids/Others" }, "MobileInternalIndex":"324" } Response
{ "Success":"true/false", "MobileInternalIndex":"324", "ReasonCode":"0" }
Remove client
command to remove a client.
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"RemoveClient",
"Clients":{
"ID":"1",
"MAC":"1c:75:08:32:2a:6d"
}
}
Response
Success
{
"CommandType":"RemoveClient",
"MobileInternalIndex":"324",
"Success":"true",
"ReasonCode":"0"
}
Failure
{
"CommandType":"RemoveClient",
"MobileInternalIndex":"324",
"Success":"false",
"ReasonCode":"0"
}
Removeallclients
Command to remove all clients
Request
{
"MobileInternalIndex":"<random key>",
"CommandType":"RemoveAllClients",
}
Response
Success
{
"CommandType":"RemoveAllClients",
"MobileInternalIndex":"324",
"Success":"true",
"ReasonCode":"0"
}
Failure
{
"CommandType":"RemoveAllClients",
"MobileInternalIndex":"324",
"Success":"false",
"ReasonCode":"0"
}
ScenesCommands
Note:mii(MobileInternalIndex) is a random key that is generated by the client and should be used for matching the received response to the corresponding request. Maximum string length of mii is 32 characters.
A unique mii should be used for each request
SceneList
Command to retrieve the list of existing Scenes.
Request
{
"CommandType":"SceneList",
"MobileInternalIndex":"5432857"
}
Response
Note: Active :- Indicates the state of Scene
{
"CommandType": "SceneList",
"Action": "addAll"
"Scenes": {
"1": {
"ID":"1",
"Active": "true",
"Name": "Scene1022",
"LastActiveEpoch": "251176214925585",
"SceneEntryList": [{
"ID": "2",
"Index": "1",
"Value": "false",
"Valid": "true"
}, {
"ID": "4",
"Index": "1",
"Value": "78",
"Valid": "true"
}]
}
}
}
AddScene
Command to add a new Scene.
Request
{
"CommandType": "AddScene",
"MobileInternalIndex": "324",
"Scenes":{
"Name": "My_created_scene",
"SceneEntryList": [
{
"ID": "1",
"Index": "1",
"Value": "false"
},
{
"ID": "2",
"Index": "2",
"Value": "false"
}
]}
}
Response
{"MobileInternalIndex":"324",
"ReasonCode":"0",
"Success":"true"
}
UpdateScene
Command to update an existing Scene
Request
{
"MobileInternalIndex": 1667509461,
"Scenes": {
"Name": "DADad222d",
"ID": 1,
"SceneEntryList": [{
"ID": 0,
"Value": "home",
"Index": 1
}, {
"ID": 2,
"Value": "false",
"Index": 1
}, {
"ID": 2,
"Value": "true",
"Index": 2
}],
"VoiceCompatible": false
},"CommandType": "UpdateScene"
}
Response
{"MobileInternalIndex":"324",
"ReasonCode":"0",
"Success":"true"
}
ActivateScene
Command to activate a Scene
Request
{
"CommandType":"ActivateScene",
"MobileInternalIndex":"324",
"Scenes":{
"ID":"11"
}
}
Response
{"CommandType":"ActivateScene","MobileInternalIndex":"324","Success":"true","Reason":"0"}
RemoveScene
Command to remove a Scene
Request
{
"CommandType":"RemoveScene",
"MobileInternalIndex":"324",
"Scenes":{
"ID":"11"
}
}
Response
{"CommandType":"RemoveScene","MobileInternalIndex":"324","Success":"true","Reason":"0"}
RemoveAllScenes
Command to remove all Scenes
Request
{
"CommandType":"RemoveAllScenes",
"MobileInternalIndex":"324"
}
Response
{"CommandType":"RemoveAllScenes","MobileInternalIndex":"324","Success":"true","Reason":"0"}
Notification and Event Updates
SensorUpdate
When any index value is changed the following update will be received.
{"commandtype":"SensorUpdate","data":{"<device id>":{"<index id>":{"index":"<index id>","name":"<index name>","value":"<index value>"}}}}
Example
{"commandtype":"SensorUpdate","data":{"25":{"3":{"index":"3","name":"TAMPER","value":"false"}}}}
DeviceAdded
When a new device is added the following update will be received.
{"commandtype":"DeviceAdded","data":{"<device id>":{"devicename":"<device name>","friendlydevicetype":"<friendly device type name >","devicetype":"<device type id >","deviceid":"<device id >","location":"
<location>","devicevalues":{"1":{"index":"<index num>","name":"<index name >","value":"<index val>"},"2":{"index":"<index num>","name":"<index name>","value":"<index val>"},"3":{"index":"<index num>","name":"<index
name>","value":"<index val>"}}}}}
Example:
{"commandtype":"DeviceAdded","data":{"27":{"devicename":"ContactSwitch #27","friendlydevicetype":"ContactSwitch","devicetype":"12","deviceid":"27","location":"Default","devicevalues":{"1":
{"index":"1","name":"STATE","value":"true"},"2":{"index":"2","name":"LOW BATTERY","value":"0"},"3":{"index":"3","name":"TAMPER","value":"true"}}}}}
DeviceRemoved
When a device is removed the following update will be received
{"commandtype":"DeviceRemoved","data":{"<device id>":{"devtype":"<device type>"}}}
Example
{"commandtype":"DeviceRemoved","data":{"25":{"devtype":"12"}}}
DeviceRemoveAll
When all the devices are removed the following update will be received.
{"commandtype":"DeviceRemoveAll"}
DeviceUpdated
If any device type or index are changed the following update will be received.
{
"CommandType":"DynamicDeviceUpdated",
"Action":"update",
"Devices":{
"<device id>":{
"Data":{
"Name":"<device name>",
"Type":"<device type id >",
"Location":"<location>",
"LastActiveEpoch":"<time stamp>",
"Manufacturer":"<manufacturer name>",
"Version":"<version number>",
"Model":"<model>"
}
}
}
}
DynamicRuleAdded
When a new rule is added the following update is received.
{
""CommandType"": ""DynamicRuleAdded"",
""Action"": ""add"",
""Rules"": {
""12"": {
""Name"": ""mynewrule"",
""Valid"": ""true"",
""ID"":""12"",
""Triggers"": [{
""Type"": ""<type of trigger>"",
""ID"": ""<device id>"",
""Index"": ""<device index>"",
""Value"": ""<index value>"",
""Grouping"": ""< AND/OR>"",
""Condition"": ""<condition typet>"",
""Duration"": ""<time in sec>"",
""Valid"": ""true""
}],
""Results"": [{
""Type"": ""<type of result>"",
""ID"": ""<device id>"",
""Index"": ""<device index>"",
""Value"": ""<index value>"",
""PreDelay"": ""<time in sec>"",
""Valid"": ""true""
}, {
""Type"": ""<type of result>"",
""ID"": ""<event id>"",
""EventType"": ""<event type>"",
""Value"": ""<event value>"",
""PreDelay"": ""<time in sec>"",
""Valid"": ""true""
}]
}
}
}
DynamicRuleUpdated
When an existing rule is modified the following update is received.
{
"CommandType": "DynamicRuleUpdated",
"Rules": {
"ID": "1",
"Name": "123",
"Valid": "1",
"Triggers": [{
"Type": "EventTrigger",
"EventType": "AlmondModeUpdated",
"ID": "1",
"Grouping": "AND",
"Condition": "eq",
"Validation": "true",
"Value": "home"
}, {
"Type": "DeviceTrigger",
"ID": "2",
"Index": "1",
"Grouping": "AND",
"Validation": "true",
"Condition": "eq",
"Value": "false"
}],
"Results": [{
"Type": "DeviceResult",
"ID": "2",
"Index": "1",
"PreDelay": "0",
"Validation": "true",
"Value": "false"
}, {
"Type": "EventResult",
"EventType": "AlmondModeUpdated",
"ID": "1",
"PreDelay": "0",
"Validation": "true",
"Value": "away"
}]
}
}
DynamicRuleRemoved
When a rule is removed the following update is received.
{
""CommandType"": ""DynamicRuleRemoved"",
""Action"": ""remove"",
""Rules"": {
""1"": {}
}
}
DynamicAllRulesRemoved
When all rules are removed the following update is received.
{"CommandType":"DynamicAllRulesRemoved","Action":"removeAll"}
DynamicAlmondModeUpdated
{
"CommandType":"DymanicAlmondModeUpdated",
"Mode":"<mode i.e. 2/3>",
"EmailId":"<email id>"
}
DynamicClientAdded
When a new client is added the following update is received.
{
"CommandType":"DynamicDeviceAdded",
"Action":"add",
"Devices":{
"<device id>":{
"Data":{
"Name":"<device name>",
"Type":"<device type id >",
"Location":"<location>",
"LastActiveEpoch":"<time stamp>",
"Manufacturer":"<manufacturer name>",
"Version":"<version number>",
"Model":"<model>"
},
"DeviceValues":{
"1":{
"Name":"<index name >",
"value":"<index val>"
},
"2":{
"Name":"<index name>",
"Value":"<index val>"
},
"3":{
"Name":"<index name>",
"Value":"<index val>"
}
}
}
}
}
DynamicClientJoined
When a client joined network the following update is received.
{
"CommandType": "DynamicClientJoined",
"Action": "update",
"Clients": {
"1": {
"ID":"1",
"Name": "64:bc:0c:80:62:46",
"Connection": "wired",
"MAC": "64:bc:0c:80:62:46",
"Type": "other",
"LastKnownIP": "10.10.10.97",
"Active": "false",
"UseAsPresence": "true",
"Wait": "6",
"LastActiveEpoch": "1459845389",
"RX": "0",
"TX": "0",
"Block": "0/1/2",
"CanBlock":"true/false",
"Category":"Kids/Others",
"Schedule": "0,0,0,0,0,0,0",
"Manufacturer": "LG",
"RSSI": "0",
"ForceInActive": "0"
}
}
}
DynamicClientLeft
When a client leaves the network, following update is received.
{
"CommandType": "DynamicClientLeft",
"Action": "update",
"Clients": {
"1": {
"ID":"1",
"Name": "64:bc:0c:80:62:46",
"Connection": "wired",
"MAC": "64:bc:0c:80:62:46",
"Type": "other",
"LastKnownIP": "10.10.10.97",
"Active": "false",
"UseAsPresence": "true",
"Wait": "6",
"LastActiveEpoch": "1459845389",
"RX": "0",
"TX": "0",
"Block": "0/1/2",
"CanBlock":"true/false",
"Category":"Kids/Others",
"Schedule": "0,0,0,0,0,0,0",
"Manufacturer": "LG",
"RSSI": "0",
"ForceInActive": "0"
}
}
}
DynamicClientUpdated
When a name change or any changes done to a client the following update is received.
{
"CommandType": "DynamicClientUpdated",
"Action": "update",
"Clients": {
"1": {
"ID":"1",
"Name": "64:bc:0c:80:62:46",
"Connection": "wired",
"MAC": "64:bc:0c:80:62:46",
"Type": "other",
"LastKnownIP": "10.10.10.97",
"Active": "false",
"UseAsPresence": "true",
"Wait": "6",
"LastActiveEpoch": "1459845389",
"RX": "0",
"TX": "0",
"Block": "0/1/2",
"CanBlock":"true/false",
"Category":"Kids/Others",
"Schedule": "0,0,0,0,0,0,0",
"Manufacturer": "LG",
"RSSI": "0",
"ForceInActive": "0"
}
}
}
DynamicClientRemoved
When a client is removed this update is received
{
"CommandType":"DynamicDeviceRemoved",
"Action":"remove",
"Devices":{
"25":{
"Type":"<device type id >"}
}
}
DynamicAllClientsRemoved
When all the clients are removed this update is received
"
{
""CommandType"":""DynamicAllDevicesRemoved"",
""Action"":""removeAll""
}"
DynamicSceneAdded
When a new scene is added the following update is received.
{
"CommandType": "DynamicSceneAdded",
"Action": "add",
"Scenes": {
"1": {
"ID":"1",
"Active": "true",
"Name": "Scene1022",
"LastActiveEpoch": "251176214925585",
"SceneEntryList": [{
"ID": "1",
"Index": "1",
"Value": "false",
"Valid": "true"
}, {
"ID": "4",
"Index": "1",
"Value": "78",
"Valid": "false"
}]
}
}
}
DynamicSceneUpdated
when any changes are made to an existing scene the following update is received.
{
"CommandType": "DynamicSceneUpdated",
"Action": "update",
"Scenes": {
"1": {
"ID":"1",
"Active": "true",
"Name": "Scene1022",
"LastActiveEpoch": "251176214925585",
"SceneEntryList": [{
"ID": "1",
"Index": "1",
"Value": "false",
"Valid": "true"
}, {
"ID": "4",
"Index": "1",
"Value": "78",
"Valid": "true"
}]
}
}
}
DynamicSceneActivated
When any scene is activated the following update is received.
{
"CommandType": "DynamicSceneActivated",
"Action": "update",
"Scenes": {
"1": {
"Active": "true",
"LastActiveEpoch": "251176214925585"
}
}
}
DynamicSceneRemoved
When any scene is removed the following update is received.
{
"CommandType": "DynamicSceneRemoved",
"Action": "remove",
"Scenes": {
"1": {}
}
}
DynamicAllScenesRemoved
When all scenes are removed the following update is received.
{
"CommandType": "DynamicAllScenesRemoved",
"Action": "removeAll"
}
