DeviceLink

Description

The device link module allows a user to create a somewhat direct link to a device. This can be used to send either UDP or TCP packages over the backend to a device and thus allows basically any protocol to be supported when communication from client to device and vice versa. The backend needs to act as a middleman because it does know the required address information for a given device. Furthermore, it allows, if required, to separate the network interfaces and keep the devices for example behind a firewall or in a virtual private cloud.

As shown in the diagram above, this is done by creating two sockets. Whenever one socket receives a message it is send to the other peer by the second socket.

API

Endpoints

POST

Create Device Link

DEL

Stop Device Link

Create Device Link

Creates a device link that allows direct communication over the backend to the device.

POST

/api/v1/devicelink/:deviceIdentifier

Access

This endpoint requires create permission for the resource deviceLink.

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Request Body

Name	Description
protocol stringenum	The protocol to use for this device link. Possible values: tcp, udp
devicePort integeroptional	The port any package should be sent to on the device. This value is optional. However, if it is not set in the config, it is required in this endpoint.
timeout integeroptional	The timeout in milliseconds after which a UDP socket is closed. The socket does never timeout whenever its not set here and in the configuration of the module.
source objectoptional	This object can be used to set up client information. These information will be used to only allow a client with the set host:port combination to send message over this device link. Otherwise, the first client connected will inherit the device link. Furthermore, using `udp` as a protocol will immediately send data from the device to the client at the specified host:port address. Note: This feature might not be applicable for any device yet.
source.host string	Host information about the client.
source.port integer	Port information about the client.
encrypt objectoptional	In order to encrypt the traffic, set up a key and initialization vector. The cipher will be AES-256-ctr
encrypt.key string	The key used for encryption as well as decryption in the hex format.
encrypt.initializationVector string	The initial vector used for encryption as well as decryption in the hex format.

Response

Name	Description
devicePort integeroptional	The port any package should be sent to on the device. This value is optional. However, if it is not set in the config, it is required in this endpoint.
timeout integeroptional	The timeout in milliseconds after which a UDP socket is closed. The socket does never timeout whenever its not set here and in the configuration of the module.
source objectoptional	This object can be used to set up client information. These information will be used to only allow a client with the set host:port combination to send message over this device link. Otherwise, the first client connected will inherit the device link. Furthermore, using `udp` as a protocol will immediately send data from the device to the client at the specified host:port address. Note: This feature might not be applicable for any device yet.
source.host string	Host information about the client.
source.port integer	Port information about the client.
encrypt objectoptional	In order to encrypt the traffic, set up a key and initialization vector. The cipher will be AES-256-ctr
encrypt.key string	The key used for encryption as well as decryption in the hex format.
encrypt.initializationVector string	The initial vector used for encryption as well as decryption in the hex format.
port integer	The port the client should use to communicating with the backend to.
token string	The token to close the device link again.

Stop Device Link

Stops a device link based on the token returned from the create request.

DELETE

/api/v1/devicelink/:deviceLinkToken

Access

This endpoint requires delete permission for the resource deviceLink.

URL Parameter

Name	Description
deviceLinkToken string	The token to close the device link again.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.