platform sdk access control units

About access control units and interface modules

An access control unit is the controller that manages a set of doors. The Platform SDK exposes it through the Unit entity. A unit provides collections of Doors and InterfaceModules and belongs to an AccessManagerRole. Interface modules connect physical hardware to logical access points. The unit also reports chassis-level alarm states through ACFailure, BatteryFailure, and Tamper.

An interface module is an input/output board installed under the unit, such as a Mercury LP series controller, a Honeywell PW board, or a wireless lock gateway. Each interface module connects card readers, request-to-exit (REX) buttons, door sensors, door locks, buzzers, and other devices to the unit's logical access points.

Common tasks

• Enrolling a unit: add a new access control unit to an AccessManagerRole.
• Attach interface modules: see "Adding an interface module" below.
• Read unit health: IsOnline, IsRunning, plus the chassis-input states ACFailure, BatteryFailure, Tamper.
• Move a unit to a different Access Manager role: Engine.ActionManager.MoveAccessControlUnit(Unit unit, Role destinationRole).

The Unit entity

The SDK class for the access control unit is Unit in the Genetec.Sdk.Entities namespace.

Unit unit = engine.GetEntity<Unit>(unitGuid);

string ipAddress = unit.IPAddress;
string firmwareVersion = unit.FirmwareVersion;
bool isRunning = unit.IsRunning;
int doorCount = unit.Doors.Count;
int interfaceModuleCount = unit.InterfaceModules.Count;
AccessControlExtensionType extensionType = unit.UnitExtensionType;

The read-only AccessManagerRole property identifies the unit's parent role. The read-only UnitExtensionType property returns an AccessControlExtensionType value that identifies the unit's access control extension.

The SerialNumber, MacAddress, and FirmwareVersion properties are read-only. The IPAddress and TimeZone properties support reading and writing. The platform validates each property update independently; Unit provides no method to update these properties atomically.

Doors lists the doors managed by the unit. InterfaceModules lists the attached input/output boards. Devices lists every device on the unit, including readers, sensors, and outputs.

Three chassis-level input states report alarm conditions: ACFailure reports AC power loss, BatteryFailure reports battery failure, and Tamper reports the tamper switch state. All three properties use InputState values and support reading and writing, so applications can simulate the inputs in test environments. IsRunning, IsOnline, and the IsOnlineChanged event report runtime state. UnitReplacementLastUpdate reports the last hardware-swap event.

Interface module model

Interface modules are organized hierarchically. The SDK exposes the structure through a small set of base classes:

• AccessControlInterfaceBase: the abstract root. Carries a Guid identifying the interface.
• AccessControlInterfaceParentBase: extends the base for parent interfaces, the controllers that connect to the unit through Ethernet or RS-485. Adds IpAddress, Hostname, Port, Channel, and a read-only CustomSupervisedInputs collection.
• AccessControlInterfaceChildBase: Extends the base for child interfaces, the boards connected to a parent through a bus.
• AccessControlInterfaceSubChildBase: Extends the base for sub-child interfaces, such as individual door locks connected through a child board. Adds DoorLockNumber.

These base classes are abstract and have no public constructors. Developers do not instantiate them directly. Instead, they construct a GenericAccessControlInterface and select the interface module type with an enum value.

Adding an interface module: GenericAccessControlInterface

GenericAccessControlInterface is the unified construction class for every supported interface module type. The constructor takes an AccessControlInterfacePeripheralsType value that selects the family:

var controller = new GenericAccessControlInterface(
    AccessControlInterfacePeripheralsType.LP1502)
{
    Name = "Lobby controller",
};

// Configure connection and network settings through Properties.
// On GenericAccessControlInterface, settings such as channel and
// connection address are not strongly typed members.

var mr52 = new GenericAccessControlInterface(
    AccessControlInterfacePeripheralsType.MR52)
{
    Name = "MR52 (lobby door)",
    Parent = controller.Guid,
};

unit.AddAccessControlInterfaces(new List<GenericAccessControlInterface>
{
    controller,
    mr52,
});

Unit.AddAccessControlInterfaces(List<GenericAccessControlInterface>) persists the interface set onto the unit. Pass parents and children together: the SDK persists them as a connected set.

GenericAccessControlInterface exposes:

• Name: A string containing the interface module's display name. Supports reading and writing.
• Parent: A nullable Guid identifying the parent of a child or sub-child interface. Supports reading and writing. The value is null for parent interfaces.
• InterfaceType: A read-only AccessControlInterfacePeripheralsType property identifying the interface type selected at construction.
• Properties: A read-only ReadOnlyDictionary<AccessControlInterfaceProperty, object> property containing the settings for the selected InterfaceType.

Strongly typed interface classes

Each supported interface module has a dedicated class that exposes its settings as typed properties. Each class has a public parameterless constructor.

Parent controller classes, such as MercuryLP1502, derive from AccessControlInterfaceParentBase. They expose IpAddress, Hostname, Port, Channel, and the CustomSupervisedInputs collection described below.

Child board classes, such as MercuryMR52, derive from AccessControlInterfaceChildBase. Sub-child device classes derive from AccessControlInterfaceSubChildBase, which adds DoorLockNumber.

These classes are in the AccessControlInterfaceParent, AccessControlInterfaceChild, and AccessControlInterfaceSubChild namespaces under Genetec.Sdk.Entities.AccessControl.AccessControlInterfaces.

These typed classes are not GenericAccessControlInterface instances, so you cannot pass them to Unit.AddAccessControlInterfaces. Persist them through the access-control peripherals builder from Engine.EntityManager:

var controller = new MercuryLP1502
{
    IpAddress = IPAddress.Parse("192.168.1.50"),
    Port = 3001,
};

var mr52 = new MercuryMR52();

engine.EntityManager.GetAccessControlInterfacePeripheralsBuilder(unitGuid)
    .AddAccessControlBusInterface("Lobby controller", controller)
    .AddAccessControlChildInterface("MR52 (lobby door)", mr52, controller.Guid)
    .Build();

Use the typed classes for compile-time-checked network and connection settings, or GenericAccessControlInterface with SetProperty for a single construction class that covers every module type.

The peripherals type enum

AccessControlInterfacePeripheralsType identifies the interface type. It is in the Genetec.Sdk.Entities.AccessControl.AccessControlInterfaces namespace.

It includes Mercury LP, MP, and EP series controllers; Mercury MR child boards; HID Mercury M-series child boards; Honeywell PW boards; PRO panels; and wireless lock interfaces. Wireless lock interfaces include AD300, AD400, Schlage NDE, Engage gateway, PIM400, SimonVoss, SmartHandle, Padlock, and Cylinder.

Select the value that matches the physical hardware. Your development environment displays the available values.

Configuring interface module properties

The properties available on a GenericAccessControlInterface depend on the chosen InterfaceType. The SDK populates a property dictionary at construction time. Read the dictionary through Properties, identify the key for the setting, and call SetProperty(key, value) to change its value:

var controller = new GenericAccessControlInterface(
    AccessControlInterfacePeripheralsType.LP1502);

// Find a key by name and set its value. For LP1502, ChannelIpPort
// holds the controller's channel address as "ip:port".
AccessControlInterfaceProperty channelIpPortKey = controller.Properties.Keys
    .FirstOrDefault(k => k.PropertyName == "ChannelIpPort");

if (channelIpPortKey != null)
{
    controller.SetProperty(channelIpPortKey, value: "192.168.1.50:3001");
}

AccessControlInterfaceProperty exposes PropertyName as a string and PropertyType as a runtime Type. The property has only an internal constructor; do not try to construct keys yourself. Read keys from the Properties.Keys collection and pass the existing key to SetProperty.

Existing interface module settings

Unit.InterfaceModules contains the GUIDs of the unit's interface modules. For supported interface types, InterfaceModule.GetAccessControlInterface() returns the configuration. The returned type determines which settings are available. Parent controller configurations expose Channel, IpAddress, Hostname, and Port; child boards expose settings specific to their hardware.

For unsupported interface types, including Readers, Inputs, and Outputs (RIO) interfaces, GetAccessControlInterface() throws SdkException with SdkError.InvalidOperation. Handle this error for each module so that enumeration continues to the remaining modules.

The example reads channel numbers from parent controllers and skips unsupported modules. It catches only SdkError.InvalidOperation from GetAccessControlInterface(); other errors propagate to the caller. engine is a connected SDK engine, and unitGuid identifies the unit to inspect. Both interface configuration base classes are in the Genetec.Sdk.Entities.AccessControl.AccessControlInterfaces.AccessControlInterfaceBaseClasses namespace.

var unit = engine.GetEntity<Unit>(unitGuid);

foreach (Guid moduleGuid in unit.InterfaceModules)
{
    var module = engine.GetEntity<InterfaceModule>(moduleGuid);
    AccessControlInterfaceBase configuration;
    try
    {
        configuration = module.GetAccessControlInterface();
    }
    catch (SdkException ex) when (ex.ErrorCode == SdkError.InvalidOperation)
    {
        continue;
    }

    if (configuration is AccessControlInterfaceParentBase controller)
    {
        int channel = controller.Channel;
    }
}

To apply changes to an existing interface configuration, pass the modified configuration to InterfaceModule.UpdateAccessControlInterface(). Use the construction APIs described earlier to add interfaces to a unit.

Input device settings

InterfaceModule.Devices contains the GUIDs of the devices on a board. An InputDevice provides its configuration through InputDeviceSettings. The returned settings type depends on the access control unit.

Each read of InputDeviceSettings returns a new settings object. Changes to that object take effect through InputDevice.Update(settings). Retrieve the settings once and pass the modified instance to Update to preserve your changes and the other retrieved settings.

Mercury contact modes

For Mercury inputs that provide SMCInputDeviceSettings, InputContactType combines the normal contact position and supervision mode. SMCInputDeviceSettings is in Genetec.Sdk.Entities.Devices, and InputContactType is in Genetec.Sdk.

Contact mode	InputContactType value
Normally open, not supervised	NormallyOpenNotSupervised
Normally closed, not supervised	NormallyClosedNotSupervised
Normally open, supervised	NormallyOpenSupervised
Normally closed, supervised	NormallyClosedSupervised
Custom supervision profile 1-4	Custom1, Custom2, Custom3, Custom4

NormallyOpen and Supervised are separate properties for other input devices represented by SMCInputDeviceSettings. The Supervised property uses ESupervisedInput, which contains E_STATE_NONE, E_STATE_3STATE, and E_STATE_4STATE. For Mercury contact modes, use InputContactType. For controller supervision profiles, see Custom supervised inputs.

To change a Mercury input's contact mode:

1. Retrieve the input's SMCInputDeviceSettings.
2. Set InputContactType to the required mode.
3. Pass the modified settings to InputDevice.Update.

In this example, inputGuid identifies a writable Mercury input that provides SMCInputDeviceSettings, and engine is connected to Security Center. The input is configured as normally closed and supervised.

var input = engine.GetEntity<InputDevice>(inputGuid);
var settings = (SMCInputDeviceSettings)input.InputDeviceSettings;
settings.InputContactType = InputContactType.NormallyClosedSupervised;
input.Update(settings);

SMCInputDeviceSettings also represents inputs without Mercury contact-mode support. Setting InputContactType on those inputs raises SdkException with SdkError.CannotSetProperty.

Custom supervised inputs

Parent interface classes derived from AccessControlInterfaceParentBase expose a CustomSupervisedInputs collection. Each entry is an AccessControlInterfaceCustomSupervisedInput describing a custom-supervised input's voltage thresholds and resistor configuration:

• NormalLow, NormalHigh: Integer values defining the analog range for the normal state.
• ActiveLow, ActiveHigh: Integer values defining the analog range for the active state.
• ADLimitRow: An AccessControlInterfaceADLimitRow value identifying the resistor-limit row used by the supervision profile.

Custom supervised inputs map non-standard analog levels to the system's supervised-input states: normal, active, trouble, cut, and short.

See also

• About access control: The access control hub.
• Enrolling a unit: Standalone procedure for adding a new unit.
• About doors, areas, elevators, and access points: The location entities and their per-access-point wiring.
• Door templates: Reusable door configuration projected across many doors.
• Maps: Placing entities on operator maps.