Difference between revisions of "Websockets Documentation"
(→Updatealmondmode) |
(Small change) |
||
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 Commands are updated according to the new firmware | + | <b>Note: WebSocket API new Rules Commands are being updated according to the new firmware R089 and please [https://wiki.securifi.com/index.php/Changelog '''click here'''] to access the old Rules Commands which would work with the old firmware R085.</b> |
== Authentication == | == Authentication == |
Revision as of 16:00, 30 August 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 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
{ "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" } } } } }
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
{ "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":"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
When a new rule is added the following update is received.
{ "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
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","Rules":{"ID":"1"} }
DynamicAllRulesRemoved
When all rules are removed the following update is received.
{ "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"}