Skip to main content

Device API

Handles TV-related operations, such as rebooting, shutting down, and resetting to factory conditions.

device.adbState​

Signatures​

adbState()

Description​

Returns the current ADB connection state for the device as a string.

Possible return values:

  • "device" — ADB is connected and the device is responsive.
  • "unauthorized" — The device is visible over USB/network but has not authorized this host's ADB key. The user needs to accept the RSA key prompt on the device.
  • "absent" — the device is still on USB but ADB cannot drive it: the adb server lists it as offline, or dropped it while it is still enumerable over USB. maintenance.usbReset() may recover it.
  • "offline" — the device is not on USB at all, or the adb server is unreachable; there is nothing a USB reset could recover.

This is the branching primitive for CableGuy auto-heal automations: a "device" state means ADB is usable; "absent" means the ADB daemon wedged on a still-attached device and maintenance.usbReset() may recover it.

Example​

local state = device.adbState()
if state == "device" then
  -- ADB is healthy, proceed
elseif state == "absent" then
  -- USB present but ADB daemon wedged — try maintenance.usbReset()
end

device.foregroundApp​

Signatures​

foregroundApp(lua)

Description​

Queries the device for the app currently running on it.

Returns a Lua-friendly map with app_id, app_version, and app_name fields. app_version and app_name may be nil if the protocol can't cheaply report them.

If the live query fails (e.g. the platform does not expose the running app), falls back to the app stored in the automation context from launch time. If neither is available, all fields are returned as nil so automations can handle the case gracefully.

local info = device.foregroundApp() print(info.app_id, info.app_version, info.app_name)

device.getDeviceLogs​

Signatures​

getDeviceLogs(stream, lines \ 100, lua)

Description​

Returns the most recent device log lines for a stream, oldest first.

The lines come from the in-memory buffer Sidecar.Device.LogStream fills as it ships console output — no device round-trip. The buffer starts empty at session start, is cleared on cooldown, and holds a bounded number of bytes per stream, so old lines fall off.

Parameters​

  • stream - one of "cdp", "adb", "sdb", "roku", "wpe"
  • lines - how many of the newest lines to return (default 100)

Example​

for _, line in ipairs(device.getDeviceLogs("cdp", 50)) do
  print(line)
end

device.launchAppByUrl​

Signatures​

launchAppByUrl(app_url, opts \ [], lua)

Description​

Opens a URL on the device, in whatever handles URLs there.

Browser devices navigate the browser. Android and Fire TV send a VIEW intent. Tizen and webOS open the system browser. SmartCast loads the URL as the sideload app. Apple TV treats it as a URL scheme, so a plain web page does nothing useful there. Roku and Vega cannot open a URL and return an error.

Returns "ok", version or "error", message.

Example: local status, err = device.launchAppByUrl("https://example.com")