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.
Where the support belongs
Section titled “Where the support belongs”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.
What to expose in Composer
Section titled “What to expose in Composer”A design that has worked well:
Properties
Section titled “Properties”| 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.
Commands
Section titled “Commands”| 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.
Actions
Section titled “Actions”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.
Sending a request
Section titled “Sending a request”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 headersend
-- 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()) endendfail_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)Things that make the Lua side easy
Section titled “Things that make the Lua side easy”The app was written with driver authors in mind:
- Choice words are forgiving.
size,corner,decoderandother_audioignore case and treat-and_alike. Turn a Composer value such as “Top Right” intotop_rightwithstring.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.
videosandactionsshould 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
warningslist says what the app corrected. Print it in the Lua output while developing.
Reading the reply
Section titled “Reading the reply”| 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) endendTelling “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 /statusis a cheap way to confirm: it answers with the app’s version, whether the overlay permission is granted and whether a token is required.
Camera addresses
Section titled “Camera addresses”- 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.
Sending a snapshot instead
Section titled “Sending a snapshot instead”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.
Interactive popups
Section titled “Interactive popups”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)Acting on a button
Section titled “Acting on a button”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": truethe reply arrives when the popup has closed, withend_reason,action(the last button pressed) andactions_pressed(all of them, in order). Set the request timeout well aboveduration: every key press restarts the countdown, and it is paused while the picture is expanded. - Or poll.
GET /statsholds 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": falsemust 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")endKeep the ids short and stable; they are the contract between the driver and the programming.
Snooze
Section titled “Snooze”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.
Closing a popup
Section titled “Closing a popup”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)Checklist
Section titled “Checklist”- 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
adbcommand. - Camera logins are masked in every print and log line.
-
warningsfrom the reply are visible while developing. - The test action uses
test-patternand reports the time to first picture. - A request timeout is always set, and is longer than the popup’s life when
wait_for_endis used. - The driver’s documentation tells the dealer to install the app and grant the overlay permission, see Getting started.
Trademarks
Section titled “Trademarks”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.
TV Camera Popup is free and provided as is, without warranty or support. It is an independent project, not affiliated with, endorsed by or sponsored by Control4, Sony or Google; those names are used only to say what the app works with. Privacy policy · Help