Websockets Documentation
From SecuriWiki
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"
}
