Connect API

For the device gateway only. Refer to the Connect Master API for the master gateway.

Overview

The Connect API is for managing the connections between the device gateway and BioStar devices. There are two modes according to the direction of the connection.

Connection mode

enum ConnectionMode {
  SERVER_TO_DEVICE = 0;	
  DEVICE_TO_SERVER = 1;	
}
SERVER_TO_DEVICE
The gateway connects to the device.
DEVICE_TO_SERVER
The device connects to the gateway.

With the default of SERVER_TO_DEVICE, the gateway will connect to the device. To change the mode, you have to call SetConnectionMode.

Synchronous vs. asynchronous

When the mode is SERVER_TO_DEVICE, there are two ways for the gateway to connect to the devices. With Synchronous APIs, you can directly connect to a device. Though it is the simpler way, you have to manage the connection manually. When you have to manage many devices, Asynchronous APIs would be preferrable since most connection tasks are managed by the gateway automatically.

Secure communication

All the packets between the gateway and the devices are encrypted for secure communication. You can choose one of the two options for packet encryption.

Default
Use AES256 for encrypting the packets.
SSL
Use TLS1.2 for communication. Though it is more secure, you have to manage the certificates. Refer to SSL APIs for the details.

Though SSL and TLS are not same exactly, both terms are used interchangeably in this manual. Without further description, SSL means TLS v1.2 protocol.

Status

With the asynchronous APIs and the device-to-server connection, the connections are managed by the gateway in the background. To get the current status of connections, you can use GetDeviceList or SubscribeStatus.

message DeviceInfo {
  uint32 deviceID;
  ConnectionMode connectionMode;
  string IPAddr;
  int32 port;
  Status status; 
  bool autoReconnect; 
  bool useSSL;
}
status
The current status of the device.
autoReconnect
True only if the device is connected by AddAsyncConnection.
enum Status {
  // Normal Status
  DISCONNECTED = 0x00;
  TCP_CONNECTED	= 0x01;
  TLS_CONNECTED = 0x02;
  
  // TCP Connection Error Status
  TCP_CANNOT_CONNECT = 0x100;
  TCP_NOT_ALLOWED = 0x101;

  // TLS Connection Error Status
  TLS_CANNOT_CONNECT = 0x200;
  TLS_NOT_ALLOWED = 0x201;
}

GetDeviceList

Get the information of the managed devices.

Response
Parameter Type Description
deviceInfos DeviceInfo[] The information of the managed devices

SubscribeStatus

If you subscribe to the status channel, the gateway will notify you whenever the status of a device changes.

message StatusChange {
  uint32 deviceID;
  Status status;
  uint32 timestamp; 
}
status
The new status of the device.
timestamp
The time when the change is occurred in Unix time format.

Synchronous connection

Connect

Connect synchronously to a device. If successful, the device ID will be returned.

message ConnectInfo {
  string IPAddr; 
  int32 port;
  bool useSSL;
}
IPAddr
IPv4 address such as 192.168.0.2.
Port
The port number of the device. Only used when the connection mode is SERVER_TO_DEVICE. The default is 51211.
useSSL
Specify whether SSL is used for communication.

To set ConnectInfo.useSSL to true, you have to call EnableSSL on the device first.

Request
Parameter Type Description
connectInfo ConnectInfo The connection information of the device
Response
Parameter Type Description
deviceID uint32 The ID of the connected device

Asynchronous connection

Synchronous connection is the easier and simpler way to connect to a device. However, if you have tens of or hundreds of devices, managing synchronous connections could become a chore. To alleviate this overload, asynchronous APIs are provided. You only have to register devices to connect. Then, the gateway will handle all the tasks in the background. When a managed device is disconnected, the gateway will try to reconnect automatically, too.

To get the current status of the managed devices, you should use GetDeviceList or SubscribeStatus.

AddAsyncConnection

Add the target devices to connect. The gateway will manage the connections to the devices in the background. To get the list of managed devices, call GetDeviceList.

You can use SearchDevice to find out devices in a subnet.

message AsyncConnectInfo {
  uint32 deviceID; 
  string IPAddr; 
  int32 port; 
  bool useSSL; 
}
deviceID
It is same with the S/N on the sticker at the back of a device.
IPAddr
IPv4 address such as 192.168.0.2.
Port
The port number of the device. Only used when the connection mode is SERVER_TO_DEVICE. The default is 51211.
useSSL
Specify whether SSL is used for communication.

To set AsyncConnectInfo.useSSL to true, you have to call EnableSSL on the device first.

Request
Parameter Type Description
connectInfos AsyncConnectInfo[] The connection information of the devices

DeleteAsyncConnection

Delete the specified devices from the managed list. If these device are connected, they will be disconnected first.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices to be deleted

Device-to-server connection

To make a device connect to the gateway, you have to do the followings;

  1. Set IPConfig.connectionMode to DEVICE_TO_SERVER.
  2. Modify the AcceptFilter to include the device ID.

SetAcceptFilter

You can select the devices to be accepted using the AcceptFilter.

message AcceptFilter {
  bool allowAll;  
  repeated uint32 deviceIDs; 
  repeated string IPAddrs; // not yet supported
  repeated string subnetMasks; // not yet supported
}
allowAll
Allow all incoming connections. If it is true, ignore the other parameters.
deviceIDs
Allow the connections from the specified IDs
Request
Parameter Type Description
filter AcceptFilter The filter specifying the accept list

GetAcceptFilter

Get the accept filter set by SetAcceptFilter.

Response
Parameter Type Description
filter AcceptFilter The filter set by SetAcceptFilter

GetPendingList

If a device is trying to connect to the gateway but is not included in the accept filter, it is registered to the pending list. By reviewing the pending list, you can choose the new devices to be accepted.

message PendingDeviceInfo {
  uint32 deviceID;
  string IPAddr;
  uint32 lastTry; 
}
lastTry
The last time the device tried to connect. It is in Unix time format.
Response
Parameter Type Description
deviceInfos PendingDeviceInfo[] The devices filtered by the accept filter

Disconnection

You can close the connections between the gateway and devices. The behavior after disconnection will differ according to how the connection was established.

Connect
The device will be removed from the managed list. The gateway will not try to reconnect to the device.
AddAsyncConnection
After some delay, the gateway will try to reconnect to the device. If you do not want this, remove the device from the managed list using DeleteAsyncConnection.
Device-to-server
After some delay, the device will try to reconnect to the gateway. If you do not want this, remove the device from the accept filter using SetAcceptFilter.

Disconnect

Disconnect the specified devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices to be disconnected

DisconnectAll

Disconnect all the connected devices.

You can search devices within a subnet using SearchDevice.

SearchDevice

message SearchDeviceInfo  {
  uint32 deviceID;
  device.Type type;
  bool useDHCP;
  ConnectionMode connectionMode; 
  string IPAddr;
  int32 port;
}
Request
Parameter Type Description
timeout uint32 Search timeout in milliseconds
Response
Parameter Type Description
deviceInfos SearchDeviceInfo[] The information of the devices found in the subnet

Connection mode

You can change the connection mode of a device. The default is SERVER_TO_DEVICE. After changing the mode, you have to do the followings to reconnect to the device.

After setting to DEVICE_TO_SERVER

  1. If the device was connected asynchronously, remove the device from the managed list using DeleteAsyncConnection.

  2. Add the device ID to the accept filter using SetAcceptFilter.

After setting to SERVER_TO_DEVICE

  1. Remove the device from the accept filter using SetAcceptFilter.

  2. Connect to the device using Connect or AddAsyncConnection.

SetConnectionMode

Change the connection mode of a device. The gateway will internally call Network.SetIPConfig and change the related parameters accordingly.

Request
Parameter Type Description
deviceID uint32 The ID of the device
connectionMode ConnectionMode The connection mode to be set

SetConnectionModeMulti

Change the connection modes of multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
connectionMode ConnectionMode The connection mode to be set

SSL

For more secure communication, you can enable SSL on devices. If enabled, all communication will conform to TLS 1.2 specification.

For SSL/TLS, you have to manage the certificates properly. The device will use the root certificate to validate the certificate of the gateway. So, if you have more than one device gateways, they should share the root certificate to connect to a SSL-enabled device.

EnableSSL

Enable SSL on a device. After this, you have to set the useSSL to true when using Connect or AddAsyncConnection.

Request
Parameter Type Description
deviceID uint32 The ID of the device

EnableSSLMulti

Enable SSL on multiple devices

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices

DisableSSL

Disable SSL on a device. After this, you have to set the useSSL to false when using Connect or AddAsyncConnection.

Request
Parameter Type Description
deviceID uint32 The ID of the device

DisableSSLMulti

Disable SSL on multiple devices

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices

Slave

message SlaveDeviceInfo {
  uint32 deviceID;
  repeated uint32 rs485SlaveDeviceIDs;
  repeated uint32 wiegandSlaveDeviceIDs;
}
deviceID
The ID of the parent device to which the slaves are registered.
rs485SlaveDeviceIDs
The IDs of the slave devices registered on RS485 channels.
wiegandSlaveDeviceIDs
The IDs of the slave devices registered on Wiegand input.

You can add slave devices on a RS485 channel or Wiegand input of a device. For searching and registering slave devices, refer to the corresponding sections in RS485 and Wiegand.

The slave information is not stored in the database. So, to access the slave devices, you have to call SetSlaveDevice after the device gateway is reconnected.

GetSlaveDevice

Get the slave device information.

Response
Parameter Type Description
slaveDeviceInfos SlaveDeviceInfo[] The slave device information

SetSlaveDevice

Set the slave device information. The slave devices should be registered first using RS485.SetDevice or Wiegand.SetDevice.

Request
Parameter Type Description
slaveDeviceInfos SlaveDeviceInfo[] The slave device information