Difference between revisions of "Websockets Documentation"
Line 1: | Line 1: | ||
[[Category:Almond+ 2014]] | [[Category:Almond+ 2014]] | ||
[[Category:Almond 2015]] | [[Category:Almond 2015]] | ||
+ | [[Category:Almond 3]] | ||
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 [https://wiki.securifi.com/index.php/Devicelist_Documentation '''smart devices'''] that are paired with Almond and build smart applications around it. | 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 [https://wiki.securifi.com/index.php/Devicelist_Documentation '''smart devices'''] that are paired with Almond and build smart applications around it. | ||
− | |||
− | |||
== Authentication == | == Authentication == |
Latest revision as of 14:52, 1 April 2019
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.
Contents
- 1 Authentication
- 2 Device Commands
- 3 Rules Commands
- 4 ClientList
- 5 ScenesCommands
- 6 Notification and Event Updates
- 6.1 DynamicIndexUpdated
- 6.2 DynamicDeviceAdded
- 6.3 DynamicDeviceRemoved
- 6.4 DynamicAllDevicesRemoved
- 6.5 DynamicDeviceUpdated
- 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", "Devices":{ "1":{ "Data":{ "ID":"1", "Name":"ContactSwitch #1", "Type":"12", "FriendlyDeviceType":"ContactSwitch", "Location":"Default", "LastActiveEpoch":"1462172879", "Manufacturer":"Sercomm Corp.", "Version":"16", "Model":"Unknown", "DeviceState":"1" }, "DeviceValues":{ "1":{ "Name":"STATE", "Value":"true", "Type":"4" }, "2":{ "Name":"LOW BATTERY", "Value":"0", "Type":"12" }, "3":{ "Name":"TAMPER", "Value":"true", "Type":"9" } } }, "2":{ "Data":{ "ID":"2", "Name":"BinarySwitch #2", "Type":"1", "FriendlyDeviceType":"BinarySwitch", "Location":"Default", "LastActiveEpoch":"1462175634", "Manufacturer":"Sercomm Corp.", "Version":"16", "Model":"SZ-BSW01", "DeviceState":"1" }, "DeviceValues":{ "1":{ "Name":"SWITCH BINARY", "Value":"true", "Type":"1" } } } } }
Updatedeviceindex
Request { "MobileInternalIndex":"<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", "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
{ "CommandType": "ClientList", "MobileInternalIndex":"<random key same as request>", "Success":"true", "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" }, "2": { "ID":"2", "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", "Schedule": "0,0,0,0,0,0,0", "Manufacturer": "LG", "RSSI": "0", "ForceInActive": "0" } } }
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", "Reason":"0" }
Failure
{ "CommandType":"RemoveClient", "MobileInternalIndex":"324", "Success":"false", "Reason":"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":"DynamicSceneList", "MobileInternalIndex":"5432857" }
Response
Note: Active :- Indicates the state of Scene
{ "CommandType": "DynamicSceneList", "MobileInternalIndex":"<same as in request>", "Scenes": { "1": { "ID":"1", "Active": "true", "Name": "Scene1022", "LastActiveEpoch": "251176214925585", "VoiceCompatible":"true", "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
{ "CommandType":"AddScene", "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
DynamicIndexUpdated
If any device index is changed, the following update will be received.
{ "CommandType":"DynamicIndexUpdated", "Devices":{ "<device id>":{ "DeviceValues":{ "<index id>":{ "Name":"<index name>", "Value":"<index value>" } } } } }
DynamicDeviceAdded
Whenever a device is added, the follow update would be received. { "CommandType":"DynamicDeviceAdded", "Devices":{ "<device id>":{ "Data":{ "Name":"<device name>", "Type":"<device type id >", "FriendlyDeviceType":"<friendly device type>", "Location":"<location>", "LastActiveEpoch":"<time stamp>", "Manufacturer":"<manufacturer name>", "Version":"<version number>", "Model":"<model>", "DeviceState":"<0/1/2>" }, "DeviceValues":{ "1":{ "Name":"<index name >", "Value":"<index val>", "Type":"<index type>" }, "2":{ "Name":"<index name>", "Value":"<index val>", "Type":"<index type>" }, "3":{ "Name":"<index name>", "Value":"<index val>", "Type":"<index type>" } } } } }
DynamicDeviceRemoved
Whenever a device is removed, the following update is received. { "CommandType":"DynamicDeviceRemoved", "Action":"remove", "Devices":{ "25":{ "Type":"<device type id >"} } }
DynamicAllDevicesRemoved
Whenever all the devices are removed, the follow update is received.
{ "CommandType":"DynamicAllDevicesRemoved" }
DynamicDeviceUpdated
If any device type or index are changed the following update will be received.
{ "CommandType":"DynamicDeviceUpdated", "Devices":{ "<device id>":{ "Data":{ "Name":"<device name>", "Type":"<device type id >", "FriendlyDeviceType":"<friendly device type>", "Location":"<location>", "LastActiveEpoch":"<time stamp>", "Manufacturer":"<manufacturer name>", "Version":"<version number>", "Model":"<model>", "DeviceState":"<0/1/2>" }, "DeviceValues":{ "1":{ "Name":"<index name >", "Value":"<index val>", "Type":"<index type>" }, "2":{ "Name":"<index name>", "Value":"<index val>", "Type":"<index type>" }, "3":{ "Name":"<index name>", "Value":"<index val>", "Type":"<index type>" } } } } }
DynamicRuleAdded
When a new rule is added the following update is received.
{ "CommandType": "DynamicRuleAdded", "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": { "12": { "ID":"12", "Name": "mynewrule", "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" }], "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>" }] } } }
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"}
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": "DynamicClientAdded", "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" } } }
DynamicClientJoined
When a client joined network the following update is received. { "CommandType": "DynamicClientJoined", "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": "true", "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", "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", "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": "DynamicClientRemoved", "Action": "remove", "Clients": { "1":{ "MAC": "1c:75:08:32:2a:6d" } } }
DynamicAllClientsRemoved
When all the clients are removed this update is received { "CommandType":"DynamicAllClientsRemoved" }
DynamicSceneAdded
When a new scene is added the following update is received. { "CommandType": "DynamicSceneAdded", "Scenes": { "1": { "ID":"1", "Active": "true", "Name": "Scene1022", "LastActiveEpoch": "251176214925585", "VoiceCompatible":"true", "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", "Scenes": { "1": { "ID":"1", "Active": "true", "Name": "Scene1022", "LastActiveEpoch": "251176214925585", "VoiceCompatible":"true", "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" }