Connections

Introduction

Connections represent controllers that are connected to a cloud node on a local network. Each controller can operate one or more devices, which represent doors and gates (along with their accompanying readers), Aperio wireless locks, and any other devices that can be controlled with relays. There are two types of controllers:

• PDK controllers can be connected via ethernet or WiMAC and can operate 1–24 doors, depending on the model.
• Aperio hubs are connected via ethernet and can operate up to 64 Aperio wireless locks.

Connections are typically configured manually in pdk.io, but they can also be configured through the API.

The connection object

{
  "id": "767a1e35-bd34-4858-9130-a0a1900438ed",
  "name": "Test Connection",
  "type": "ethernet",
  "connected": true,
  "protocol": "IPv6",
  "ipaddress": "10.0.0.2",
  "ipv6Address": "fe80::5e85:7eff:fe60:dfa",
  "port": 10001,
  "dhcp": true,
  "netmask": null,
  "gateway": null,
  "dns": null,
  "macAddress": "5c:85:7e:60:0d:fa",
  "manufacturer": "PDK"
}

Property	Type	Description
id	String	The connection ID.
name	String	The connection name.
type	String	The connection type. Possible values include aperio, ethernet, usb, wirelessCoordinator, and wirelessGateway.
connected	Boolean	The connection status.
protocol	String	The protocol version. Possible values include IPv4 and IPv6.
ipaddress	String	The IPv4 address of the controller.
ipv6Address	String	The IPv6 address of the controller.
port	Integer	The port number used on the controller.
dhcp	Boolean	Whether DHCP is enabled.
netmask	String	The subnet mask.
gateway	String	The gateway IP address.
dns	String	The DNS IP address.
macaddress	String	The MAC address of the controller.
manufacturer	String	The ethernet module manufacter. Possible values include PDK and Lantronix.

Basic Endpoints

Create a connection

Request

POST https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/connections HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Connection",
  "type": "ethernet",
  "ipaddress": "10.0.0.2",
  "port": 10001
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The connection name.
type	Body	String	Yes	The connection type. Possible values include aperio, ethernet, usb, wirelessCoordinator, and wirelessGateway. The usb type is used for the on-board cloud node controller.
protocol	Body	String	No	The protocol version to use if type is set to ethernet. Possible values include IPv4 and IPv6 (default).
ipaddress	Body	String	Sometimes	The IPv4 address of the controller. This is required if type is set to ethernet or wirelessGateway.
ipv6Address	Body	String	No	The IPv6 address of the controller. This only applies if type is set to ethernet.
port	Body	Integer	Yes	The port number to be used on the controller.
macaddress	Body	String	Sometimes	The MAC address of the controller. This is required when type is set to aperio.
manufacturer	Body	String	No	The ethernet module manufacter. This only applies if type is set to ethernet. Possible values include PDK and Lantronix (default).

Response

The response contains the ID of the newly created connection object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "767a1e35-bd34-4858-9130-a0a1900438ed"
}

Retrieve a connection

Request

GET https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/connections/{{connection_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
connection_id	Path	Integer	Yes	The connection ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains a connection object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "767a1e35-bd34-4858-9130-a0a1900438ed",
  "name": "Test Connection",
  "type": "ethernet",
  "connected": true,
  "protocol": "IPv6",
  "ipaddress": "10.0.0.2",
  "ipv6Address": "fe80::5e85:7eff:fe60:dfa",
  "port": 10001,
  "dhcp": true,
  "netmask": null,
  "gateway": null,
  "dns": null,
  "macAddress": "5c:85:7e:60:0d:fa",
  "manufacturer": "PDK"
}

Update a connection

Request

PUT https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/connections/{{connection_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Connection",
  "type": "ethernet",
  "ipaddress": "10.0.0.2",
  "port": 10001
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
connection_id	Path	Integer	Yes	The connection ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The connection name.
type	Body	String	Yes	The connection type. Possible values include aperio, ethernet, usb, wirelessCoordinator, and wirelessGateway. The usb type is used for the on-board cloud node controller.
protocol	Body	String	No	The protocol version to use if type is set to ethernet. Possible values include IPv4 and IPv6 (default).
ipaddress	Body	String	Sometimes	The IPv4 address of the controller. This is required if type is set to ethernet or wirelessGateway.
ipv6Address	Body	String	No	The IPv6 address of the controller. This only applies if type is set to ethernet.
port	Body	Integer	Yes	The port number to be used on the controller.
macaddress	Body	String	Sometimes	The MAC address of the controller. This is required when type is set to aperio.
manufacturer	Body	String	No	The ethernet module manufacter. This only applies if type is set to ethernet. Possible values include PDK and Lantronix (default).

Response

HTTP/1.1 204 No Content

Delete a connection

Request

DELETE https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/connections/{{connection_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
connection_id	Path	Integer	Yes	The connection ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all connections

Request

GET https://systems.pdk.io/{{system_id}}/connections HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of connection objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "767a1e35-bd34-4858-9130-a0a1900438ed",
    "name": "Test Connection 1",
    "type": "usb",
    "connected": true,
    "port": 1
  },
  {
    "id": "4769e1db-d879-40b0-b968-ffaa343e982c",
    "name": "Test Connection 2",
    "type": "ethernet",
    "connected": true,
    "protocol": "IPv6",
    "ipaddress": "10.0.0.2",
    "ipv6Address": "fe80::5e85:7eff:fe60:dfa",
    "port": 10001,
    "dhcp": true,
    "netmask": null,
    "gateway": null,
    "dns": null,
    "macAddress": "5c:85:7e:60:0d:fa",
    "manufacturer": "PDK"
  }
]

Retrieve wireless diagnostics

Request

GET https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/diagnostics/wireless HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "767a1e35-bd34-4858-9130-a0a1900438ed",
    "name": "Test Connection",
    "type": "wirelessCoordinator",
    "nodes": [
      {
        "name": "Test Device",
        "shortAddress": "3ceb",
        "address": "0013a200403e07c6",
        "communicationLost": true,
        "averageRtt": 4737,
        "averageRetries": 0,
        "failureRate": 1
      }
    ],
    "links": [
      {
        "from": "0000",
        "to": "0013a200403e08c6",
        "lqi": 255
      }
    ]
  }
]

Configure a connection

Additional network configuration options are available for PDK ethernet modules. In order to apply these options, a connection's manufacturer property must be set to PDK.

Request

POST https://systems.pdk.io/{{system_id}}/cloud-nodes/{{cloud_node_id}}/connections/{{connection_id}}/configure HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "dhcp": false,
  "netmask": "255.255.255.0",
  "gateway": "10.0.0.1",
  "dns": "8.8.8.8"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
cloud_node_id	Path	String	Yes	The cloud node ID.
connection_id	Path	Integer	Yes	The connection ID.
system_token	Header	String	Yes	A valid system token.
dhcp	Body	Boolean	Yes	Whether DHCP should be enabled.
netmask	Body	String	No	The subnet mask.
gateway	Body	String	No	The gateway IP address.
dns	Body	String	No	The DNS IP address.

Response

HTTP/1.1 204 No Content