# 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.

{% hint style="info" %}
**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.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

{% hint style="success" %}
**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.
{% endhint %}

***

## 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`

```json
{
  "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:**

```json
{
  "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

{% hint style="info" %}
For general calibration information, refer to the [Calibration Overview](https://docs.butlr.io/historical-occupancy/reporting-api-overview/calibration-overview) documentation.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.butlr.io/historical-occupancy/reporting-api-overview/pir-zeroing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.