Skip to content

Control4 driver integration

TV Camera Popup has no Control4 driver of its own, and it does not need one. It is driven by plain HTTP requests on the local network, so any DriverWorks driver can show a popup with a few lines of Lua.

This page is for driver developers. It describes how to add popup support to a driver: where to put it, what to expose in Composer, how to send the requests and what to do with the answers. The full list of fields is in the Request reference.

Two places work well:

  • In the driver for the TV. It already knows the TV’s address and whether the TV is on, and “Show TV Popup” reads naturally as a command of the TV in programming.
  • In a small standalone driver, one instance per TV, with the TV’s address as a property. This keeps a certified or third-party TV driver untouched.

Either way the driver needs only outgoing HTTP to the TV on port 5001. The app never calls the driver back, so there is nothing to listen for.

A design that has worked well:

Property Type Purpose
TV Popups Enabled / Disabled A master switch, so the rest can be hidden when the app is not installed.
TV Popup Size Small / Medium / Large / Fullscreen Default size.
TV Popup Corner Top Left / Top Right / Bottom Left / Bottom Right / Center Default corner.
TV Popup Sound On / Muted Default mute.
TV Popup Other Audio Keep / Duck / Pause Default other_audio.
TV Popup Access Token Password The app’s access token. Empty when the app has none.

Leave a default out of the request when the dealer has not chosen one. The app then uses the defaults set on its own settings screen.

Command Parameters
Show TV Popup Title, Message, Video URL, Duration Seconds, and Size, Corner, Sound and Other Audio that each offer “Default” plus the choices above.
Dismiss TV Popup None.

“Default” on a command parameter means “use the property”, so a dealer sets the usual look once and overrides it only where a popup should differ.

A Test TV Popup action that sends "video": "test-pattern" is worth having. It shows the app’s built-in color-bar card, so it checks the app, the permission, the token and the placement without needing a camera, and the reply carries the time to first picture.

The asynchronous C4:url() interface does everything needed. This helper sends one request to the app and hands the decoded reply to a callback:

local POPUP_PORT = 5001
local function PopupHeaders()
local headers = { ["Content-Type"] = "application/json" }
local token = Properties["TV Popup Access Token"]
if token and token ~= "" then
headers["X-Access-Token"] = token
end
return headers
end
-- tvAddress: the TV's address, from the driver's network binding or a property.
-- onDone(reply, code, err): reply is the decoded JSON, or nil when the TV did not answer.
local function PopupRequest(tvAddress, method, path, body, timeoutSeconds, onDone)
local url = "http://" .. tvAddress .. ":" .. POPUP_PORT .. path
local transfer = C4:url()
transfer:SetOptions({ timeout = timeoutSeconds or 5, fail_on_error = false })
transfer:OnDone(function(_, responses, errCode, errMsg)
if errCode ~= 0 then
onDone(nil, 0, errMsg or "no answer")
return
end
local last = responses[#responses]
onDone(C4:JsonDecode(last.body), last.code)
end)
if method == "GET" then
transfer:Get(url, PopupHeaders())
else
transfer:Post(url, body and C4:JsonEncode(body) or "", PopupHeaders())
end
end

fail_on_error = false matters: the app’s error answers (400, 401, 403) carry a JSON body that says what is wrong, and the driver wants to read it.

Showing a popup is then one call:

PopupRequest(tvAddress, "POST", "/notify", {
title = "Front Door",
message = "Someone is at the door",
video = videoUrl,
duration = 30,
size = "medium",
corner = "top_right",
other_audio = "duck",
}, 5, HandlePopupReply)

The app was written with driver authors in mind:

  • Choice words are forgiving. size, corner, decoder and other_audio ignore case and treat - and _ alike. Turn a Composer value such as “Top Right” into top_right with string.lower(value):gsub(" ", "_").
  • Numbers and booleans may be text. "30" and "true" are accepted, so command parameters can be passed along as they arrive.
  • Lists may be Lua-style. videos and actions should be JSON arrays, but an object keyed "1", "2", … is accepted too, with a warning in the reply. Leave an empty list out of the request instead of sending an empty table.
  • Unknown fields are ignored, and a bad value costs a default, not the popup. The reply’s warnings list says what the app corrected. Print it in the Lua output while developing.
Result Meaning What the driver should say
No answer The TV is off or in deep standby, the address is wrong, or the app is not running. See Telling “TV off” from “app missing”.
200 Accepted. The body is the popup’s record. Nothing, or the timing when testing.
200 with "snoozed": true The viewer snoozed this source; nothing was shown. Nothing. This is not an error.
400 The request could never work, for example a Video URL that does not start with rtsp://, rtspt://, http:// or https://. The error text.
401 The app has an access token and the request had none, or the wrong one. “Set the TV Popup Access Token property.”
403 The app is missing the overlay permission. The error text, which holds the adb command that grants it.

A reply to a plain request comes back at once, before the camera has connected. To learn whether the picture really appeared, add "wait": true and allow a 25 second timeout: the reply then arrives with the first frame, or with error_text such as Camera refused the login. That is the right choice for a test action, and usually unnecessary for programming.

function HandlePopupReply(reply, code, err)
if not reply then
print("TV popup: no answer from the TV (" .. tostring(err) .. ")")
elseif code ~= 200 then
print("TV popup: " .. tostring(reply.error))
elseif reply.snoozed then
print("TV popup: snoozed by the viewer")
elseif reply.error_text then
print("TV popup: " .. reply.error_text)
end
for _, warning in ipairs(reply and reply.warnings or {}) do
print("TV popup warning: " .. warning)
end
end

Telling “TV off” from “app missing”

Section titled “Telling “TV off” from “app missing””

A request to a TV in standby may get no answer, or may be accepted and show nothing, because a popup does not turn the screen on.

  • If the driver knows the TV’s power state, check it first and skip the request, or turn the TV on, as the project requires.
  • When a request gets no answer and the TV is on, the app is not installed, was never opened, or the address is wrong. GET /status is a cheap way to confirm: it answers with the app’s version, whether the overlay permission is granted and whether a token is required.
  • Pass the Video URL to the app as it is. The app plays it directly from the camera, so the TV must be able to reach the camera.
  • Characters such as @, : or / in the user name or password must be percent-encoded (%40, %3A, %2F). Say so in the parameter’s description, or encode them when the driver builds the address itself.
  • The address, with its login, is stored in the Control4 project and travels to the TV without encryption.
  • Never print the login. Mask it before anything goes to the Lua output or the log, for example with url:gsub("//[^@/]*@", "//***@"). The app does the same in everything it reports.

To keep the camera login away from the TV, the driver can fetch a still picture itself and send it in the request:

local transfer = C4:url()
transfer:SetOptions({ timeout = 8, fail_on_error = false })
transfer:OnDone(function(_, responses, errCode)
if errCode ~= 0 or responses[#responses].code ~= 200 then return end
PopupRequest(tvAddress, "POST", "/notify", {
title = "Driveway",
image = C4:Base64Encode(responses[#responses].body),
duration = 20,
}, 5, HandlePopupReply)
end)
transfer:Get(snapshotUrl, snapshotHeaders)

The picture must be a JPEG or PNG, and the whole request may be up to 2 MB.

With "interactive": true the viewer can work the popup with the TV remote: cycle through cameras, expand the picture, press buttons and snooze. See Interactive popups for what the viewer sees.

PopupRequest(tvAddress, "POST", "/notify", {
title = "Front Door",
interactive = true,
duration = 30,
videos = {
{ title = "Front Door", video = frontDoorUrl },
{ title = "Driveway", video = drivewayUrl },
},
actions = {
{ id = "unlock", label = "Unlock door" },
{ id = "light", label = "Porch light", close = false },
},
snooze_key = "front_door",
wait_for_end = true,
}, 120, HandlePopupEnded)

The app does not do anything when a button is pressed except record its id. The driver learns about it and lets programming do the work.

  • Wait for the end. With "wait_for_end": true the reply arrives when the popup has closed, with end_reason, action (the last button pressed) and actions_pressed (all of them, in order). Set the request timeout well above duration: every key press restarts the countdown, and it is paused while the picture is expanded.
  • Or poll. GET /stats holds the record of a popup that is still showing, including the buttons pressed so far. Poll it every second or two while a popup is up when a button with "close": false must act right away.

Expose the result as a driver event, with the pressed id in a variable, so that a dealer can program “when a TV popup button is pressed, if the button is unlock, unlock the door”:

function HandlePopupEnded(reply, code)
if code ~= 200 or not reply or not reply.action then return end
C4:SetVariable("TV_POPUP_ACTION", reply.action)
C4:FireEvent("TV Popup Button Pressed")
end

Keep the ids short and stable; they are the contract between the driver and the programming.

Give every request from one source the same snooze_key, for example the name or device id of the doorbell. The popup then gets a Snooze button, and the app itself drops further requests with that key while the snooze lasts, answering them with "snoozed": true. The driver has nothing to track.

POST /dismiss closes whatever popup is showing, for example when the door is answered. It needs no body and is not an error when nothing is showing.

PopupRequest(tvAddress, "POST", "/dismiss", nil, 5, function() end)
  • Nothing is sent when the popup feature is disabled or the TV’s address is unknown.
  • The access token is sent when set, and a 401 is explained to the dealer.
  • A 403 shows the app’s own error text, which names the adb command.
  • Camera logins are masked in every print and log line.
  • warnings from the reply are visible while developing.
  • The test action uses test-pattern and reports the time to first picture.
  • A request timeout is always set, and is longer than the popup’s life when wait_for_end is used.
  • The driver’s documentation tells the dealer to install the app and grant the overlay permission, see Getting started.

Control4 is named here only as a system the app works with. TV Camera Popup is an independent project and is not affiliated with, endorsed by or sponsored by Control4, Sony or Google.