Apple Bridge

The model

The bridge is a singleton that stands between TV device drivers in the project and a controller-local daemon that speaks to the physical devices. Your driver never talks to the daemon; it exchanges plain driver-to-driver commands with the bridge, and the bridge translates.

Three identities matter, and confusing them is the usual integration bug. Your device id is the Control4 id of your driver; it addresses ACTIVATE and SEND_KEY and is where the bridge sends replies. The bridge assigns each discovered device an internal index that selects which daemon socket to use; you never see it. The remote identifier is the daemon's id for a pairable device, delivered in AVAILABLE_CHANGED and echoed back inside the REMOTE string; it is also the id embedded in the voice URL.

Registration comes in two grades. A device whose driver.xml declares <push-to-talk>true</push-to-talk> is registered with the daemon as a voice remote and its sessions carry a voice URL. Without the capability it is registered as a plain remote: buttons work, ACTIVE still arrives, but its URL is never populated for voice.

Call flow

Conventions

Discovery is by exact filename, again

The bridge scans the project for devices whose driver file is named appleTV.c4z and nothing else. This is the same rule the Voice Coordinator applies, so one filename buys both integrations. At discovery the bridge reads the device's declared capabilities; a lowercased match on <push-to-talk>true</push-to-talk> upgrades the registration to a voice remote. Capabilities come from the device data recorded when the device was added, so a capability edit takes effect only after removing and re-adding the device.

Finding the bridge

The bridge is a singleton; address it by filename:

local bridgeId = next(C4:GetDevicesByC4iName("AppleBridge.c4z"))

The stock device driver installs the bridge automatically when it is missing, so treat a nil result as "not installed yet" rather than an error, and retry after a few seconds.

Entry points

Everything in both directions travels as C4:SendToDevice and lands in ExecuteCommand. Nothing on this interface uses proxies, bindings, or UI requests.

Discovery gates

The bridge only registers devices while discovery is authorized: the Discover Remotes property is On (the default), or the non-remote discovery property is On, or a ten-minute pairing window opened from the mobile side is running. With every gate closed the bridge shuts its daemon session down entirely, and nothing on this page functions. The bridge also defers its own initialization until a companion system driver, when present, reports ready.

Library conventions are not the contract

The command names, parameter names, the REMOTE string format, and the URL shape are wire contract. The handler style is not: this page writes a plain ExecuteCommand, and a driver built on the shared library reaches the same handlers through its EC. dispatch table. Helper names in the examples, such as StoreVoiceUrl(), are placeholders to write yourself.

Commands you send

Sent with C4:SendToDevice(bridgeId, ...). All of them require your device to be in the bridge's discovery map; a driver the bridge has not discovered is silently ignored.

The bridge also accepts management traffic that is not part of the device-driver contract: REFRESH and RESTART_DAEMON mirror the Composer actions, and PAUSE_DISCOVERY, RESUME_DISCOVERY, ENABLE_REMOTE_DISCOVERY, ENABLE_SIRI_DISCOVERY, STATUS_UPDATE, and CHANGEPROP belong to the companion system driver. Leave them alone.

Commands that arrive

The bridge sends these to your driver's ExecuteCommand. Handle all four; three of them change what your voice UI requests should answer.

function ExecuteCommand(strCommand, tParams)
  if strCommand == "AVAILABLE_CHANGED" then
    local entries = { "Not Activated [0]" }
    for identifier, name in pairs(tParams) do
      table.insert(entries, name .. " [" .. identifier .. "]")
    end
    UpdateSelectorList(entries)          -- write this yourself
    ReassertPersistedSelection(entries)  -- sends ACTIVATE if found
  end
end

Alongside ACTIVE and NOT_ACTIVE the bridge sends the Voice Coordinator APPLETV_STATUS { STATUS, DEVICE_ID }, with your device id as DEVICE_ID. That message is what lets the coordinator start your voice target immediately instead of on its next timer pass; your driver neither sends nor receives it, but it is why the ordering works: the bridge delivers ACTIVE to you first, so your config reply is already valid when the coordinator asks.

Data shapes

The REMOTE string

"<name> [<identifier>]", for example "Media Room [3]". The bridge parses it with "%[(%d+)%]": the first bracketed run of digits wins and the name is ignored. Keep device names out of your own bracket notation or the wrong identifier can be extracted.

The voice URL

c4vc://<identifier>@<ip>:<port>/. The daemon composes it; the identifier is the active remote identifier and the address points at the daemon's audio listener, not at your driver. Nothing on the device-driver side should parse it. Store and relay.

Button events

-- a tap
{ ID = C4:GetDeviceID(), BUTTON = "select", STATE = "press",
  DURATION = 100, TIMESTAMP = tostring(now) }

-- a hold, as a down/up pair
{ ID = ..., BUTTON = "menu", STATE = "down", TIMESTAMP = tostring(now) }
{ ID = ..., BUTTON = "menu", STATE = "up",
  TIMESTAMP = tostring(now + holdMs) }

Composer surface

The bridge's own surface, for orientation while debugging. Your driver does not manage any of it.

Behavior notes

Integration recipe

The minimum for a device driver that wants working voice through the bridge. Requires the file to be named appleTV.c4z and <push-to-talk>True</push-to-talk> in driver.xml.

-- 1. Find the bridge; install it if absent, then retry.
local function BridgeId()
  return tonumber(next(C4:GetDevicesByC4iName("AppleBridge.c4z")) or 0) or 0
end

-- 2. Handle the bridge's messages.
gVoiceUrl = ""

function ExecuteCommand(strCommand, tParams)
  tParams = tParams or {}

  if strCommand == "AVAILABLE_CHANGED" then
    local entries = { "Not Activated [0]" }
    for identifier, name in pairs(tParams) do
      table.insert(entries, name .. " [" .. identifier .. "]")
    end
    UpdateSelectorList(entries)             -- property list for the installer
    local kept = PersistData.Selection or ""
    for _, entry in ipairs(entries) do
      if entry == kept then Activate(kept) end
    end

  elseif strCommand == "ACTIVE" then
    gVoiceUrl = tParams.URL or ""
    C4:SendToProxy(5001, "SET_PTT_URL", { URL = gVoiceUrl,
                                          Protocol = "Control4" })

  elseif strCommand == "NOT_ACTIVE" then
    gVoiceUrl = ""
    C4:SendToProxy(5001, "SET_PTT_URL", { URL = "", Protocol = "Control4" })
    ScheduleReactivate(3)   -- re-send ACTIVATE on a short delay
  end
end

-- 3. Activate the installer's selection, and persist it.
function Activate(selection)
  PersistData.Selection = selection
  C4:SendToDevice(BridgeId(), "ACTIVATE",
                  { REMOTE = selection, ID = C4:GetDeviceID() })
end

-- 4. Serve the URL to the voice stack. The coordinator reads the first
--    two; Navigators read the third.
function UIRequest(strCommand, tParams)
  if strCommand == "GET_VOICE_TARGET_TYPE" then
    return "<TargetType>appletv</TargetType>"
  elseif strCommand == "GET_VOICE_TARGET_CONFIG" then
    return "<TargetConfig>" .. gVoiceUrl .. "</TargetConfig>"
  elseif strCommand == "GET_PTT_URL" then
    return "<PTT><URL>" .. gVoiceUrl ..
           "</URL><Protocol>Control4</Protocol></PTT>"
  end
end