Home Assistant

Home Assistant Integration

Meridian VMS ships a native Home Assistant integration that turns your VMS into a first-class smart-home camera platform. Install it via HACS and every camera, detection event, and license plate read is available in Home Assistant for dashboards and automations.

Features

Feature	Description
Camera entities	Live RTSP streams and snapshots for every camera
Motion sensors	Real-time binary sensors tracking motion per camera
Zone occupancy	Per-detection-zone occupancy sensors
AI detection events	Event entities when objects are detected
LPR events	Event entities with plate numbers
Detection thumbnails	Image entities showing the last detection snapshot
Switches	Toggle detection and recording on/off per camera
Dashboard sensors	Global VMS statistics
Media browser	Browse cameras, dates, and events with thumbnails
Services	Export clips, acknowledge alarms, PTZ control
Custom Lovelace cards	Status bar, camera wall, event feed
MQTT auto-discovery	Automatic entity creation via MQTT

---

Installation

From HACS (Recommended)

1. Open HACS in Home Assistant.
2. Go to Integrations and click +.
3. Search for Meridian VMS and install.
4. Restart Home Assistant.
5. Go to Settings > Devices & Services > Add Integration.
6. Search for Meridian and enter your VMS URL and credentials.

Manual Installation

1. Copy custom_components/meridian/ to your HA config/custom_components/ directory.
2. Restart Home Assistant.
3. Add the integration via Settings > Devices & Services.

Lovelace Cards

The custom cards ship as a JavaScript bundle:

1. Download the latest meridian-cards.js from the integration release.
2. Copy meridian-cards.js to your HA config/www/ directory.
3. Go to Settings > Dashboards > Resources and add /local/meridian-cards.js as a JavaScript module.

Cache busting

When updating the cards JS file, append a version parameter to the resource URL (e.g., /local/meridian-cards.js?v=2) to force browsers to load the new version.

---

Configuration

When adding the integration:

Field	Description
URL	Base URL of your management server (e.g., http://192.168.1.50)
Username	A Meridian VMS user account with API access
Password	Account password
Verify SSL	Enable if using a trusted HTTPS certificate

The integration authenticates and refreshes sessions automatically.

---

Data Coordinators

The integration uses 5 coordinators to poll the VMS API at different intervals:

Coordinator	Interval	Data
Camera	30s	Camera list, server RTSP URLs, detection zones (5-min cache for zones)
Event	10s	Detection events grouped by camera (last 5 minutes)
Motion	10s	Raw motion activity per camera (last 30 seconds)
LPR	10s	License plate events grouped by camera
Dashboard	60s	Global stats (camera count, events today, servers online)

Each coordinator runs independently. Failure in one coordinator does not affect others.

---

Entity Platforms (6)

Every camera in the VMS creates a device in Home Assistant with the following entities:

Camera

Live RTSP stream via MediaMTX and on-demand JPEG snapshots.

• Entity: camera.{name}
• Stream: rtsp://{recorder_ip}:8554/{camera_id}
• Attributes: status, recording_enabled, detection_enabled, resolution, fps

Binary Sensor — Motion

Real-time motion detection. Polls every 10 seconds with a 30-second lookback window.

• Entity: binary_sensor.{name}_motion
• Device class: Motion

Binary Sensor — Zone Occupancy

One sensor per configured detection zone. Activates when AI detections occur within the zone.

• Entity: binary_sensor.{name}_{zone_name}
• Device class: Occupancy
• Attributes: zone_id, zone_name, last_event_type, confidence

Event — AI Detection

Fires when the AI detects an object on a camera.

• Entity: event.{name}_detection
• Event types: person, car, truck, bus, motorcycle, bicycle, dog, cat, bird, detection
• Event data: camera, camera_id, event_id, confidence, timestamp, zone_id, count

Event — License Plate

Fires when a license plate is read.

• Entity: event.{name}_license_plate
• Event type: plate_detected
• Event data: plate, camera, camera_id, confidence, det_confidence, vehicle_class, timestamp

Image — Last Detection

Thumbnail of the most recent AI detection on a camera.

• Entity: image.{name}_last_event
• Attributes: event_type, confidence, detection_time, source, event_id

Sensor — Last Detection

Text sensor showing the type and time of the last detection.

• Entity: sensor.{name}_last_detection
• Attributes: timestamp, event_type, source, confidence

Switch — Detection / Recording

Toggle detection and recording per camera.

• Entities: switch.{name}_detection, switch.{name}_recording
• Turning off recording stops the recording process; the camera remains available for live view
• Turning off detection stops AI inference for that camera

Dashboard Sensors

Global VMS statistics:

Entity	Value
sensor.meridian_vms_total_cameras	Total camera count
sensor.meridian_vms_cameras_online	Cameras currently online
sensor.meridian_vms_events_today	Detection events in the last 24 hours
sensor.meridian_vms_servers_online	Recording servers online

---

MQTT Auto-Discovery

The integration supports MQTT-based auto-discovery for automatic entity creation:

1. Enable MQTT on your Meridian VMS management server.
2. Configure the same MQTT broker in both the VMS and Home Assistant.
3. The VMS publishes discovery messages to homeassistant/ topics.
4. Entities are created automatically without manual configuration.

Discovery messages include device information, entity configuration, and state topics. Entity states are updated via MQTT for lower latency than REST polling.

---

HTTP Proxy Views

The integration registers authenticated HTTP proxy views in Home Assistant for serving media:

Path	Description
/api/meridian/thumbnail/{event_id}	Event thumbnail JPEG (proxied from VMS)
/api/meridian/clip/{camera_id}?from=&to=	Streaming clip proxy (MP4)
/api/meridian/snapshot/{camera_id}	Camera snapshot JPEG

These views use Home Assistant’s authentication, so they are safe to use in dashboards and notifications without exposing VMS credentials.

---

Media Browser

The integration registers a media source for browsing detection events from the Home Assistant Media panel.

Meridian VMS
  +-- Camera Name (with live snapshot thumbnail)
       +-- Today
       +-- Yesterday
       +-- 2026-04-20
            +-- 14:32 - Person (92%)     [playable clip]
            +-- 14:45 - Car (87%)        [playable clip]
            +-- 15:01 - Truck (91%)      [playable clip]

Each event shows a thumbnail and can be played as an MP4 clip via the clip proxy. The last 7 days are browseable.

---

Services

meridian.export_clip

Export a video clip for a camera time range.

Parameter	Type	Description
camera_id	string	Camera UUID
start	string	Start time (ISO 8601)
end	string	End time (ISO 8601)

Fires a meridian_clip_exported event with the download URL when complete.

meridian.acknowledge_alarm

Acknowledge an open alarm.

Parameter	Type	Description
alarm_id	string	Alarm UUID

meridian.ptz_command

Send a PTZ command to a camera.

Parameter	Type	Description
camera_id	string	Camera UUID
command	string	pan_left, pan_right, tilt_up, tilt_down, zoom_in, zoom_out, stop

---

Custom Lovelace Cards

Three custom cards for surveillance dashboards:

meridian-status-bar

Compact overview bar showing cameras online, events today, and server status.

type: custom:meridian-status-bar

meridian-camera-wall

Responsive camera grid with live snapshots, motion indicators, and status dots.

type: custom:meridian-camera-wall
title: Cameras
columns: 3
refresh: 10

Option	Default	Description
title	Cameras	Card title
columns	3	Grid columns
refresh	10	Snapshot refresh interval (seconds)
cameras	all	Optional list of camera entity IDs to display

meridian-event-feed

Real-time scrollable feed of AI detection events with thumbnails, confidence bars, and relative timestamps.

type: custom:meridian-event-feed
title: Detection Feed
max_items: 25

Option	Default	Description
title	Detection Feed	Card title
max_items	20	Maximum events to display

---

Automation Examples

Gate automation with LPR

Open a gate when a whitelisted license plate is detected:

automation:
  - alias: "Open gate for known plates"
    trigger:
      - platform: state
        entity_id: event.gate_camera_license_plate
        attribute: event_type
        to: "plate_detected"
    condition:
      - condition: template
        value_template: >
          {{ trigger.to_state.attributes.plate in
             ['ABC 123', 'XYZ 456', 'DEF 789'] }}
    action:
      - service: switch.turn_on
        entity_id: switch.gate_relay

Dynamic whitelist

Use an input_text helper to manage your plate whitelist from the HA UI instead of hardcoding plates in YAML.

Person detection notification with thumbnail

automation:
  - alias: "Person detected notification"
    trigger:
      - platform: state
        entity_id: event.front_door_detection
        attribute: event_type
        to: "person"
    action:
      - service: notify.mobile_app
        data:
          title: "Person Detected"
          message: "{{ trigger.to_state.attributes.camera }} at {{ now().strftime('%H:%M') }}"
          data:
            image: "/api/meridian/thumbnail/{{ trigger.to_state.attributes.event_id }}"

Toggle detection by schedule

automation:
  - alias: "Disable indoor detection during the day"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: switch.turn_off
        entity_id:
          - switch.kitchen_detection
          - switch.living_room_detection

  - alias: "Enable indoor detection at night"
    trigger:
      - platform: time
        at: "22:00:00"
    action:
      - service: switch.turn_on
        entity_id:
          - switch.kitchen_detection
          - switch.living_room_detection

Alarm acknowledgement

Automatically acknowledge low-priority alarms when motion stops:

automation:
  - alias: "Auto-ack low priority alarms"
    trigger:
      - platform: state
        entity_id: binary_sensor.storage_room_motion
        to: "off"
        for: "00:05:00"
    action:
      - service: meridian.acknowledge_alarm
        data:
          alarm_id: "{{ states.sensor.storage_room_last_alarm_id.state }}"

---

Network Requirements

Destination	Port	Purpose
Management server	80 or 8000	REST API (cameras, events, clips, thumbnails)
Recording server(s)	8554	RTSP streams via MediaMTX (live camera view)

No inbound connections from the VMS to Home Assistant are required.

---

Troubleshooting

Cameras show “unavailable” : Verify the VMS management server is reachable: curl http://{vms_ip}/api/dashboard. Check integration logs in Settings > System > Logs, filter for meridian.

Camera snapshots fail (500 error) : The management server proxies snapshots from the recording server. If the recorder is down or the stream is stalled, snapshots fail. Snapshots are cached for 5 seconds.

Motion sensors always off : Verify motion detection is enabled in VMS settings. The motion coordinator polls every 10 seconds with a 30-second lookback — expect 10-40 second latency.

LPR events not firing : The integration uses a dedicated LPR coordinator requesting type=license_plate. Verify LPR is running by checking for license_plate events in the VMS Events page.

Custom cards not loading : Verify meridian-cards.js is at config/www/. Check the resource URL in Settings > Dashboards > Resources includes a cache-busting parameter. Open DevTools console and look for MERIDIAN CARDS 1.0.0.

High CPU from frequent polling : Reduce coordinator update intervals in the integration options. The default intervals (10-60s) are balanced for responsiveness vs. resource usage.