Interfacing with the Door Controller Test Tool

• Web GUI
• HTTP 
• WebSocket

There are three ways of sending commands and receiving feedback from the Arduino. You can use the web GUI, HTTP or WebSockets.

Web GUI

TODO

HTTP

Commands over HTTP are sent using query strings to http://arduino-ip:http-port/api. Below is a list of the field-value combinations that are provided.

• cmd
  • swipecard, enterpin, opendoor, closedoor, pushrex, activateinput, deactivateinput
  • getperipheralstate
• doorid  * The ID of the target door, specified in doors.cfg.
• id 
  • The ID of the target peripheral, specified in doors.cfg.
• facilitycode
  • 0-255
• cardnumber
  • 0-65535
• pin
  • PIN sequence (16 digits maximum)

The "doorid" and "id" field must always be specified, so Door Controller Test Tool knows which door and peripheral you are sending the command to. If issuing a "swipecard" command, you also need to specify the "facilitycode" and "cardnumber" field. Likewise, if issuing an "enterpin" command, you need to also append the "pin" field.

For example, if you want to simulate a card-swipe at the door specified in the "Configuring the Doors"-example, this is what the URL would look like:

http://192.168.1.15/api?cmd=swipecard&doorid=MainEntrance&id=rdrIn&facilitycode=123&cardnumber=12345

And to simulate opening the door:

http://192.168.1.15/api?cmd=opendoor&doorid=MainEntrance&id=doorMonitor

Getting the status of the lock:

http://192.168.1.15/api?cmd=getperipheralstate&doorid=MainEntrance&id=lock

Note that no quotes are needed when specifying the fields or values in the URL.

WebSocket

The WebSocket protocol allows for full-duplex communication with the Arduino, meaning that commands can be sent to Arduino while receiving updates from it simultaneously. Peripherals do not need to be polled for their states as they are pushed to the client after each state-change.

The DCTT WebSocket API consists of JSON structures that are sent to the WebSocket server on the Arduino via the WebSocket endpoint. The endpoint has the following composition, ws://[ARDUINO_IP_ADDRESS]:[ARDUINO_WEBSOCKET_PORT] (for example: ws://192.168.0.1:8888). The WebSocket port is 8888 by default and can be changed in the network configuration file.

To be able to communicate with the Arduino over WebSockets, a client which supports the WebSocket protocol RFC6455 is needed, for example a modern browser if building a GUI or Ws4Py if using Python.

The supported commands are listed below:

EnterPIN Sends a digit or a sequence of digits.
DoorId: (String) The id of the target door.
Id: (String) The id of the target reader.
PIN: (String) The digit or digits to be sent via Wiegand protocol to the PACS device.

{
  "EnterPIN": {
    "DoorId": "<doorId>",
    "Id": "<readerId>",
    "PIN": "<digit(s)>"
  }
}

SwipeCard
Swipes a Wiegand26-formatted card.
DoorId: (String) The id of the target door.
Id: (String) The id of the target reader.
FacilityCode: (String) The card's facility code, 0-255.
CardNumber: (String) The card's facility code, 0-65535.

{
  "SwipeCard": {
    "DoorId": "<doorId>",
    "Id": "<readerId>",
    "FacilityCode": "<facilityCode>",
    "CardNumber": "<cardNumber>"
  }
}

PushREX
Presses and releases a REX button.
DoorId: (String) The id of the target door.
Id: (String) The id of the target REX button.

{
  "PushREX": {
    "DoorId": "<doorId>",
    "Id": "<rexId>"
  }   
}

OpenDoor
Opens the door, i.e. the door monitor.
DoorId: (String) The id of the target door.
Id: (String) The id of the target door monitor.

{
  "OpenDoor": {
    "DoorId": "<doorId>",
    "Id": "<doorMonitorId>"
  }   
}

CloseDoor
Closes the door, i.e. the door monitor.
DoorId: (String) The id of the target door.
Id: (String) The id of the target door monitor.

{
  "CloseDoor": {
    "DoorId": "<doorId>",
    "Id": "<doorMonitorId>"
  }   
}

ActivateInput
Activates the digital input
DoorId: (String) The id of the target door.
Id: (String) The id of the target digital input.

{
  "ActivateInput": {
    "DoorId": "<doorId>",
    "Id": "<inputId>"
  }   
}

DeactivateInput
Deactivates the digital input
DoorId: (String) The id of the target door.
Id: (String) The id of the target digital input.

{
  "DeactivateInput": {
    "DoorId": "<doorId>",
    "Id": "<inputId>"
  }   
}

RequestUpdate
Forces all peripherals and readers to send an update specifying their current state (useful when determining the states of everything attached for the first time)

{
  "RequestUpdate": {}   
}