API Reference

Overview

gRPC

The APIs of G-SDK are defined using gRPC to maximize its compatibility among programming languages. And, gRPC uses protocol buffers as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages. Since the naming convention and data types of each language are different, you have to consult the generated header files in addition to these definitions.

Device gateway vs. master gateway

A master gateway manages devices through one or more device gateways. Due to this difference, the Connect Master API is different from the Connect API. And, since the master gateway is designed for multi-tenant systems, you have to use the Login API before using other APIs. The Tenant API and the Gateway API are also provided for the master gateway only. Apart from these differences, the other APIs are same both for the device gateway and the master gateway.

API Device Gateway Master Gateway Note
Connect O X manage devices directly
Connect Master X O manage devices via device gateways
Login X O login as an administrator or a tenant
Tenant X O manage tenants
Gateway X O manage device gateways
Server O X implement server matching

API definition

Each API sends a single request to the gateway and gets a single response back.

service Connect {
  rpc Connect(ConnectRequest) returns (ConnectResponse);
}

message ConnectRequest {
  ConnectInfo connectInfo;
}

message ConnectResponse {
  uint32 deviceID;
}

For brevity, when the response has no data, its definition is omitted in the reference manual.

XXX_Multi command

One of the design goals of G-SDK is to manage hundreds of devices easily. The more devices, the more cumbersome for developers to do same operations repetitively on multiple devices. To alleviate this overload, G-SDK provides XXX_Multi commands. For example, with User.EnrollMulti, you can enroll users to multiple devices with only one function call. All these operations will be executed in parallel by the gateway.

For these commands, if the operation fails on any of the target devices, the following deviceErrors will be returned.

Response
Parameter Type Description
deviceErrors ErrorResponse[] The errors on some of the target devices

Since the responses of all XXX_Multi commands have same definition, they are also omitted in the manual.

Core APIs

Connect

Manage connections between the device gateway and the devices.

ConnectMaster

Manage connections between the master gateway and the devices through device gateways.

Device

Provide the firmware and capability information of a device. Lock, reset, or upgrade devices.

Event

Read event logs from a device. Enable monitoring and receive real-time events from devices.

Network

Configure the IP address of a device.

User

Enroll and manage users. Set fingerprints, cards, and access groups to users.

Master gateway APIs

Gateway

Manage device gateways for the master gateway.

Login

Login to the master gateway as an administrator or a tenant.

Tenant

Manage tenants for the master gateway. Only an administrator can use these APIs.

Authentication APIs

Auth

Configure the options related to credentials such as cards and fingerprints.

Card

Read or write a card. You can also configure the options related to authenticating cards.

Finger

Scan a fingerprint. You can also configure the options related to authenticating fingerprints.

Face

Scan face templates. You can also configure the options related to authenticating faces.

Server

Implement server matching.

Access control APIs

You can specify which users can access which doors for specific schedules.

Access

Configure access levels and access groups.

Door

Configure doors and manage them.

Lift

Configure lifts and manage them.

Schedule

Make schedules, which will be used for access control and other configurations.

T&A APIs

T&A

Configure the options related to time & attendance. You can also get event logs with time & attendance or job code information.

Configuration APIs

Action

Configure what actions should be taken when specific triggers are fired.

Display

Configure the UI of devices. You can also upgrade the language pack.

RS485

Configure the RS485 communication parameters and manage the slave devices.

Status

Configure the LEDs and the buzzer for each status.

System

Configure the miscellaneous options of a device. You can also check if the device is locked.

Thermal

Configure the options related to thermal cameras.

Time

Configure the options such as Daylight Saving Time(DST) and time synchronization. You can also set the clock on the device.

VoIP

Configure the options related to VoIP(Voice over IP).

Wiegand

Configure Wiegand formats which will be used for interpreting card data and interfacing with 3rd party readers/controllers. It also provides APIs for managing Wiegand slave devices.

Zone APIs

You can configure several types of zones for high-level functions such as anti passback and intrusion alarm. G-SDK supports only local zones, where all devices should be within a RS485 network.

Anti passback zone

Timed anti passback zone

Intrusion alarm zone

Fire alarm zone

Scheduled lock zone

Interlock zone

Lift zone

Misc. APIs

Admin

Get the version of G-SDK.

Err

The error definition for XXX_Multi commands.