Skip to content

DEBUGGING.md

Latest commit

 

History

History
67 lines (51 loc) · 3.2 KB

DEBUGGING.md

File metadata and controls

67 lines (51 loc) · 3.2 KB
Raw

Roku Debugging

rokit can wrap Roku debugging surfaces when they expose generic device or runtime state. Keep product journeys, selectors, content IDs, account state, and assertions in consumer app repos.

Official Surfaces

Roku documents the developer debug console as a telnet connection to port 8085. It emits app runtime output, compilation errors, crash line numbers, stack traces, and variable state when an app fails. Open it before sideloading or reproducing a startup crash so the first failure is captured.

Roku also documents debug-server utilities on port 8080. Useful generic commands include:

Command Port Use
chanperf 8080 Current app memory and CPU snapshot
free 8080 Device memory snapshot
sgnodes roots 8080 Top-level SceneGraph nodes
sgnodes all 8080 Full SceneGraph node listing
sgnodes <node_ID> 8080 SceneGraph nodes with a matching id field
loaded_textures 8080 Loaded texture diagnostics
r2d2_bitmaps 8080 Bitmap diagnostics

The BrightScript debug protocol is a separate binary protocol for interactive debugger clients; rokit does not wrap it, because crash capture needs append-only text artifacts more than an IDE-style session.

Sources:

rokit Shape

rokit covers text telnet capture and allowlisted debug-server commands:

  • rokit console <output-path> [--duration-ms <ms>] captures port 8085 output to a timestamped local log.
  • rokit debug-command <command> [args...] sends one allowlisted command to port 8080 or 8085 and prints the response.

debug-command is described as mutating for agent safety because some allowlisted Roku commands can affect profiling/debugger state.

Roku's chanperf -r <seconds> command writes repeated samples to the BrightScript console on 8085, not the 8080 socket that receives the command. rokit debug-command rejects that form; capture the console with rokit console while sampling runs instead.

Use Node's node:net module directly instead of shelling out to a local telnet binary. This keeps the CLI cross-platform, typed, and easier to test.

Limits

  • Live verification requires a developer-enabled Roku with reachable debug ports. Unit tests can cover parsing, command validation, output paths, and socket behavior with fake TCP servers.
  • The console should be connected before the repro. It cannot recover log lines emitted before the socket was open.
  • Another tool, such as an IDE or Roku plugin, may already own the console connection.
  • If the device hard-reboots, rokit can only preserve bytes received before the socket disconnects.