Websockets Documentation

From SecuriWiki
Revision as of 12:27, 12 May 2016 by Securifi (Talk | contribs)

Jump to: navigation, search

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.

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

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

RuleAdded

When a new rule is added the following update is received. 

{"commandtype":"RuleAdded","ruleid":"<ruleid>"}

Example 

{"commandtype":"RuleAdded","ruleid":"1"}

RuleRemoved

When a rule is removed the following update is received. 

{"commandtype":"RuleRemoved","ruleid":"<ruleid>"}

Example 

{"commandtype":"RuleRemoved","ruleid":"1"}

RuleUpdated

When a rule is updated the following update is received. 

{"commandtype":"RuleUpdated","ruleid":"<ruleid>"}

Example 

{"commandtype":"RuleUpdated","ruleid":"1"}

RuleRemoveAll

When all the rules are removed the following update is received. 

{"commandtype":"RuleRemoveAll"}

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"}
Retrieved from "https://wiki.securifi.com/index.php?title=Websockets_Documentation&oldid=1237"