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;
device.Type type;
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;
- Set IPConfig.connectionMode to DEVICE_TO_SERVER.
- 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;
device.Type type;
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.
Search
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;
bool useSSL;
string serverAddr;
}
| 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
-
If the device was connected asynchronously, remove the device from the managed list using DeleteAsyncConnection.
-
Add the device ID to the accept filter using SetAcceptFilter.
After setting to SERVER_TO_DEVICE
-
Remove the device from the accept filter using SetAcceptFilter.
-
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 |