Skip to content

Configure sensors & gates (Administrator setup)

This page is for administrators who configure sensor equipment and gate mappings for occupancy monitoring.

Overview

Sensor configuration involves: 1. Registering sensor devices 2. Associating sensors with Points of Interest 3. Mapping sensor gates to monitoring functions 4. Configuring detection settings

1) Registering sensors

Adding a new sensor

  1. Navigate to Occupancy → Sensor Equipment in Django Admin.
  2. Click Add Sensor Equipment.
  3. Configure core fields:
Field Description Example
Device ID Unique identifier (from manufacturer) "CAM-BEACH-001"
Sensor Type AI Camera or Infrared Counter "AI Camera"
Location Geographic coordinates Map pin placement
Is Active Enable/disable the sensor ✅
  1. Configure sensor-specific settings in the Config JSON field:
{
  "gates": [
    {"id": "gate1", "name": "Main Entrance", "direction": "bidirectional"},
    {"id": "gate2", "name": "Side Exit", "direction": "exit"}
  ],
  "detection_zone": "polygon coordinates",
  "min_confidence": 0.8
}

Sensor types

AI Camera - Multiple detection gates (zones) - Object type classification (person, car, bus, etc.) - Direction detection - Higher accuracy but more complex setup

Infrared Counter - Simple beam-break counting - Entry/exit detection - Lower cost, simpler setup - No object classification

2) Equipment module integration

Linking sensors to equipment records

If the Equipment module is enabled, you can link sensors for full asset management:

  1. In the sensor record, find the Equipment integration section.
  2. Enable Sync with Equipment.
  3. Select or create the linked Equipment record.

Benefits: - Maintenance tracking for sensors - Warranty management - Cost allocation - Unified asset inventory

Soft dependency behavior

  • If Equipment module is disabled, sensors work standalone
  • The integration fields are hidden or disabled
  • No impact on core occupancy functionality

3) Gate mapping configuration

Understanding gates

Gates are detection zones within a sensor: - AI cameras may have multiple gates (different areas of the frame) - Each gate can serve different monitoring purposes - Gates are mapped to POIs to define what they measure

Creating gate mappings

  1. First create a POI-Sensor association:
  2. Navigate to Occupancy → POI Sensors

  3. Link the sensor to a Point of Interest

  4. Then create gate mappings:

  5. Navigate to Occupancy → Gate Mappings

  6. Click Add Gate Mapping

  7. Configure the mapping:

Field Description
POI Sensor Which POI-sensor association
Gate ID Reference to gate in sensor config
Gate Function What this gate monitors (see below)
Tracked Object Types Array of object types to count
Geometry Optional geographic representation
Is Active Enable/disable this mapping

Gate functions explained

Function Purpose Use cases
Entry Count entries only Single-direction entrance gates
Exit Count exits only Single-direction exit gates
Entry/Exit Bidirectional counting Main entrances that handle both
Presence Real-time in-frame count Viewpoints, small plazas
Flow Traffic throughput Roads, walkways

Tracked object types

Configure which objects each gate should count:

["person", "car", "bus", "motorcycle", "bicycle"]
  • For parking: ["car", "motorcycle", "bus"]
  • For beaches/trails: ["person", "bicycle"]
  • For roads: ["car", "bus", "motorcycle", "bicycle"]

4) Multi-POI sensor configuration

One sensor can monitor multiple POIs using different gates:

Example: Camera at intersection - Gate 1 → Parking lot entrance (Entry function) - Gate 2 → Parking lot exit (Exit function)
- Gate 3 → Plaza entrance (Entry for different POI)

Setting up multi-POI

  1. Create multiple POI-Sensor associations (same sensor, different POIs)
  2. Map specific gates to each POI
  3. Ensure gate IDs match the sensor's configuration

5) Sensor configuration JSON

The sensor's config field stores device-specific settings:

AI Camera example

{
  "manufacturer": "SensorCorp",
  "model": "AI-CAM-3000",
  "firmware": "2.1.5",
  "gates": [
    {
      "id": "gate_main",
      "name": "Main Entrance",
      "detection_line": [[100, 200], [400, 200]],
      "direction": "bidirectional"
    },
    {
      "id": "gate_side",
      "name": "Side Exit",
      "detection_line": [[500, 150], [500, 350]],
      "direction": "outbound"
    }
  ],
  "detection_settings": {
    "min_confidence": 0.85,
    "tracking_algorithm": "sort",
    "frame_skip": 2
  }
}

Infrared counter example

{
  "manufacturer": "CounterTech",
  "model": "IR-DualBeam",
  "beam_height_cm": 100,
  "sensitivity": "high",
  "direction_detection": true
}

6) Testing configuration

After configuration:

  1. Verify sensor is reporting:
  2. Check last_seen field updates

  3. View recent readings in Sensor Readings

  4. Validate gate mappings:

  5. Confirm correct POI is receiving data
  6. Check object types are being detected

  7. Verify direction is correct (entry vs exit)

  8. Test occupancy calculation:

  9. Check POI shows reasonable occupancy
  10. Verify capacity percentage if configured
  11. Confirm no negative values

Best practices

Device ID conventions

  • Use meaningful, hierarchical IDs
  • Include location hints: "CAM-BEACHNORTH-001"
  • Keep consistent across your deployment

Configuration documentation

  • Document gate purposes in config JSON
  • Keep firmware versions updated
  • Note any special detection settings

Change management

  • Test configuration changes during low-traffic periods
  • Keep backups of working configurations
  • Document changes in sensor notes

Behind the scenes (grounded in code)

  • Sensor model: apps/occupancy/models.py → SensorEquipment
  • POI association: apps/occupancy/models.py → POISensor
  • Gate mapping: apps/occupancy/models.py → GateMapping
  • Equipment integration: GenericForeignKey with soft dependency check
  • Config storage: JSONField for flexible device configuration