Difference between revisions of "Websockets Documentation"

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 Commands are updated according to the new firmware R085 and please click here to access the old Rules Commands.

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"}