Difference between revisions of "Sensaphone.net API/device"

From Sensaphone.net
Jump to: navigation, search
(→‎Sensaphone.net API)
m (→‎Specifications)
 
(6 intermediate revisions by one other user not shown)
Line 16: Line 16:
 
}}{{TableRowN| location              | address        | Object    | Address information for Device (See [[Sensaphone.net API/address|Sensaphone.net API/address]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| location              | address        | Object    | Address information for Device (See [[Sensaphone.net API/address|Sensaphone.net API/address]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| location              | coordinates        | Object    | GPS Coordinates information for Device (See [[Sensaphone.net API/coordinates]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| location              | coordinates        | Object    | GPS Coordinates information for Device (See [[Sensaphone.net API/coordinates]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
−
}}{{TableRowN| device              | firmware        | String    | Firmware version of Device  | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
 
}}{{TableRowN| device              | default_schedule        | Object    | Alarm Schedule data (See [[Sensaphone.net API/alarmschedule]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| device              | default_schedule        | Object    | Alarm Schedule data (See [[Sensaphone.net API/alarmschedule]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| device              | device_schedule        | Object    | Alarm Schedule data (See [[Sensaphone.net API/alarmschedule]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
 
}}{{TableRowN| device              | device_schedule        | Object    | Alarm Schedule data (See [[Sensaphone.net API/alarmschedule]])    | ''' ''' | ''' ''' | '''✓''' | '''✓'''
Line 34: Line 33:
 
}}{{TableRowN| device                | power_status        | String    | A device's power status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | power_status        | String    | A device's power status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | connection_status        | String    | A device's connection status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
 
}}{{TableRowN| device                | connection_status        | String    | A device's connection status    | ''' ''' | ''' ''' | '''✓''' | ''' '''  
−
}}{{TableRowN| device                | ack_offline_alarm        | String   | Acknowledge a device offline alarm    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
+
}}{{TableRowN| device                | ack_offline_alarm        | Boolean   | Acknowledge a device offline alarm    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
−
}}{{TableRowN| device                | acknowledge_all_alarms        | String   | Acknowledge all device/zone alarms    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
+
}}{{TableRowN| device                | acknowledge_all_alarms        | Boolean   | Acknowledge all device/zone alarms    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
 
}}{{TableRowN| device                | reset_to_defaults        | Boolean    |  Reset the device settings to factory defaults    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
 
}}{{TableRowN| device                | reset_to_defaults        | Boolean    |  Reset the device settings to factory defaults    | '''✓''' | ''' ''' | ''' ''' | ''' '''  
 
}}{{TableRowN| device                | clone        | Integer    |  Clone a device's data    | ''' ''' | ''' ''' | ''' ''' | '''✓'''  
 
}}{{TableRowN| device                | clone        | Integer    |  Clone a device's data    | ''' ''' | ''' ''' | ''' ''' | '''✓'''  
−
}}{{TableRowN| device          | feature             | Array of Objects | The feature linked to the device (See [[Sensaphone.net API/feature]])             | ''' ''' | ''' ''' | '''✓''' | '''✓'''
+
}}{{TableRowN| device              | firmware        | Object    | Firmware object of Device  | ''' ''' | ''' ''' | '''✓''' | ''' '''
 +
}}{{TableRowN| firmware              | firmware_id        | Integer    | The ID of the firmware  | ''' ''' | ''' ''' | '''✓''' | ''' '''
 +
}}{{TableRowN| firmware              | version        | String    | Firmware version of Device  | ''' ''' | ''' ''' | '''✓''' | ''' '''
 +
}}{{TableRowN| device          | firmware_auto_update              | Boolean | Will the Device automatically update to the latest firmware version            | ''' ''' | ''' ''' | '''✓''' |  '''✓'''
 +
}}{{TableRowN| device          | firmware_target              | Object | The firmware version the Device will install          | ''' ''' | '''✓''' | '''✓''' |  '''✓'''
 +
}}{{TableRowN| device          | firmware_available             | Array of Objects | A list of available firmware to install on the Device            | ''' ''' | ''' ''' | '''✓''' | ''' '''
 +
}}{{TableRowN| device         | firmware_changelog             | Array of Strings | A list of the changes verses the currently installed version            | ''' ''' | ''' ''' | '''✓''' | ''' '''
 +
}}{{TableRowN| device          | firmware_latest                | Object | Latest production firmware released for device | ''' ''' | ''' ''' | '''✓''' | ''' '''
 
}}{{TableEnd}}
 
}}{{TableEnd}}
  
Line 61: Line 67:
 
*Receive the alarm status of a Device  
 
*Receive the alarm status of a Device  
 
   '''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/status
 
   '''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/status
 +
 +
*Receive the changlog from a particular firmware version 
 +
  '''GET''' <nowiki>https://</nowiki>rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/firmware_changelog/{FIRMWARE_ID}
  
 
'''JSON Mode Request URI:'''
 
'''JSON Mode Request URI:'''
Line 72: Line 81:
 
}}{{TableRowN| &nbsp;          | request_type            | String          | "read"
 
}}{{TableRowN| &nbsp;          | request_type            | String          | "read"
 
}}{{TableRowN| &nbsp;          | device                  | Array of Objects | The device object.
 
}}{{TableRowN| &nbsp;          | device                  | Array of Objects | The device object.
 +
}}{{TableRowN| device          | firmware_changelog      | Object    | The changelog is only returned if specified explicitly in the request
 +
}}{{TableRowN| firmware_changelog          | firmware_id        | Integer    |  The ID of the firmware to get the changelog from
 
}}{{TableEnd}}
 
}}{{TableEnd}}
  
Line 107: Line 118:
 
}}{{TableRowN| device                | connection_status    | Optional      | String    | A device's connection status   
 
}}{{TableRowN| device                | connection_status    | Optional      | String    | A device's connection status   
 
}}{{TableRowN| device          | feature            | Optional      | Array of Objects | The feature linked to the account (See [[Sensaphone.net API/feature]])     
 
}}{{TableRowN| device          | feature            | Optional      | Array of Objects | The feature linked to the account (See [[Sensaphone.net API/feature]])     
 +
}}{{TableRowN| device              | firmware          | Optional        | Object    | Firmware version of Device
 +
}}{{TableRowN| device          | firmware_auto_update            | Optional          | Boolean | Will the Device automatically update to the latest firmware version
 +
}}{{TableRowN| device          | firmware_target            | Optional          | Object | The firmware version the Device will install   
 +
}}{{TableRowN| device          | firmware_available            | Optional          | Array of Objects | A list of available firmware to install on the Device     
 +
}}{{TableRowN| device          | firmware_changelog            | Optional          | Array of Strings | A list of the changes verses the currently installed version 
 
}}{{TableEnd}}
 
}}{{TableEnd}}
  
Line 186: Line 202:
 
}}{{TableRowN| device                    | standby_mode      | Optional        | String    | A device's standby mode.       
 
}}{{TableRowN| device                    | standby_mode      | Optional        | String    | A device's standby mode.       
 
}}{{TableRowN| device                    | clone      | Optional        | Integer    |  Destination device_id to clone this device's data to
 
}}{{TableRowN| device                    | clone      | Optional        | Integer    |  Destination device_id to clone this device's data to
−
}}{{TableRowN| device          | feature            | Optional      | Array of Objects | The feature linked to the device (See [[Sensaphone.net API/feature]])  
+
}}{{TableRowN| device          | feature            | Optional      | Array of Objects | The feature linked to the device (See [[Sensaphone.net API/feature]])  
 +
}}{{TableRowN| device          | firmware_auto_update            | Optional          | Boolean | Will the Device automatically update to the latest firmware version
 +
}}{{TableRowN| device          | firmware_target            | Optional          | Integer | The firmware version the Device will install   
 
}}{{TableEnd}}
 
}}{{TableEnd}}
  

Latest revision as of 19:29, 27 November 2023

Sensaphone.net API

Specifications

The device resource allows access to the devices that are bound to the account.

The device resource has the following properties:

Parent Property Property Type Description Create Delete Read Update
<parent> device Object The device object. ✓ ✓ ✓ n/a
device device_id Integer ID of the device. ✓
device id String Unique identifier located on the Device (Serial number, etc.) ✓
device name String Name of Device ✓ ✓
device description String Short description of Device ✓ ✓
device timezone String The timezone the Device is in ✓ ✓
device location Object Contains location information for the device. ✓ ✓
location address Object Address information for Device (See Sensaphone.net API/address) ✓ ✓
location coordinates Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates) ✓ ✓
device default_schedule Object Alarm Schedule data (See Sensaphone.net API/alarmschedule) ✓ ✓
device device_schedule Object Alarm Schedule data (See Sensaphone.net API/alarmschedule) ✓ ✓
device zone Array of Objects Device Zone data (See Sensaphone.net API/zone) ✓ ✓
device offline_timeout Integer The number of minutes a device must be offline before it goes into alarm. ✓ ✓
device product String The name of the product type ✓
device modbus_ports Array of Objects TBD
device zone_meta Array of Objects TBD ✓
zone_meta zone Zone Meta Type TBD ✓
zone_meta children Array of Zone Meta Type TBD ✓
device is_offline_unack Boolean Whether or not an unacknowledged offline alarm exists. ✓
device is_online Boolean Whether or not the device is currently online. ✓
device standby_time String The number of minutes a device will be in standby mode. ✓ ✓
device standby_mode String A device's standby mode. ✓ ✓
device standby_status String A device's standby status ✓
device battery_status String A device's battery status ✓
device power_status String A device's power status ✓
device connection_status String A device's connection status ✓
device ack_offline_alarm Boolean Acknowledge a device offline alarm ✓
device acknowledge_all_alarms Boolean Acknowledge all device/zone alarms ✓
device reset_to_defaults Boolean Reset the device settings to factory defaults ✓
device clone Integer Clone a device's data ✓
device firmware Object Firmware object of Device ✓
firmware firmware_id Integer The ID of the firmware ✓
firmware version String Firmware version of Device ✓
device firmware_auto_update Boolean Will the Device automatically update to the latest firmware version ✓ ✓
device firmware_target Object The firmware version the Device will install ✓ ✓ ✓
device firmware_available Array of Objects A list of available firmware to install on the Device ✓
device firmware_changelog Array of Strings A list of the changes verses the currently installed version ✓
device firmware_latest Object Latest production firmware released for device ✓


Zone Meta Type

PropertyType Description
zone_id Integer The Zone ID
is_enabled Integer Is the zone enabled
hide_if_disabled Boolean Hide the zone if disabled
add_name String The add name

GET

URI Mode Request URI's:

  • Receive all Device data for all Devices in a user's account
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device
  • Receive all Device data for a specific Device 
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}
  • Receive the alarm status of a Device 
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/status
  • Receive the changlog from a particular firmware version 
 GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/firmware_changelog/{FIRMWARE_ID}

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "read"
  device Array of Objects The device object.
device firmware_changelog Object The changelog is only returned if specified explicitly in the request
firmware_changelog firmware_id Integer The ID of the firmware to get the changelog from

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device id Optional Integer Unique identifier located on the Device (Serial number, etc.)
device name Optional String Name of Device
device description Optional String Short description of Device
device timezone Optional String The timezone the Device is in
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device product Optional String The name of the product type
device modbus_ports Optional Array of Objects TBD
device zone_meta Optional Array ofObjects TBD
zone_meta zone Optional Zone Meta Type TBD
zone_meta children Optional Array of Zone Meta Type TBD
device is_offline_unack Optional Boolean Whether or not an unacknowledged offline alarm exists.
device is_online Optional Boolean Whether or not the device is currently online.
device standby_time Optional String The number of minutes a device will be in standby mode.
device standby_mode Optional String A device's standby mode.
device standby_status Optional String A device's standby status
device battery_status Optional String A device's battery status
device power_status Optional String A device's power status
device battery_value Optional String A device's battery value
device power_value Optional String A device's power value
device connection_status Optional String A device's connection status
device feature Optional Array of Objects The feature linked to the account (See Sensaphone.net API/feature)
device firmware Optional Object Firmware version of Device
device firmware_auto_update Optional Boolean Will the Device automatically update to the latest firmware version
device firmware_target Optional Object The firmware version the Device will install
device firmware_available Optional Array of Objects A list of available firmware to install on the Device
device firmware_changelog Optional Array of Strings A list of the changes verses the currently installed version
Example JSON

Receive all Device information for a specific Device

  • Request JSON:
{
  "acctid":987654,
  "session":"0123-4567-8901",
  "request_type":"read",
  "device": {
      "device_id":1234
     }
}


  • Response JSON:
{
  "result":
  {
    "success":true,
    "code":0,
    "message":"OK"
  },
  "response": 
  {
    "device":[
     {
       "device_id": 1234,
       ...
     }
    ]
  }      
}

PUT

URI Mode Request URI's:

  • Edit the description of a Device 
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/description/{DESCRIPTION}
  • Edit the name of a Device 
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/name/{DEVICE_NAME}

JSON Mode Request URI: 

  POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "update"
  device Array of Objects The device object.
device device_id Integer ID of the device.
device CHILD PROPERTY   Device's child properties to be edited*

*One or more device child properties below are required in addition to "device_id".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device name Optional String Name of Device
device description Optional String Short description of Device
device timezone Optional String The timezone the Device is in
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device modbus_ports Optional Array of Objects TBD
device standby_time Optional String The number of minutes a device will be in standby mode.
device standby_mode Optional String A device's standby mode.
device clone Optional Integer Destination device_id to clone this device's data to
device feature Optional Array of Objects The feature linked to the device (See Sensaphone.net API/feature)
device firmware_auto_update Optional Boolean Will the Device automatically update to the latest firmware version
device firmware_target Optional Integer The firmware version the Device will install

POST

Adding a device

The preferred method to add a new Device is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a Device with only the id value (not to be confused with the device_id), all other values will be left empty until a PUT request is used. With the JSON Mode Request you can add a Device with all values defined in one step.

URI Mode Request URI:

  • Add a new Device 
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/id/{DEVICEID}

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "create"
  device Array of Objects The device object.
device id Integer Unique identifier located on the Device (Serial number, etc.)

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  device Required Array of Objects The parent device object.
device device_id Optional Integer ID of Device
device id Optional Integer Unique identifier located on the Device (Serial number, etc.)
device name Optional String Name of Device
device description Optional String Short description of Device
device location Optional Object Contains location information for the device.
location address Optional Object Address information for Device (See Sensaphone.net API/address)
location coordinates Optional Object GPS Coordinates information for Device (See Sensaphone.net API/coordinates)
device firmware Optional String Firmware version of Device
device default_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device device_schedule Optional Object Alarm Schedule data (See Sensaphone.net API/alarmschedule)
device zone Optional Array of Objects Device Zone data (See Sensaphone.net API/zone)
device offline_timeout Optional Integer The number of minutes a device must be offline before it goes into alarm.
device modbus_ports Optional Array of Objects TBD



Acknowledging Alarms

URI Mode Request URI:

  • Acknowledge All Alarms
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}/acknowledge_all_alarms/{true}

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "create"
  device Array of Objects The device object.
device device_id Integer ID of Device
device ack_offline_alarm Boolean A write-only property that will acknowledge a device offline alarm
device acknowledge_all_alarms Boolean A write-only property that will acknowledge all alarms for a device, including all device alarms and all zone alarms

* "acknowledge_all_alarms" supersedes "ack_offline_alarm", if it is present in the request json other properties will be ignored

DELETE

URI Mode Request URI:

  • Delete a Device from an account 
 DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/device/{DEVICE_ID}

JSON Mode Request URI: 

 POST https://rest.sensaphone.net/api/v1/device

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "delete"
  device Array of Objects The device object.
device device_id Integer ID of the device.
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API/device&oldid=274"