Realtime Calibration

The PIR Zeroing (Realtime Calibration) feature enhances the Butlr Calibration System by automatically detecting when rooms are empty using Passive Infrared (PIR) motion sensors. This automated approach generates zero-occupancy calibration points without manual intervention, significantly improving the accuracy of occupancy tracking by correcting sensor drift more frequently throughout the day.

Overview

PIR Zeroing leverages the motion detection capabilities of PIR sensors to identify periods when a room is unoccupied. When all PIR-enabled sensors in a room detect no motion for a configurable duration, the system automatically creates a calibration point marking that time as zero occupancy. This complements existing calibration methods by providing additional correction points between manual counts and operational day boundaries.

Automatic Activation: PIR Zeroing works seamlessly with the calibration system when enabled. Simply set calibrated: "true" in your API requests and configure PIR settings for your rooms and sensors.

Sensor Mode Requirement: PIR Zeroing only works with sensors in "presence" mode. Sensors in "traffic" mode are not used to generate no-motion events for PIR zeroing.

Key Benefits

  1. Automated Drift Correction: No manual counts needed for zero-occupancy calibration

  2. Increased Accuracy: More frequent calibration points throughout the day

  3. Flexible Configuration: Customizable thresholds and time windows per room

  4. Graceful Degradation: System continues working if PIR data is unavailable

Important Note: PIR Zeroing requires both room-level and sensor-level configuration. All eligible sensors must agree on absence for calibration points to be generated.

How PIR Zeroing Works

Motion Detection Process

PIR sensors continuously monitor for human presence by detecting infrared radiation changes. The system analyzes this data to identify absence periods:

  1. Sensor Monitoring: PIR sensors report confidence values (0.0 to 1.0) indicating motion detection

  2. Absence Detection: Values below the configured threshold indicate no human presence

  3. All-Sensor Agreement: All PIR-enabled sensors in a room must show absence simultaneously

  4. Duration Validation: Absence must persist for the configured time window

  5. Calibration Point Generation: System creates a zero-occupancy point at the start of the absence period

The system includes sophisticated logic to prevent incorrect zero-occupancy calibration:

Scenario: PIR sensors may incorrectly detect absence while people are still exiting the room.

Solution: The drift correction algorithm analyzes occupancy patterns after PIR zero points. If it detects exit events (negative occupancy changes) immediately following a PIR zero point, it recognizes this as a false positive and excludes that calibration point from processing.

Result: Only valid empty-room periods generate calibration points, maintaining data integrity.

Configuration

PIR Zeroing is configured through four GraphQL fields that control its behavior at both room and sensor levels.

Room-Level Configuration

pir_zero_enable (Boolean)

Controls whether PIR Zeroing is active for a specific room.

  • Type: Boolean

  • Default: false

  • Description: When true, the room will use PIR motion data to generate zero-occupancy calibration points

pir_zero_threshold (Float)

Sets the confidence threshold below which sensors indicate no human presence.

  • Type: Float (0.0 to 1.0)

  • Default: 0.05

  • Description: PIR sensor values below this threshold indicate absence. Lower values are more conservative.

pir_zero_window (Integer)

Defines how long all sensors must show absence before generating a calibration point.

  • Type: Integer (seconds)

  • Default: 300 (5 minutes)

  • Description: Minimum duration of continuous absence required. Longer windows reduce false positives.

Sensor-Level Configuration

pir_zero_enable (Boolean)

Controls whether a specific sensor participates in PIR Zeroing.

  • Type: Boolean

  • Default: true

  • Description: When false, this sensor will be excluded from PIR-based calibration calculations

API Usage Example

When PIR Zeroing is configured, it automatically enhances calibrated queries. Here's a complete example:

POST https://api.butlr.io/api/v3/reporting

{
  "window": {
    "every": "5m",
    "function": "median"
  },
  "filter": {
    "start": "2025-01-20T00:00:00Z",
    "stop": "2025-01-21T00:00:00Z",
    "measurements": ["traffic_room_occupancy"],
    "calibrated": "true",
    "rooms": {
      "eq": ["room_id"]
    }
  },
  "group_by": {
    "order": ["time"]
  },
  "includeCalibrationPoints": true
}

Response with PIR-generated calibration points:

{
  "data": [
    {
      "time": "2025-01-20T00:00:00Z",
      "value": 0,
      "room": "room_id"
    },
    // ... occupancy data ...
  ],
  "calibrationPoints": [
    {
      "timestamp": "2025-01-20T00:00:00Z",
      "occupancy": 0,
      "type": "operational_day_start"
    },
    {
      "timestamp": "2025-01-20T10:30:00Z",
      "occupancy": 0,
      "type": "pir_zero"  // PIR-generated calibration point
    },
    {
      "timestamp": "2025-01-20T14:15:00Z",
      "occupancy": 0,
      "type": "pir_zero"  // Another PIR-generated point
    },
    {
      "timestamp": "2025-01-21T00:00:00Z",
      "occupancy": 0,
      "type": "operational_day_end"
    }
  ]
}

Best Practices

Configuration Guidelines

  1. Start Conservative: Begin with default settings (threshold: 0.05, window: 300 seconds)

  2. Monitor Results: Use includeCalibrationPoints: true to verify PIR zero points are being generated

  3. Adjust Gradually: If too few points are generated, try:

    • Increasing threshold to 0.1 (less conservative)

    • Decreasing window to 180 seconds (3 minutes)

  4. Room-Specific Tuning: Different room types may need different settings:

    • Conference rooms: Shorter windows (180-300 seconds)

    • Open offices: Longer windows (600-900 seconds)

Sensor Placement

For optimal PIR Zeroing performance:

  • Ensure complete room coverage with PIR sensors

  • Avoid sensor blind spots near exits

  • Position sensors to detect all areas where people might be stationary

  • Test sensor coverage by walking through all room areas

Troubleshooting

No PIR calibration points generated:

  • Verify pir_zero_enable is true for both room and sensors

  • Check that sensors are in "presence" mode, not "traffic counting"

  • Confirm PIR sensors are detecting motion correctly

  • Review threshold and window settings

Too many false positives:

  • Increase the time window (e.g., from 300 to 600 seconds)

  • Decrease the threshold (e.g., from 0.05 to 0.02)

  • Check for sensor placement issues or environmental interference

Partial sensor agreement:

  • Ensure all sensors in the room have consistent PIR settings

  • Verify sensor coverage overlaps appropriately

  • Check for faulty sensors showing constant absence or presence

Technical Details

Processing Pipeline Integration

PIR Zeroing integrates seamlessly into the calibration processing pipeline:

  1. Room-Level Processing: Only applies to traffic_room_occupancy measurements

  2. Configuration Check: System verifies room has pir_zero_enable: true

  3. Sensor Filtering: Identifies sensors with pir_zero_enable: true and mode: "presence"

  4. Data Query: Retrieves PIR sensor data for the query time range

  5. Absence Analysis: Identifies periods where all sensors show values below threshold

  6. Point Generation: Creates calibration points with type: "pir_zero"

  7. Standard Processing: Continues with normal calibration pipeline

  8. Standard Processing: Continues with normal calibration pipeline

Calibration Point Types

When using includeCalibrationPoints: true, the API returns calibration points with the following types:

Type
Description
Source

user_provided

Explicitly provided via API request

Manual input

pir_zero

Generated from PIR sensor absence detection

Automatic

operational_day_end

End of operational day (historical days)

Automatic

Limitations and Considerations

Current Limitations

  1. Room-Level Only: PIR Zeroing only works with traffic_room_occupancy, not floor-level measurements

  2. Presence Mode Required: Sensors used to collect PIR data for zeroing must be in presence mode

  3. All-Sensor Agreement: All enabled sensors must agree on absence

  4. Historical Data: PIR Zeroing only affects data from when the sensors began collecting PIR data. This is configured by support independently of any other parameters discussed in this guide

Future Enhancements

Planned improvements include:

  • Machine learning-based threshold optimization

  • Cross-validation with other sensor types

  • Real-time calibration point generation

  • Advanced pattern recognition for improved accuracy

For general calibration information, refer to the Calibration Overview documentation.

PreviousCalibration OverviewNextFloor Occupancy

Last updated