Overview


This article explains three ways to control a device's relays in Suprema G-SDK, and which method to use in each situation.


Suprema access control devices typically have built-in relays. A relay is the device's physical output for controlling an external device such as a door lock, and it opens or closes its contact based on authentication results or configured events. Whether switching the contact locks or unlocks the connected device depends on the relay configuration.


The number of relays varies by device model. You can check it with the DeviceCapability.maxRelays value returned by the GetCapability API.


Who controls the relay?


In Suprema G-SDK, a relay is controlled by either a Door or an Action. The API you can use depends on which one controls the relay.


Relays assigned to a Door

  • When a relay is included in a Door configuration, it becomes part of that Door and is controlled by the Door API.
  • To check whether a relay is already assigned to a Door, call Door.GetList and look at the relay configured in each DoorInfo.

Relays not assigned to a Door

  • These relays are controlled directly by an Action on the device.
  • To operate a relay on demand, use RunAction.
  • To operate a relay automatically when a specific trigger occurs on the device, use the Trigger & Action feature.


Note
A relay assigned to a Door does not respond to RunAction or Trigger & Action.


Method 1. Controlling relays directly with RunAction


Starting with Suprema G-SDK v1.8.0, you can use the RunAction API to execute a specified action on a device. Use it to operate a relay on demand from your own application, for example, when a user presses a button in your app.


RunAction supports several action types. To control a relay, use ACTION_RELAY.


For the request and response of RunAction, see the RunAction API.


Procedure

  1. Set deviceID to the ID of the device that operates the relay.
  2. Set Action.type to ACTION_RELAY.
  3. In RelayAction, set relayIndex to the relay you want to operate. The relay index starts at 0.
  4. In Signal, set count to the number of times the relay operates, and set onDuration, offDuration, and delay in milliseconds. 
  5. Call RunAction with the configured Action.


Note
A relay operated by RunAction does not generate an event log. To verify the operation, check the sound of the relay contact or the behavior of the connected external device.


Method 2. Controlling relays conditionally with Trigger & Action


With Trigger & Action, you can configure the device to operate a relay automatically when an event occurs, an input signal is detected, or a schedule starts or ends.


A Trigger defines when the relay operates, and an Action defines how it operates. The two are registered on the device as one pair, and the device can store up to 128 pairs.


For the available trigger types, configuration fields, and APIs, see the Trigger & Action API.


Example


For instance, an alarm lamp is connected to relay 0 on the device, and the relay is not assigned to a Door. The alarm lamp needs to flash whenever card or fingerprint authentication fails, so that failed attempts are noticed at the entrance.


When event triggers for card and fingerprint authentication failure are paired with a relay action, the device flashes the alarm lamp on each failure. Card and fingerprint failures are separate event codes, so register one pair for each.


For instructions on creating triggers and registering them, refer to the G-SDK Trigger & Action API Tutorial for the client language you use. For example, if you are using Python, see the Python Trigger & Action API Tutorial.


Event codes for TRIGGER_EVENT are listed in the Event Code section of the Event API document.


Method 3. Controlling relays assigned to a Door


When a relay is assigned to a Door, it becomes part of that Door configuration. How you control the Door determines how the relay operates. Each Door can have only one relay, and every Door must have a relay assigned. 


A Door has two independent states: a lock state (Locked/Unlocked) and a door position (Open/Closed). A Door can stay Closed while Unlocked until someone opens the entrance, and can be Open while Locked if it is forced open.


When the Door's lock state changes, the device operates the relay as specified in the Door configuration. For example, when your application unlocks the Door, the assigned relay remains activated until the Door is locked or released.


Controlling relays with the Door API


Control the relay by calling Door.Lock, Door.Unlock, or Door.Release. To check the current state of the Door, call Door.GetStatus. These APIs take the Door ID, not a relay index.


For instructions on configuring and registering a Door with DoorInfo and Door.Add, refer to the G-SDK Door API Tutorial for the client language you use. For example, if you are using Python, see the Python Door API Tutorial.


For the parameters and behavior of each call, see the Door API.


Note
Door Mode Override is available from G-SDK v1.9.0.
Use Device.GetCapability to verify that doorModeOverrideSupported is true. When doorFlag is set to OPERATOR and normalizeTimer is configured, the Door returns to its normal state when the timer expires.


DoorFlag


Lock and Unlock requests for a Door carry a DoorFlag, which indicates what is controlling the Door and at what priority. The priority of DoorFlag is EMERGENCY > OPERATOR > SCHEDULED > NONE.


A Lock or Unlock request with lower priority than the flag currently applied to the Door is rejected, and the relay does not operate.


For the DoorFlag values and for opening a locked Door in an emergency, see [Suprema G-SDK] How to Configure and Use Lock Override. Lock Override is available from G-SDK v1.9.0.