Integrations

What is a device adapter?

A device adapter is an AOP Module that connects a third-party system to WinGuard (AOP).

A device adapter does:

• Connect to the third-party system and monitor the connection.
• Keep current states and events of objects in sync with the third-party system.
• Control objects (e.g., enable/disable an output, open/close a door).

A device adapter does not:

• Configure the third-party system (e.g., add/remove/edit objects or change their configuration; add/remove/edit users or accounts).
• Render custom UI.
• Implement security-critical functionality — the security system must keep working independently without WinGuard or the device adapter.
• Implement additional features on top of what the third-party system provides.

Legacy terms: The terms “SST” (from the German Schnittstelle = interface) and “interface module” refer to the same concept. These terms are now considered outdated and are replaced by “device adapter”.

→ See Device Integration Concepts and What is the difference between device adapters and other Extensions? for more details.

What is the difference between device adapters and other Extensions?

A device adapter is a specific type of AOP Extension with a well-defined role: it maps external real-world IoT objects (sensors, cameras, access readers, etc.) into WinGuard’s generic EXT Object model. It must implement the adapter Skill.

Other Extension types serve different purposes and implement different (or no) functional Skills.

The SDK choice also differs: Device adapters use the SST SDK (C++ or .NET), while other Extensions typically use the .NET AOP SDK, JS AOP SDK, or the raw IPC API directly.

→ See What are the differences between the SDKs, and what is the SST SDK? for more details.

What is the difference to legacy X4 SSTs?

AOP device adapters differ fundamentally from the legacy X4 SST model:

Aspect	X4 SST	AOP device adapter
Delivery format	DLL, loaded in-process by WinGuard	Standalone EXE, connects via IPC
Communication	Direct function calls via C++ interfaces	WebSocket-based IPC (JSON)
Object model	Direct use of WinGuard Datapoints and alarms	Generic EXT Object model with XML definitions
Deployment	Must be installed on every WinGuard station	Only required on stations where it actually runs; can also run remotely
UI	Could include its own Automatic Data Supply, settings cards, log filters	No UI in the Module, all handled generically by WinGuard
Versioning	Binary-compatible, tied to WinGuard build	Independently versioned; no binary compatibility required
Threading/IO	Implemented individually per Module	Handled uniformly by the SDK IO framework

The move to AOP means developers no longer need deep WinGuard knowledge for Datapoint configuration. The generic object model and XML-based mapping handle that layer automatically.

Which domains exist in the area of device integration?

The AOP device integration model is designed to be domain-agnostic, but there are established conventions for modeling common device categories. Advancis Security & Safety Ontology defines typical object types, properties, states, events, and commands for the most common domains.

The document includes a domain browser that functions like an interactive viewer and offers various views for navigation.

→ See Advancis Security & Safety Ontology for the full reference.

Are there any development guidelines or best practices for device adapters?

Yes. The Device Adapter Specification is the authoritative development guide for building device adapters.

The spec is organized into two layers:

General guidelines — cross-domain rules that apply to every device adapter, regardless of the integrated system. Topics include Object hierarchy modeling, how to use Properties, States, and Events, connection handling and reconnect behavior, state and event synchronization, automatic data supply, logging, internal fault reporting, time zone handling, and Manifest compatibility.

Domain-specific guidelines — additional requirements and Object model specifications for particular device categories such as Access Control, Fire Alarm, Intrusion Detection, Video Management, and others. Each domain section defines the expected Object types, their States, Events, and Operations, as well as domain-specific behavioral rules (e.g., alarm delay handling for fire systems, or anti-passback forgive for access control).

→ See Device Adapter Specification for the full reference.

What is Automatic Data Supply (ADS), and do I need to implement it?

Automatic Data Supply (ADS) is the mechanism by which WinGuard queries a device adapter for its current list of EXT Objects and automatically creates the corresponding Datapoints in the WinGuard project. Without ADS, a WinGuard administrator must add every Datapoint manually.

To support ADS, the adapter must implement the Object query interface, declared via the ap Trait in the Manifest. When triggered, WinGuard calls the adapter’s query function, receives the full Object list, and uses the App XML naming schemes to generate Datapoint codes and names automatically.

ADS is not strictly required; an adapter functions without it. However, it is strongly recommended for any adapter that manages more than a handful of Objects, as it greatly simplifies initial system configuration.

→ See Automatic Data Supply settings and Module Development for implementation details.

How do I report the connection state of my adapter to WinGuard?

Every EXT Object has a built-in @connected State that signals whether the Object is currently functional:

• @connected = true — the Object is reachable and its States and Events are valid.
• @connected = false (default) — the Object is offline, unreachable, or not yet synchronized.

For connection faults at the system boundary (e.g., the adapter has lost its TCP connection to the third-party system), the convention is to set the @connectionfault Event on the affected Node Object and set @connected = false on all Objects under it. The @connectionfault Event is special: it is the only Event WinGuard evaluates even when @connected = false.

When the connection is restored, set @connected = true again and clear the @connectionfault Event. The SDKs provide dedicated helpers for managing these states.

→ See Processes: Object Connectivity for the full connection state model.

What is the difference between the Module XML and the App XML?

Both files describe parts of the Object model but serve different audiences:

Module XML defines the structural aspects: which Object types exist, their Properties, States, Events, and Operations. This file is the adapter developer’s deliverable and should never be modified by end users.The IDs of the Objects, States, Events, etc. are defined in the Module XML and referenced in the remaining XML files.

App XML defines the application-specific behavior: how WinGuard maps Object types to Datapoints, which States and Events correspond to WinGuard App States, and how Events are handled. This file is specifically designed to be customized by experienced WinGuard administrators. It lives in the WinGuard project directory and is automatically copied there from the adapter package on first start. It will never be overwritten by subsequent adapter updates.

Separating the two is strongly recommended to ensure clear boundaries between structural definitions and application-specific behavior.

→ See App XML and Module XML for the full reference.

Can an EXT Object have multiple active States and Events simultaneously?

States: Each State is a named value updated in place. An Object has exactly one current value per State at any given time (e.g., Locked = true or Temperature = 22.5).

Clearable Events:: Yes. Multiple instances of the same Event type can be active on a single Object simultaneously, each identified by a unique Event key. For example, a camera raising separate motion alarms for two independently tracked objects may hold two active MotionAlarm Event instances at the same time, one per Event key.

If the third-party system does not support multiple simultaneous instances of an Event type, use the Event type name itself as the Event key. The URL address part can then be omitted.

→ See Device Integration Concepts: States and Events for details on Event keys and instances.

How can I tell whether an ExportImage Operation was triggered for live or archive?

When WinGuard invokes the ExportImage Operation on a device adapter, the Operation always includes the URL of the associated Activity. By inspecting the Time Property of that Activity, you can distinguish the two cases:

• Live export: The Activity’s Time Property is null.
• Archive export: The Activity’s Time Property contains the timestamp of the requested archived image.

This works because ExportImage is an Activity-level Operation: The Activity is always present in its context. There is no ExportImage for Objects (Datapoints) directly, so this pattern is reliable.

Note: The only export that does not require an active Activity is DirectVideoExport for the media archive.

→ See ExportImage and Activities for details on the Activity model and its Time Property.