Automations and arming
Automations turn events into actions: when a person is seen on the driveway at night, notify your phone and switch the garage camera to continuous recording. Arming decides whether alerts and automations run at all. This page covers both, how they relate to recording schedules, and how scripts can arm and disarm through the API.
Arming and disarming
Section titled “Arming and disarming”Aperture has one alarm switch with two states: armed and disarmed. A new install is armed, and it stays armed until something disarms it. There are no separate home, away or night modes.
What disarming changes:
| Armed | Disarmed | |
|---|---|---|
| Recording, motion, audio and object recognition | Run | Run |
| Events in Alarms and Playback | Created | Created |
| Notification rules, every channel | Deliver | Deliver nothing |
| Automations | Run | Don’t run |
| Notify on this device in the browser | Alerts | Alerts |
| Integrations › Webhooks | Sent | Sent |
| Home Assistant sensors, HomeKit motion sensors | Update | Update |
Disarming is for “we are home, stop alerting us”. It never stops recording.
Where to arm and disarm
Section titled “Where to arm and disarm”The web app has no arm button of its own. The switch is controlled from:
- Home Assistant. With the Home Assistant integration connected, Aperture’s NVR device has an Armed switch. Behind it are the MQTT topics
aperture/system/set/armed(sendONorOFF) andaperture/system/armed(the current state). - Apple Home. With HomeKit on, the bridge includes a security system. Any arm mode in the Home app (Home, Away, Night) arms Aperture; it then shows as Away. Off disarms.
- The API.
GET /api/v1/alarmreads the state,PUT /api/v1/alarmsets it. See below. - Extensions that were granted the
alarm:armpermission (see Extension permissions).
All of these change the same setting, and the others catch up: the Home app within about 5 seconds, the Home Assistant switch within about half a minute. A change made through the API is also written to the Activity Log.
Arm from a script
Section titled “Arm from a script”- Open Integrations › API Tokens and select Create token.
- Tick only Arm/disarm alarm (
alarm:arm) and create it. Copy the token (it starts withapt_); it is shown once. - Call the API with it:
# Disarmcurl -s -X PUT https://nvr.example.com/api/v1/alarm \ -H "Authorization: Bearer apt_…" \ -H "Content-Type: application/json" \ -d '{"armed": false}'
# Read the state: {"armed":true} or {"armed":false}curl -s -H "Authorization: Bearer apt_…" https://nvr.example.com/api/v1/alarmAperture has no timer for arming. To arm at night and disarm in the morning, use a Home Assistant automation on the Armed switch, or cron on any machine that can reach Aperture:
# /etc/cron.d/aperture-alarm (owned by root, mode 600: it holds the token)0 23 * * * root curl -fsS -X PUT -H "Authorization: Bearer apt_…" -H "Content-Type: application/json" -d '{"armed":true}' http://127.0.0.1:8971/api/v1/alarm0 7 * * * root curl -fsS -X PUT -H "Authorization: Bearer apt_…" -H "Content-Type: application/json" -d '{"armed":false}' http://127.0.0.1:8971/api/v1/alarmAny signed-in user can also arm and disarm through the API with their own session; a token needs the alarm:arm scope. See Scopes.
Automations
Section titled “Automations”An automation has a trigger (which events), conditions (time of day, weather) and one or more actions. Open Automations in the navigation (administrators only).
Create one
Section titled “Create one”- Select Create automation.
- Give it a Name.
- Under When — objects (any if none), pick the objects that should trigger it: person, car, truck, dog, cat, bicycle, package. Pick none to react to every event.
- Under On cameras (any if none), pick cameras, or none for all.
- Optionally set Time (Any, Day or Night), Only when raining, and a Cooldown in seconds.
- Under Then, choose an action and fill it in. Add action adds more; they all run.
- Select Save.
The list shows each automation’s trigger, actions, cameras and when it last fired, with an Enabled switch, a Run now button and a delete button. Click a row to edit it.
Triggers and conditions
Section titled “Triggers and conditions”| Part | What it does |
|---|---|
| Objects | The event must carry one of these labels from object recognition. With objects picked, plain motion never triggers it. Labels found in the first 1.5 seconds of a motion event are what it sees. Package deliveries and pick-ups carry package. |
| Cameras | The event must come from one of these cameras. |
| Event types | Motion, audio and package events all trigger an automation. Through the API, trigger.eventTypes (motion, audio, package) limits it. |
| Time | Day or Night by sunrise and sunset at your site. |
| Only when raining | Only when the recorded weather shows precipitation at that moment. |
| Cooldown | After firing, the automation waits this many seconds before it can fire again, whichever camera the next event comes from. 0 means every event. |
Time and rain need a site location under Settings › Environment (see Site and weather); without one they are ignored and the automation fires anyway.
An automation is checked once, when an event opens, and only while the system is armed.
Actions
Section titled “Actions”| Action | Fields | What it does |
|---|---|---|
| Notify | Your notification channels | Sends an alert through the chosen channels. The title is what was seen (“Person”, or “Motion” without objects), the text is the time, and the link opens Playback at the event. It carries no picture and no camera name; use a notification rule when you want those. |
| Webhook | A URL | POSTs the event as JSON (below). One attempt, 10-second timeout, not signed. For signed deliveries with retries, use Integrations › Webhooks (see Signed webhooks). |
| MQTT publish | Topic, payload | Publishes the payload, as written, to the topic on the broker of the Home Assistant integration (QoS 1, not retained). Nothing is sent while that connection is down. |
| Set record mode | Camera, mode | Switches a camera’s recording mode to never, motion, continuous or scheduled, at once. |
The webhook action sends:
{ "type": "automation", "ts": 1763215407000, "event": { "id": "3f9a1c2e7b8d4e6f9a0b1c2d3e4f5a6b", "cameraId": "b41e0c9a2f7d48e3a1c5d6e7f8091a2b", "eventType": "motion", "startTs": 1763215402000, "topLabel": "person" }, "link": "https://nvr.example.com/playback?camera=b41e0c9a2f7d48e3a1c5d6e7f8091a2b&t=1763215402000"}link is empty when APERTURE_PUBLIC_URL is not set; topLabel is empty when no object was recognised.
Run now
Section titled “Run now”Run now runs the automation’s actions immediately, against a made-up motion event on the first camera of its trigger (or the first camera, if it names none). The actions are real: notifications are sent, webhooks are called, MQTT messages are published and record modes change. Arming, conditions and cooldown are not checked.
Through the API
Section titled “Through the API”Automations are at /api/v1/automations (scopes automation:read and automation:write, administrator tokens only). The editor saves the same JSON:
{ "name": "Person in the driveway at night", "enabled": true, "trigger": { "objects": ["person"], "cameras": ["<driveway camera id>"] }, "conditions": { "timeOfDay": "night" }, "actions": [ { "type": "notify", "channels": ["<channel id>"] }, { "type": "record_mode", "camera": "<garage camera id>", "recordMode": "continuous" } ], "cooldownMs": 300000}POST /api/v1/automations/{id}/test is the Run now button. See the API reference.
Examples
Section titled “Examples”Light the porch when a parcel arrives. When: package. On cameras: Front door. Then: MQTT publish, topic home/porch/light/set, payload ON (use your own device’s topic). Add a Home Assistant automation that turns the light off again.
Keep the back of the house recording after someone is seen at night. When: person. On cameras: Garden. Time: Night. Then: Set record mode, Garage, continuous, and Notify on your phone’s channel. Cooldown: 600. Nothing switches the garage back by itself; set it back to motion in the morning, for example from a Home Assistant automation on its Record mode select.
Send every event to n8n. No objects, no cameras. Then: Webhook, https://n8n.example.com/webhook/aperture. For a signed feed with retries, add the URL under Integrations › Webhooks instead.
Quiet alerts while at home. Leave automations and rules as they are, and disarm from Home Assistant when the family arrives (for example on a presence trigger), arm when everyone leaves.
Schedules
Section titled “Schedules”Aperture schedules recording, not alerts or automations:
- A camera in Scheduled recording mode records only inside weekly windows. Set them with Edit recording schedule in the camera’s Recording settings: paint the hours per weekday. The windows follow the site’s time zone. See Recording.
- Notification rules have Quiet hours (see Notifications).
- Automations have no time triggers, and arming has no timer. For anything on a clock, use Home Assistant or cron with the API, as above.
Home Assistant can also change a camera’s recording mode through its Record mode select (aperture/<camera id>/set/record_mode), with the same refusal of scheduled for a camera without windows.
Troubleshooting
Section titled “Troubleshooting”- An automation never fires. Check that it is enabled, that the system is armed, and that the camera’s events in Alarms carry the label it waits for. Last triggered in the list shows when it last fired.
- It fires too often. Set a Cooldown, pick objects, or narrow the cameras. With no objects picked, every motion, audio and package event triggers it.
- The MQTT message never arrives. Check Integrations › Home Assistant: the MQTT connection must be up. The payload is sent as typed, without placeholders.
- A camera stopped recording after an automation. Look for a Set record mode action that chose
never.
Related: Notifications · Home Assistant · Object recognition · API