The Surveillance Experience

The model

The experience is assembled from three independent agents plus the camera proxy. There is no single surveillance API. A driver participates by talking to whichever agents are relevant to it.

A driver reporting things that have already happened, such as a detection, an alarm, or a door opening, needs only the history agent. Writing the same occurrence to the timeline as well produces two entries for one event.

The timeline agent is the correct surface for future events: things scheduled to happen that a user may intervene in beforehand. That is where its validation, modification and action attachment apply.

The experience is opt in per system, and the opt in lives inside the experience rather than in settings. Open a camera in the app and accept the prompt there. A driver cannot enable it and should not assume it is on.

The timeline agent requires OS 4.0.0. Below that it disables itself at startup and every timeline command silently does nothing. The history agent has no such floor.

Call flow

History agent

The primary surface. A single write feeds three things at once: the History list in the app, per type push notifications, and the surveillance timeline.

Resolving

HISTORY = next(C4:GetDevicesByC4iName("control4_agent_history.c4i"))

Older helper snippets look for shorter names that do not match what current systems install. If the filename lookup fails, the agent can also be found by display name, which is what appears in Director traces.

if not HISTORY then
  for id, _ in pairs(C4:GetDevicesByName("History") or {}) do
    HISTORY = id
  end
end

Recording an event

Use C4:SendUIRequest. SendToDevice appears to succeed, returns nothing, and creates no record.

local reply = C4:SendUIRequest(HISTORY, "RECORD_HISTORICAL_EVENT", {
  DEVICE_ID   = C4:GetProxyDevices(),   -- the proxy device
  SEVERITY    = "Info",                 -- Critical, Warning or Info
  CATEGORY    = "Cameras",
  SUBCATEGORY = "IP Camera",
  TYPE        = "Vehicle",              -- the event name users see
  DESCRIPTION = "Vehicle detected on Driveway",
})

The call returns the record's UUID wrapped in XML. Parse it and keep it, because attaching an image needs it.

local parsed = C4:ParseXml(reply)
local uuid = (parsed and parsed.Name == "uuid") and parsed.Value or nil

Categories

Cameras with IP Camera is the pairing the interface expects for camera events. Security is correct for alarm panels and access control. Using it for a camera detection logs an entry the surveillance timeline does not treat as a camera event.

Attaching images

A record with no image appears in the History list but does not surface in the surveillance timeline. The image is what distinguishes a surveillance entry from a log line.

Attach it with a second call, using the record UUID. This one is SendToDevice.

C4:SendToDevice(HISTORY, "SET_METADATA_ON_RECORD", {
  RECORD_UUID    = uuid,
  METADATA_NAME  = "media_filename",
  METADATA_VALUE = "/path/to/snapshot.jpg",
})

media_filename is a path to a file on the controller, not image bytes and not a URL. The file must already exist when this call is made. If the driver receives images as base64 or fetches them over HTTP, write them to disk in the driver's own directory first.

local dir = C4:GetDriverFileDirectory()
local f = io.open("snapshot_01.jpg", "wb")
f:write(jpegBytes)
f:close()
-- then attach dir .. "/snapshot_01.jpg"

Event registration

Registering event types builds the taxonomy the History agent uses for filtering, and populates the curated list users choose from when enabling push notifications. It is independent of recording and belongs at driver init.

Two forms exist, both in shipping use.

-- current form
local result = C4:RegisterEvents(eventsXml)

-- older form, addressed to the driver's own proxy
C4:SendToDevice(proxyId, "REG_HISTORY_EVENTS", { XML = eventsXml })

C4:RegisterEvents has changed return type across versions. Older builds return a boolean, where false means retry. Newer builds return a number, where -6 means retry and -1 means the registration failed. Handle both rather than assuming one.

Deep links from a notification into the relevant device require the Navigation agent (control4_agent_navigation.c4i) in the project. Without it entries still record and notify, but tapping one goes nowhere.

Timeline agent

Holds two sets, past and future. Past events are populated automatically from the history agent. Future events are things scheduled to happen, which a user can intervene in beforehand, and that is what this agent is for from a driver's perspective.

Every command carries one serialized payload and returns a small XML document, either <success>true</success> or <success>false</success>. Compare against the literal string.

TIMELINE = next(C4:GetDevicesByC4iName("agent-timeline.c4z"))

Do not write past events for occurrences the history agent already recorded. SetPastEvent is accepted unconditionally, so this fails silently as a duplicated timeline rather than as an error.

Event payload

One object, base64 encoded JSON in the payload parameter.

{
  "source": {
    "deviceId":    123,
    "displayName": "Side Gate",
    "fileName":    "your-driver.c4z"
  },
  "event": {
    "id":          "9f2c7a10-4e55-4b21-8f0e-1c3d5a7b9e42",
    "displayName": "Motion at the side gate",
    "timestamp":   1725213610,
    "actions": [
      { "command": "muteThisSensor", "displayName": "Mute For Now" },
      {
        "command":     "snoozeThisSensor",
        "displayName": "Snooze",
        "params": [ { "id": "hours", "allowedValues": [1, 2, 3, 4, 5] } ]
      }
    ]
  }
}

Quick Actions agent

Supplies the controls offered alongside a notification. It has no driver facing command surface. Everything it exposes is for the user interface.

The agent scans the project for devices whose driver matches an enabled entry in its allow list, then drives them with ordinary proxy traffic such as select, scene activation, or macro execution. Those entries are proxy types rather than specific products, so any driver implementing a supported proxy is eligible without writing anything.

The list is editable per project, with paired properties for moving an entry between enabled and disabled, and a parallel set for macros. A driver that expects to appear and does not should be checked against the enabled list, and against whether the agent is in the project at all.

Behavior notes

Integration recipe

A driver reporting a detection. Helper names are placeholders for whatever the driver already has.

-- 1. resolve the history agent, tolerating absence
local HISTORY

local function ResolveHistory()
  HISTORY = next(C4:GetDevicesByC4iName("control4_agent_history.c4i"))

  if not HISTORY then
    for id, _ in pairs(C4:GetDevicesByName("History") or {}) do
      HISTORY = id
    end
  end

  print("history agent: " .. tostring(HISTORY))
  return HISTORY
end

-- 2. record the event, then attach its image
local function ReportDetection(what, cameraName, jpegPath)
  if not HISTORY and not ResolveHistory() then
    return
  end

  local reply = C4:SendUIRequest(HISTORY, "RECORD_HISTORICAL_EVENT", {
    DEVICE_ID   = C4:GetProxyDevices(),
    SEVERITY    = "Info",
    CATEGORY    = "Cameras",
    SUBCATEGORY = "IP Camera",
    TYPE        = what,
    DESCRIPTION = what .. " detected on " .. cameraName,
  })

  local parsed = C4:ParseXml(reply)
  local uuid = (parsed and parsed.Name == "uuid") and parsed.Value or nil

  if not uuid then
    print("history: no uuid returned, record was not created")
    return
  end

  -- without this the entry stays out of the surveillance timeline
  if jpegPath and jpegPath ~= "" then
    C4:SendToDevice(HISTORY, "SET_METADATA_ON_RECORD", {
      RECORD_UUID    = uuid,
      METADATA_NAME  = "media_filename",
      METADATA_VALUE = jpegPath,
    })
  end

  return uuid
end

Fetching the image first

The file must exist before the record is written, so an asynchronous fetch has to complete first. Guard it with a timeout so a slow or missing image still produces an entry rather than none at all.

local imageSeq = 0

local function ReportWithSnapshot(what, cameraName, cameraId)
  imageSeq = (imageSeq % 60) + 1        -- rotate, never overwrite
  local name = ("detect_%02d.jpg"):format(imageSeq)
  local done = false

  local function finish(path)
    if done then return end
    done = true
    ReportDetection(what, cameraName, path)
  end

  C4:SetTimer(6000, function() finish(nil) end)

  FetchSnapshot(cameraId, function(ok, jpeg)
    if not ok or not jpeg or #jpeg < 200 then
      finish(nil)
      return
    end

    local f = io.open(name, "wb")
    if not f then
      finish(nil)
      return
    end

    f:write(jpeg)
    f:close()
    finish(C4:GetDriverFileDirectory() .. "/" .. name)
  end)
end

Gateway and child drivers

The record is filed against the calling driver's proxy device, and there is no argument to override that. A gateway therefore cannot record on a child's behalf in a way the experience attributes correctly. The working arrangement is for the gateway to resolve the event and broadcast it to its children, and for the child owning that device to make the call. The gateway can still prepare the image, since it holds the credentials, and pass the path along with the broadcast.

Promoting a future event to a past one

An elapsed future event is deleted rather than converted, so a driver that schedules work closes the loop itself. Keep the payload you scheduled with, then resend it as a past event once the thing happens.

local function PromoteToPast(eventId, ranEarly)
  local payload = ScheduledPayloads[eventId]
  if not payload then return end

  payload.event.actions = nil            -- a completed event offers nothing

  if ranEarly then
    payload.event.timestamp = os.time()  -- when it really happened
  end

  local reply = C4:SendToDevice(TIMELINE, "SetPastEvent", {
    payload = C4:Base64Encode(C4:JsonEncode(payload, false, true)),
  })

  if reply ~= "<success>true</success>" then
    print("timeline rejected SetPastEvent: " .. tostring(reply))
  end

  ScheduledPayloads[eventId] = nil
end

This is one of the few legitimate uses of SetPastEvent, because the event was never in History to begin with. A cancel action removes the future event and writes nothing to the past. A run now action removes it, performs the work, and writes the past event with a corrected timestamp.

Troubleshooting