IntrusionDetector¶

Overview¶

Generic intrusion detection sensor covering all types: PIR motion, magnetic contact, glass break, shock, vibration, curtain, dual-tech. The adapter selects appropriate actions based on the physical sensor type.

Added in: PQ Framework 2.1
Namespace: Pq.Adapters.Framework

When to Use¶

PIR motion detectors
Magnetic contact sensors (door/window)
Glass break detectors
Shock/vibration sensors
Curtain/beam sensors
Dual-technology sensors
Any intrusion detection sensor

States¶

Detection Lifecycle¶

State	Status id	Description
`Clear`	`detection.clear` (hidden)	No detection condition present
`Prealarm`	`intrusion.prealarm`	Threshold exceeded, approaching alarm
`Alarm`	`intrusion.alarm`	Full alarm condition triggered
`Fault`	`supervision.fault`	Sensor malfunction detected
`Trouble`	`supervision.trouble`	Detector malfunction or fault
`Masked`	`intrusion.masked`	Sensor masked or obstructed
`TestCalibrating`	`supervision.test.calibrating`	Sensor calibration in progress
`Test`	`supervision.test`	Walk test or diagnostic mode active

Clear is the hidden default state: SetClear(ct) publishes no status string, so a quiet detector reports the function as cleared.

Motion-Specific States¶

State	Status id	Description
`MotionActive`	`detection.motion.active`	Active motion sensed
`MotionIdle`	`detection.motion.idle`	Motion stopped, settling period

Contact-Specific States¶

State	Status id	Description
`Open`	`position.open`	Door/barrier is in open position
`Closed`	`position.closed`	Door/barrier is in closed position

Intrusion Overrides¶

State	Status id	Description
`Bypassed`	`intrusion.bypassed`	Excluded from security monitoring
`Tamper`	`intrusion.tamper`	Device enclosure opened or tampered

Actions¶

Alarm Events¶

Alarm(timestamp)

Description: Intrusion alarm triggered
Target State: Alarm
Events: pq.event.intrusion.alarm (Critical)
Usage: Sensor detected intrusion condition

PreAlarm(timestamp)

Description: Pre-alarm condition (threshold warning)
Target State: Prealarm
Events: pq.event.intrusion.prealarm (Warn)
Usage: Entry delay zone triggered

Cleared(timestamp)

Description: Alarm condition cleared, return to normal
Target State: Clear
Events: pq.event.intrusion.cleared (Info)

Tamper Events¶

Tamper(timestamp)

Description: Tamper detected (enclosure opened)
Target State: Tamper
Events: pq.event.intrusion.tamper (Critical)

TamperRestored(timestamp)

Description: Tamper condition restored
Target State: Clear
Events: pq.event.intrusion.tamper.cleared (Info)

Fault Events¶

Fault(timestamp)

Description: Sensor fault detected
Target State: Fault
Events: pq.event.supervision.fault (Warn)

FaultRestored(timestamp)

Description: Sensor fault restored
Target State: Clear
Events: pq.event.technical.fault.cleared (Info)

Masked/Blocked Events¶

Masked(timestamp)

Description: Sensor masked or obstructed
Target State: Masked

MaskedRestored(timestamp)

Description: Masking condition cleared
Target State: Clear

Bypass Events¶

Bypassed(timestamp, personId, zoneName, reason?) (custom)

Description: Detector bypassed by operator
Target State: Bypassed
Events: pq.event.intrusion.bypassed (Info)
Parameters:
personId (Guid) - Person who performed bypass
zoneName (string) - Name of zone being bypassed
reason (string?) - Optional reason for bypass
Usage: Operator manually excluded detector from monitoring

BypassCancelled(timestamp)

Description: Bypass cancelled, return to normal monitoring
Target State: Clear
Events: pq.event.intrusion.bypassed.cleared (Info)

BypassedRemote(timestamp)

Description: Detector bypassed remotely by operator
Target State: Bypassed
Events: pq.event.intrusion.bypassed.remote (Info)

BypassCancelledRemote(timestamp)

Description: Bypass cancelled remotely, return to normal monitoring
Target State: Clear
Events: pq.event.intrusion.bypassed.cleared.remote (Info)

Motion Detection (PIR, Dual-Tech)¶

MotionDetected(timestamp)

Description: Motion detected by sensor
Target State: MotionActive
Events: pq.event.intrusion.motion.detected (Info)

MotionCleared(timestamp)

Description: Motion cleared
Target State: MotionIdle
Events: pq.event.intrusion.motion.cleared (Info)

Contact (Magnetic Contacts)¶

ContactOpen(timestamp)

Description: Contact opened (door/window opened)
Target State: Open
Events: pq.event.intrusion.contact.open (Warn)

ContactClosed(timestamp)

Description: Contact closed (door/window closed)
Target State: Closed
Events: pq.event.intrusion.contact.closed (Info)

Special Events¶

ForcedEntry(timestamp, personId?, zoneId?) (custom)

Description: Forced entry detected
Events: pq.event.intrusion.entry.forced (Critical)
Parameters:
personId (Guid?) - Optional person identifier
zoneId (Guid?) - Optional zone identifier
Usage: Contact opened while partition armed

TestModeActivated(timestamp)

Description: Walk test mode activated
Target State: Test
Events: pq.event.intrusion.testing.started (Info)

TestModeDeactivated(timestamp)

Description: Walk test mode deactivated
Target State: Clear
Events: pq.event.intrusion.testing.completed (Info)

Life-Safety Events (panic / medical / hold-up)¶

Intrusion and life-safety share the security domain, so panic, medical, and hold-up calls are actions on this function. They publish the pq.event.safety.panic.* family (distinct from burglary intrusion.*, because they trigger a different operational response — ambulance/police dispatch). Fire is the exception: it has its own FireDetector function.

Panic(timestamp)

Description: Panic / hold-up alarm raised
Target State: Alarm
Events: pq.event.safety.panic (Critical)

Medical(timestamp)

Description: Medical-call alarm raised
Target State: Alarm
Events: pq.event.safety.panic.medical (Critical)

Police(timestamp)

Description: Police / duress hold-up alarm raised
Target State: Alarm
Events: pq.event.safety.panic.police (Critical)

PanicCleared(timestamp)

Description: Panic / medical condition cleared
Target State: Clear
Events: pq.event.safety.panic.cleared (Info)

Properties¶

None. All configuration is adapter-specific. Define properties in adapter-registration.yaml if needed (e.g., sensitivity, supervision_type).

YAML Example¶

device_types:
  - type_id: PIRMotionDetector
    name: "PIR Motion Detector"
    functions:
      IntrusionDetector:
    properties:
      sensitivity:
        type: "int"
        default: 50
        range: [0, 100]
        description: "Sensor sensitivity (0=min, 100=max)"
      supervision_type:
        type: "string"
        default: "eol"
        description: "Supervision: none, eol, deol, digital"

  - type_id: DoorContact
    name: "Magnetic Door Contact"
    functions:
      IntrusionDetector:
    properties:
      supervision_type:
        type: "string"
        default: "eol"

Code Usage¶

public class PIRDetectorThing : Thing
{
    public IntrusionDetectorFunction Detector { get; }

    protected override async Task HandleDeviceEvent(DetectorEvent evt, CancellationToken ct)
    {
        switch (evt.Type)
        {
            case DetectorEventType.MotionDetected:
                await Detector.MotionDetected(evt.Timestamp);
                break;

            case DetectorEventType.MotionCleared:
                await Detector.MotionCleared(evt.Timestamp);
                break;

            case DetectorEventType.Tamper:
                await Detector.Tamper(evt.Timestamp);
                break;

            case DetectorEventType.Fault:
                await Detector.Fault(evt.Timestamp);
                break;
        }
    }

    public async Task HandleBypass(Intrusion.Bypass cmd, CancellationToken ct)
    {
        await Detector.Bypassed(
            DeviceTimestamp.UtcNow,
            cmd.OperatorIdentity,
            zoneName: this.Name,
            reason: "Manual bypass"
        );
    }
}

Notes¶

Generic Design: IntrusionDetector is intentionally generic to support all sensor types in one function
Adapter Chooses Actions: PIR sensors call MotionDetected(), contacts call ContactOpen(), glass break calls Alarm()
Bypass Ownership: Bypass is on the detector, not the partition. Partition reflects aggregate bypass state if needed.
Fire Detection: Fire is a separate FireDetector function with fire-specific events (pq.event.fire.*); panic/medical/hold-up, however, live here as life-safety actions.