PDK & DW Spectrum Integration Documentation

 

Sending Events in PDK.io to DW Spectrum

Generic Event

 

 

A Generic Event occurs when the server receives an HTTP request from an external system such as an alarm, access control device, or a monitoring system. This is a default event and allows commands to be sent from DW Spectrum to third-party systems such as pdk.io. 

 

DW Spectrum allows pdk.io devices to send an HTTP string known as a CreateEvent API call. The CreateEvent request must follow the proper format in order to be read by the server. In addition, the event fields in the rule must match the corresponding fields in the HTTP request to be acted upon. The full server API documentation is accessed on any installed server from: 

http://<serveripaddress>:<servernetworkport>/static/api.xml 

 

NOTE: Values in the Event field are case-sensitive, and an empty string functions as a wildcard, where any value is considered a match. 

 

When a Generic Event is created in the DW Spectrum System, there are three basic parameters associated with each event; each HTTP request contains these three parameter data pieces: the Source, Caption, and Description. 

These three data events are searched and filtered by the DW System. This can be leveraged in the Bookmark Log (Ctrl-B) when bookmarks are created from events, and when creating Event Rules (Ctrl-E).

Source

The resource that initiates the event: device (motion detection, input signal, etc.) or server (storage failure, server failure, etc.). The source parameter of the Generic Event is the name of the device in the pdk.io system that generated the PDK io event.

Caption

Caption is an optional class value used to identify an object type. Entries in this field should match the corresponding field in the HTTP request and is case sensitive. If the field is empty, it will always be considered a match. The caption parameter of the Generic Event is determined by the corresponding pdk.io event type that was generated. This can be any of the following values:

PDK.io Event Type	DW Spectrum IPVMS Generic Event Caption	Description
Open (DPS)	door.input.dps.opened	The door position sensor detected the door open.
Close (DPS)	door.input.dps.closed	The door position sensor detected the door closed.
AutoOpen Enabled	door.autoopen.on	Auto open became active on the device.
AutoOpen Disabled	door.autoopen.off	Auto open became deactivated on the device.
Door Propped Alarm	door.alarm.propped.on	The door propped alarm has triggered for the device.
Door Propped Alarm Clear	door.alarm.propped.off	The door propped alarm has been cleared for the device.
All Prop Clear	door.alarm.propped.alloff	All door propped alarms have been cleared.
Door Forced Alarm	door.alarm.forced	The door forced alarm has triggered for the device.
Communication Loss	endpoint.alarm.commloss.on	Communication to the connection has been lost.
Communication Loss Clear	endpoint.alarm.commloss.off	Communication to the connection has been re-established.
No Person Associated with Credentials	door.request.unknown	An unknown credential was scanned and access was implicitly denied.
Access Allowed	door.request.allowed	A known credential was scanned and access was allowed.
Access Denied	door.request.denied	A known credential was scanned and access was denied.
Duress PIN Entered	door.request.duress	A duress PIN was used to authenticate at the reader.
Request to Exit Open	door.input.rex.on	The request to exit was triggered on the door.
Request to Exit Closed	door.input.rex.off	The request to exit was cleared on the door.
Card Scan Error	error.card.parse	Bad data was received from the card reader connected to the door.

 

Description

Description is an optional attribute value used to distinguish objects within a class. Entries in this field should match the corresponding field in the HTTP request and is case sensitive. The description parameter of the Generic Event is the same text that is generated for the info text of the Live Events in pdk.io. 

NOTE: Generic Events created by pdk.io do not have the following parameters defined; Metadata and Occurs are parameters defined only in DW Spectrum. 

 

 

Metadata

Metadata, strictly a DW Spectrum parameter and not defined in PDK.io, is used to pass a device identifier that will specify devices the event is limited to.

IMPORTANT: PDK does not define the Metadata parameter; the Force Acknowledgement option cannot be used when using the Show Notification action as part of a rule event.

Occurs

Occurs is a DW Spectrum parameter and not defined in PDK.io. This is an optional field in DW Spectrum for the State. If there is no State field in the HTTP request, the event is considered instant. All Generic Events created by pdk.io are considered instant Generic Events.

IMPORTANT: If a continuous action such as “device recording” or “repeat sound” is bound to an instant Generic Event (one without a State field) the rule will not work.

 

Triggering Actions in PDK.io from DW Spectrum

After installing the NVR Integration Tool you will be able to trigger specific actions in pdk.io from the DW Spectrum interface using Event rules with the Soft Trigger Event and Do HTTP Request Action.

The parameters of the Do HTTP Request Action must be populated as shown below for the actions to complete successfully in pdk.io.

 

 

NOTE: Refer to the fields in the right-side Action panel above for an example of how the content should appear in each of the fields described below. 

Do - Click on this field (or the Action panel in the list) to select from a menu of Actions.

 

 

Interval of action - Check this option to aggregate the number of times the action will be triggered. For No more than once per a given amount of time, or instance, enter an integer value (1 - 999) and select a time interval from the menu (seconds, minutes, hours, or days). If unchecked, the action is instant and will occur whenever the event is triggered.

 

HTTP URL - This is the HTTP link to the external system that will receive the request. It can also contain the request itself. The URL should be formatted as follows: 

http://localhost:9191/commands/{command-name} 

The {command-name} must be one of the following Command Names in the table below and the parameter /commands/ (as shown in the screen example above) precedes the command name(s) in the string of text. If more than one command name is used, each command name is separated by a comma (no spaces). 

Command Names

NOTE: The {command-name} is case sensitive and must be exactly as shown in this table. 

{command-name}	Action Performed in pdk.io
open	Changes the relay associated with the device to the open state.
close	Changes the relay associated with the device to the closed state.
dnd	Toggles the do-not-disturb flag on the device.
forceToggle	Forces the relay associated with the device into the opposite of its current state regardless of holds or auto opens.
tryOpen	Performs an Open/Close action on the device which is the same as an access allowed scan in that it will: Change the relay associated with the device to the open state Leave the relay in the open state for the specified dwell time listed in the devices configuration in pdk.io Change the relay associated with the device to the closed state.
commands	Used to specify multiple other commands to be used

HTTP content - The HTTP content should be formatted as follows: 

{“panelid”:“{Cloud Node Serial Number}”,“doors”:[{Device ID number(s)}]}

as in the following: 

{“panelid”:“1070ECB”,“doors”:[1]} 

 

Note the use and placement of colons ( : ) commas ( , ) and brackets [ ] and that each parameter is enclosed in “double-quotes” with {curly brackets} at each end of this HTTP content string of text. 

 

{Cloud Node Serial Number} - This is the serial number labeled on the inside door of the pdk.io appliance or it can also be found on the pdk.io website. It will be something similar to 1070XXX (where XXX is a unique three-character alphanumeric designation). 

 

{Device ID number(s)} - This is a comma-separated list of the Device IDs that you would like the action performed on (no spaces). If performing the action on a single device, no comma is needed. The Device ID is found by navigating to the device’s configuration screen in pdk.io and look in the browser URL bar. The number at the end is the Device ID. 

 

For example: 

pdk.io/appliances/1070ECB/configuration/devices/1

 

The Device ID for this device is 1.

 

 

Content type - Must be left at Auto.

 

Login and Password - Leave these two fields blank.

 

Authentication type - Must be left at Auto.

 

Request type - Must be left at Auto.

 

Click OK to accept the input changes for this screen. 

 

Advanced Use Cases

 

It is possible to have multiple actions triggered in pdk.io using a single Soft Trigger Event. To do so in the Do HTTP Request Action, you will use the commands {command-name} in the HTTP URL and format the HTTP content similar to the following. 

{“Panelid”:“{Cloud Node Serial Number}”,“doors”:[{Device ID number(s)}],“commands”:[“{command-name},{command-name}”]}

{command-name} -      This value is a comma-separated list of the Command Name options listed above that you would like to have triggered. Each command name is surrounded by double-quotes. Multiple commands can be used, separated by a comma (no spaces), and must be preceded by “commands” as illustrated here. 

{“panelid”,“1070ECB”,“doors”:[1],“commands”:[“close”,“dnd”]}

(This command string format would be entered in the HTTP content field.)