Difference between revisions of "Websockets Documentation"
m |
m |
||
Line 3: | Line 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. | ||
− | <b>Note: WebSocket API new Rules and Commands are updated according to the new firmware R085 and please [https://wiki.securifi.com/index.php/ | + | <b>Note: WebSocket API new Rules and Commands are updated according to the new firmware R085 and please [https://wiki.securifi.com/index.php/Changelog '''click here'''] to access the old Rules and Commands.</b> |
== Authentication == | == Authentication == |
Revision as of 13:12, 12 May 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 and Commands are updated according to the new firmware R085 and please click here to access the old Rules and Commands.
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 AlmondModeUpdated
- 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
{ "mii":"<random key>", "cmd":"devicelist" }
Response
{ "mii":"<random key>","commandtype":"devicelist","data" : {"1":{"devicename":"ContactSwitch #1","friendlydevicetype":"ContactSwitch","devicetype":"12","deviceid":"1","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"}}},"2":{"devicename":"BinarySwitch #2","friendlydevicetype":"BinarySwitch","devicetype":"1","deviceid":"2","location":"Default","devicevalues":{"1":{"index":"1","name":"SWITCH BINARY","value":"true"}}}} }
Setdeviceindex
Command to set the device index value without timeout.
Request
{ "mii":"<random key>", "cmd":"setdeviceindex", "devid":"<device id>", "index":"<deviceindex>", "value":"<indexvalue>" }
Response
Success
{ "mii":"<random key>","commandtype":"setdeviceindex","success":"true","data":{"devid":"<deviceid>","index":"<deviceindex>","value":"<indexvalue>"} }
Failure
{ "mii":"<random key>","commandtype":"setdeviceindex",:"success":"false"} }
Example
In the following example, the value of index 1 is set to ‘true’ for device id 2.
{ "mii":"jdnbc", "cmd":"setdeviceindex", "devid":"2", "index":"1", "value":"true", }
Response
{ "mii":"jdnbc","commandtype":"setdeviceindex","success":"true","data":{"devid":"2","index":"1","value":"true"} }
Getdeviceindex
Command to get the value of a device index. Request
{ "mii":"<random key>", "cmd":"getdeviceindex", "devid":"<deviceid>", "index":"<deviceindex>" }
Response
Success
{ "mii":"<random key>","commandtype":"getdeviceindex","success":"true","data":{"devid":"<deviceid>","index":"<deviceindex>","value":"<indexvalue>"} }
Failure
{ "mii":"<random key>","commandtype":"getdeviceindex","success":"false" }
Example In the following example, value of index 1 is retrieved for device id 2.
{ "mii":"jdnbc", "cmd":"getdeviceindex", "devid":"2", "index":"1" }
Response
{ "mii":"jdnbc","commandtype":"getdeviceindex","success":"true","data":{"devid":"2","index":"1","value":"false"} }
Editdevicename
Command to edit name and location of a device.
Request
{ "mii":"<random key>", "cmd":"editdevicename", "devid":"6", "name":"newswitchsss", "location":"default" }
Response
Success
{ "mii":"<random key>","commandtype":"editdevicename","success":"true" }
Failure
{ "mii":"<random key>","commandtype":"editdevicename","success":"false" }
Updatealmondmode
Command to change the almond mode.
Request
{ "mii":"<random key>", "cmd":"updatealmondmode", "mode":"<mode i.e. 2/3>", "emailid":"<email id>" }
Response
Success
{ "mii":"<random key>","commandtype":"updatealmondmode","success":"true","data":{"mode":"2","emailid":"swetha.reddy@securifi.com"} }
Failure
{ "mii":"<random key>","commandtype":"updatealmondmode","success":"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":"123"}
Response:
{"CommandType":"RuleList" ,"Rules":[{"ID":"1","Name":"12346","Valid":"1","Triggers":[{"Type":"EventTrigger","EventType":"AlmondModeUpdated","ID":"1","Grouping":"AND","Condition":"eq","Validation":"true","Value":"home"}, { "Type":"DeviceTrigger","ID":"1","Index":"1","Grouping":"AND","Validation":"true","Condition":"eq","Value":"false"}],"Results":[{"Type":"EventResult","EventType":"AlmondModeUpdated","ID":"1","PreDelay":"0", "Validation":"true","Value":"away"},{"Type":"DeviceResult","ID":"2","Index":"1","PreDelay":"0","Validation":"true","Value":"false"}]}]}
Addrule
Command to create a new rule.
Request
{ "MobileInternalIndex": "111", "CommandType": "AddRule", "Name": "MYRULE", "Valid":"true", "Triggers": [ { "Type": "DeviceTrigger", "ID": "1", "Index": "1", "Value": "true", "Grouping": "AND", "Condition": "eq", "Validation": "true" }, { "Type": "EventTrigger", "ID": "1", "EventType": "AlmondModeUpdated", "value": "home", "Grouping": "AND", "Condition": "eq" } ], "Results": [ { "Type": "DeviceResult", "ID": "2", "Index": "1", "Value": "true", "PreDelay": "10" }, { "Type": "EventResult", "ID": "1", "EventType": "AlmondModeUpdated", "Value": "away", "PreDelay": "0" } ] }
Response
{ "CommandType":"AddRule", "Success":"true", "MobileInternalIndex":"111", "ReasonCode":"1" }
Updaterule
Command to update an existing rule.
Request
{ "MobileInternalIndex": "111", "CommandType": "UpdateRule", "Name": "UPATERULE", "Valid":"true", "ID": "1", "Triggers": [ { "Type": "DeviceTrigger", "ID": "1", "Index": "1", "Value": "true", "Grouping": "AND", "Condition": "eq" }, { "Type": "EventTrigger", "ID": "1", "EventType": "AlmondModeUpdated", "Value": "home", "Grouping": "AND", "Condition": "eq" } ], "Results": [ { "Type": "DeviceResult", "ID": "2", "Index": "1", "Value": "true", "PreDelay": "10" }, { "Type": "EventResult", "ID": "1", "EventType": "AlmondModeUpdated", "Value": "away", "PreDelay": "10" } ] }
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
{ "MobileInternalIndex":"<random key>", "CommandType":"UpdateClient", "Clients":{ "ID":"2", "Name":"device1", "Connection":"wired", "MAC":"00:17:88:0a:04:41", "Type":"tv", "LastKnownIP":"10.2.2.11", "Active":"false", "UseAsPresence":"false", "Wait":"6"
} }
Response
Success
{ "CommandType":"UpdateClient", "MobileInternalIndex":"324", "Success":"true", "ReasonCode":"0" }
Faliure
{ "CommandType":"UpdateClient", "MobileInternalIndex":"324", "Success":"false", "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
{ "MobileInternalIndex":"<random key>", "CommandType":"DynamicSceneList" }
Response
Note: Active :- Indicates the state of Scene
{ "MobileInternalIndex":"<random key>", "CommandType":"DynamicSceneList", "Scenes":[ { "ID":"1", "Name":"Scene1", "LastActiveEpoch":"1433740885", "Active":"false", "SceneEntryList":[ { "DeviceID":"2", "Index":"2", "Value":"true", "Valid":"false" }, { "DeviceID":"1", "Index":"2", "Value":"true", "Valid":"false" } ] }, { "ID":"2", "Name":"Scene2", "LastActiveEpoch":"0", "Active":"false", "SceneEntryList":[ { "DeviceID":"6", "Index":"1", "Value":"true", "Valid":"false" }, { "DeviceID":"7", "Index":"1", "Value":"true", "Valid":"false" } ] } ] }
AddScene
Command to add a new Scene.
Request
{ "CommandType":"AddScene", "MobileInternalIndex":"324", "Scenes":{ "Name":"My_created_scene", "SceneEntryList":[ { "DeviceID":"1", "Index":"1", "Value":"false" }, { "DeviceID":"2", "Index":"2", "Value":"false" } ] } }
Response
{"CommandType":"AddScene","MobileInternalIndex":"324","Success":"true","Reason":"0"}
UpdateScene
Command to update an existing Scene
Request
{ "CommandType":"UpdateScene", "MobileInternalIndex":"324", "Scenes":{ "ID":"15", "Name":"My_created_scene", "SceneEntryList":[ { "DeviceID":"1", "Index":"1", "Value":"false" }, { "DeviceID":"2", "Index":"2", "Value":"false" } ] } }
Response
{"CommandType":"UpdateScene","MobileInternalIndex":"324","Success":"true","Reason":"0"}
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":"DeviceUpdated","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":"DeviceUpdated","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"}}}}}
DynamicRuleAdded
{ "CommandType": "DynamicRuleAdded", "Rules": { "ID": "1", "Name": "NewRule", "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" }] } }
DynamicRuleUpdated
{ "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
{ "CommandType":"DynamicRuleRemoved","Rules":{"ID":"1"} }
DynamicAllRulesRemoved
{ "CommandType":"DynamicAllRulesRemoved" }
AlmondModeUpdated
{"commandtype":"AlmondModeUpdated","data":{"<almond mode >":{"emailid":"<email id>"}}}
Example
{"commandtype":"AlmondModeUpdated","data":{"2":{"emailid":"swetha.reddy@securifi.com"}}}
DynamicClientAdded
When a new client is added this update is received.
{ "CommandType":"DynamicClientAdded", "Clients":{ "ID":"1", "Name":"my phone", "Connection":"wired", "MAC":"c4:43:6d:c9:ef:05", "Type":"tv", "LastKnownIP":"10.10.10.55", "Active":"false", "UseAsPresence":"true", "Wait":"6" } }
DynamicClientJoined
When a client joined network this update is received.
{ "CommandType":"DynamicClientJoined", "Clients":{ "ID":"1", "Name":"my phone", "Connection":"wired", "MAC":"c4:43:6d:c9:ef:05", "Type":"tv", "LastKnownIP":"10.10.10.55", "Active":"false", "UseAsPresence":"true", "Wait":"6" } }
DynamicClientLeft
When a client leaves the network, following update is received.
{ "CommandType":"DynamicClientLeft", "Clients":{ "ID":"1", "Name":"my phone", "Connection":"wired", "MAC":"c4:43:6d:c9:ef:05", "Type":"tv", "LastKnownIP":"10.10.10.55", "Active":"false", "UseAsPresence":"true", "Wait":"6" } }
DynamicClientUpdated
When a name change or any changes done to a client this update is received.
{ "CommandType":"DynamicClientUpdated", "Clients":{ "ID":"1", "Name":"my phone", "Connection":"wired", "MAC":"c4:43:6d:c9:ef:05", "Type":"tv", "LastKnownIP":"10.10.10.55", "Active":"false", "UseAsPresence":"true", "Wait":"6" } }
DynamicClientRemoved
When a client is removed this update is received
{"CommandType":"DynamicClientRemoved","ID":"1","MAC":"c4:43:6d:c9:ef:05"}
DynamicAllClientsRemoved
When all the clients are removed this update is received
{"CommandType":"DynamicAllClientsRemoved"}
DynamicSceneAdded
when a new scene is added this update is received. { "CommandType":"DynamicSceneAdded", "Scenes":{ "ID":"1", "Name":"My_created_scene", "LastActiveEpoch":"8295685751190847488", "Active":"false", "SceneEntryList":[ {"DeviceID":"1","Index":"1","Value":"false","Valid":"true"}, {"DeviceID":"1","Index":"2","Value":"false","Valid":"false"} ] } }
DynamicSceneUpdated
when any changes are made to existing scene this update is received.
{ "CommandType":"DynamicSceneUpdated", "Scenes":{ "ID":"1", "Name":"My_created_scene", "LastActiveEpoch":"8295685751190847488", "Active":"false", "SceneEntryList":[ {"DeviceID":"2","Index":"1","Value":"false","Valid":"true"}, {"DeviceID":"4","Index":"1","Value":"78","Valid":"false"} ] } }
DynamicSceneActivated
when any scene is activated this update is received.
{ "CommandType":"DynamicSceneActivated", "Scenes":{ "ID":"1", "LastActiveEpoch":"8295685751190847488", "Active":"true", } }
DynamicSceneRemoved
when any scene is removed this update is received.
{ "CommandType":"DynamicSceneRemoved", "Scenes":{ "ID":"1" } }
DynamicAllScenesRemoved
when all scenes are removed this update is received.
{"CommandType":"DynamicAllScenesRemoved"}