Roku Device Toolkit

npm install kopytko-roku-device

import { SsdpClient, EcpClient, DeviceManager } from 'kopytko-roku-device';

// DeviceStorage + NetworkWatcher are host-provided interfaces:
// the VS Code extension backs them with Memento global state and a
// focus-aware network poller; a CLI can use a JSON file + no-op watcher.
const manager = new DeviceManager(
  new SsdpClient(),
  new EcpClient(),
  myStorage,        // implements DeviceStorage
  myNetworkWatcher, // implements NetworkWatcher
);

manager.on('devices-changed', () => {
  for (const device of manager.getDevices()) {
    console.log(device.friendlyName, device.ip, device.state);
  }
});

await manager.initialize(); // starts SSDP + initial M-SEARCH scan

import { EcpClient, parseRegistryXml } from 'kopytko-roku-device';

const ecp = new EcpClient();

const info = await ecp.queryDeviceInfo('192.168.1.20');
console.log(info['model-name'], info['software-version']);

const apps = await ecp.queryApps('192.168.1.20');
const dev = apps.find((a) => a.id === 'dev'); // sideloaded channel

// Registry of the sideloaded channel (all channels sharing the dev key)
const registryXml = await ecp.queryRegistry('192.168.1.20', 'dev');
const registry = parseRegistryXml(registryXml);
console.log(registry.plugins); // e.g. "158987,268970,dev"

// Deep linking — relaunch with params, or roInput to the running channel
await ecp.launchApp('192.168.1.20', '12', { contentId: 'movie-123', mediaType: 'movie' });
await ecp.sendInput('192.168.1.20', { contentId: 'movie-123', mediaType: 'movie' });

// Channel icon — raw bytes + content type (binary-safe)
const { data, contentType } = await ecp.queryAppIcon('192.168.1.20', '12');

import { EcpClient, EcpKeys, textToLitKeys } from 'kopytko-roku-device';

const ecp = new EcpClient();

// Press-and-release a named key (POST /keypress/{key})
await ecp.keypress('192.168.1.20', EcpKeys.Home);

// Hold a key — the device keeps it pressed until the matching keyup
await ecp.keydown('192.168.1.20', EcpKeys.Right);
await ecp.keyup('192.168.1.20', EcpKeys.Right);

// Type on the on-screen keyboard: one strictly sequential keypress per
// Unicode code point, Lit_-encoded ('€' → 'Lit_%E2%82%AC')
await ecp.sendText('192.168.1.20', 'my search term');
textToLitKeys('r€'); // → ['Lit_r', 'Lit_%E2%82%AC']

// Playback state — foreground app + media player (state, codecs, DRM)
const active = await ecp.queryActiveApp('192.168.1.20');
const player = await ecp.queryMediaPlayer('192.168.1.20');
if (player.state === 'play') console.log(player.format?.video, player.format?.drm);

import {
  DebugConsoleClient,
  ChanperfCollector,
  EcpObjectCountsCollector,
} from 'kopytko-roku-device';

// SceneGraph debug console (port 8080) — idle-framed, auto-reconnecting
const console8080 = new DebugConsoleClient({ host: '192.168.1.20' });

// Poll per-channel CPU + memory every second
const chanperf = new ChanperfCollector(console8080, 1000);
chanperf.on('sample', (s) => {
  // { type: 'mem-cpu', wall, memKiB, anonKiB, cpuPct, ... }
  console.log(s);
});
chanperf.start();

// Collectors never throw into callers: a failed poll skips that
// interval and the collector self-heals when the device answers again.

import { ProtocolClient, DebugCommands, IOClient } from 'kopytko-roku-device';

// Binary BrightScript remote debug protocol (port 8081)
const client = new ProtocolClient('192.168.1.20');
client.on('update', (update) => console.log(update)); // stops, compile errors, IO port
await client.connect(); // 8-byte magic handshake + version negotiation

const commands = new DebugCommands(client);
const threads = await commands.threads();
const stack = await commands.stacktrace(threads.primary);
await commands.addBreakpoints([{ filePath: 'pkg:/source/main.brs', lineNumber: 42 }]);

import { InstallerClient } from 'kopytko-roku-device';

const installer = new InstallerClient();
const password = 'my-dev-password'; // username is always 'rokudev'

// Installer tab
await installer.installChannel('192.168.1.20', password, './build/archive.zip');

// Packager tab — installs, signs, and downloads the .pkg
await installer.packageChannel(
  '192.168.1.20', password, './build/archive.zip',
  'MyApp/1.0', 'my-signing-password', './out/signed.pkg',
);

// Utilities tab
await installer.takeScreenshot('192.168.1.20', password, './out/screenshot.jpg');
await installer.downloadProfilingData('192.168.1.20', password, './out/channel.bsprof');

// Update tab
await installer.checkForUpdate('192.168.1.20', password);

import { EcpClient, RaleTrackerClient } from 'kopytko-roku-device';

// Requires Roku's RALE TrackerTask injected and started in the (dev) channel.
const rale = new RaleTrackerClient({ host: '192.168.1.20', ecp: new EcpClient() });
const { raleVersion } = await rale.connect(); // ECP activate -> TCP connect -> init
await rale.hideSelectorView();                // no red selector rectangle on the TV

// setField writes to the *selected* node — always selectNode first.
const { node } = await rale.selectNode([{ child: 0 }, { child: 2 }]);
if (node.item.subtype === 'Label') {
  await rale.setField('text', 'Hello from RALE');
  await rale.setField('visible', true);
}

rale.close(); // the task returns to awaiting activation

npm install -g kopytko-roku-device
kopytko-roku --help

# ECP
kopytko-roku ecp device-info --host 192.168.1.20
kopytko-roku ecp keypress --host 192.168.1.20 --key Home
kopytko-roku ecp launch --host 192.168.1.20 --app dev --param contentId=42
kopytko-roku ecp app-ui --host 192.168.1.20

# Developer web-admin
kopytko-roku installer screenshot --host 192.168.1.20 --password secret --out shot.jpg

# Discovery
kopytko-roku discover --json