diff --git a/docs/DEVELOPER/dev-tools/external-control-api.md b/docs/DEVELOPER/dev-tools/external-control-api.md index 820b1fed..bb7bca0d 100644 --- a/docs/DEVELOPER/dev-tools/external-control-api.md +++ b/docs/DEVELOPER/dev-tools/external-control-api.md @@ -124,9 +124,56 @@ commands to the Roku device. ### General ECP commands -{` -
CommandDescriptionRequired Device Settings
query/media-playerReturns a child element named 'player' that identifies the media player state. The information returned includes the current stream segment and position of the content being played, the running time of the content, audio format, and buffering. This command is accessed using an HTTP GET.
keydown/Equivalent to pressing the remote control key identified after the slash. This command is sent using an HTTP POST with no body.Control by mobile apps setting “Enabled”
keyup/Equivalent to releasing the remote control key identified after the slash. This command is sent using an HTTP POST with no body.Control by mobile apps setting “Enabled”
keypress/Equivalent to pressing down and releasing the remote control key identified after the slash. You can also use this command, and the keydown and keyup commands, to send keyboard alphanumeric characters when a keyboard screen is active, as described in Keypress Key Values. This command is sent using an HTTP POST with no body.Control by mobile apps setting “Enabled”
query/device-infoRetrieves device information similar to that returned by roDeviceInfo. This command is accessed using an HTTP GET.

As of [Roku OS 15.0](doc:release-notes#roku-os-150), this command returns the following fields that indicate whether TV power and audio volume control have been enabled on a Roku streaming player:

- supports-tv-power-control
- supports-audio-volume-control
query/icon/supports-tv-power-control supports-audio-volume-controlReturns an icon corresponding to the application identified by appID. The binary data with an identifying MIME-type header is returned. This command is accessed using an HTTP GET. Example: GET /query/icon/1Control by mobile apps setting “Enabled”
query/chanperf

query/chanperf/<channelld>?duration-seconds=<seconds>		Returns the current memory and CPU utilization of the app running in the foreground (RAM usage is reported bytes). The foreground app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.

As of [Roku OS 15.2](doc:release-notes#roku-os-152), the command response includes a new **proc-stat** field that reports the raw Linux CPU and processing status information ([/proc/pid/stat](https://www.man7.org/linux/man-pages//man5/proc_pid_stat.5.html)).

Developers can use this data in their own monitoring and debugging tools to optimize app performance.
  • Including the channelId option in the path outputs statistics for a specific app from the Streaming Store. To use this command, the device must be keyed with the same developer ID/key that was used to generate the package file. The app's process ID (pid) is added to the output of this command.
Developer mode enabled

Control by mobile apps setting “Enabled”
query/r2d2-bitmapsReturns a list of the assets that have been loaded into texture memory and the amount of used, available, and maximum memory on your device (in bytes).

As of [Roku OS 11.5](doc:release-notes#roku-os-115), this query returns all bitmaps in texture memory, including those that cannot be directly attributed to an app.		Developer mode enabled

Control by mobile apps setting “Enabled”
query/sgnodes/all?count_only=true&sizes=trueReturns all the nodes created by the currently running app. This includes the number of osref references to the node (held in the Roku platform) and bscref references (held in the app).

  • The bcsref count includes references from "m." variable and local variables. Child references and field references do not increase bscref counts. The bscref count provides a more relevant and accurate indication of the resources that the app itself controls.
- The count_only parameter returns the total number of objects as a parameter in the All-Nodes field .
- The size parameter returns the memory used by the object (in kB).		Developer mode enabled

Control by mobile apps setting “Enabled”
query/sgnodes/roots?count_only=true&sizes=truePrints every existing node without a parent that has been created by the currently running app. The existence of these un-parented nodes means they are being kept alive by direct BrightScript references. These could be in variables local to a function, arrays, or associative arrays, including a component global m or an associative array field of a node.Developer mode enabled

Control by mobile apps setting “Enabled”
query/sgnodes/nodes?node-id=nodeId&count_only=true&sizes=truePrints nodes with an id field set to node_ID, except it, bypasses all the hierarchy and rules and just runs straight down the whole list in the order of node creation. It will list multiple nodes if there are several that match.Developer mode enabled

Control by mobile apps setting “Enabled”
sgrendezvousLists the node rendezvous events for a sideloaded app or production/beta app linked to the Roku developer's account.

Use the following commands to enable the logging of rendezvous events, log the events, and disable logging. To use these commands, the device must have developer mode enabled.

CommandArgumentDescription
sgrendezvous/track
(POST request)		channel_id (optional)Starts the logging of node rendezvous events node between threads. Only one app can be tracked at a time. Tracking a different app clears any queued rendezvous events.

To track rendezvous events, send a POST command with no JSON body: 
POST http://[IP address]:8060/query/sgrendezvous/trackPOST http://[IP address]:8060/query/sgrendezvous/track/[channel_id]
The response to this command is as follows: 
    true    OK
query/sgrendezvousReturns the rendezvous events that have occurred since tracking was enabled, or since the previous call to query/sgrendezvous. A maximum of 1,000 events are queued between calls; events beyond this limit are not logged. If events are dropped, the response includes the total count of those dropped events.

To retrieve rendezvous events, send a GET command: 
GET http://[IP address]:8060/query/sgrendezvous

See query/sgrendezvous example for details on the command response.
sgrendezvous/untrackTo stop the tracking of rendezvous events, send a POST command with no JSON body: 
POST http://[IP address]:8060/query/sgrendezvous/untrack

The response to this command is as follows: 
    false    OK
Developer mode enabled

Control by mobile apps setting “Enabled”
query/registry/<channelld>Lists the entries in the device registry for a sideloaded app or production/beta app linked to the Roku developer's account. The app ID must be provided; for sideloaded apps, use "dev" as the channelId.Developer mode enabled

Control by mobile apps setting “Enabled”
query/graphics-frame-rate

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		Returns the recent number of rendered graphics frames per seconds (this value is separate from the video frame rate). Developer mode must be enabled to use this command.Developer mode enabled

Control by mobile apps setting “Enabled”
fwbeacons

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		Tracks app and media lifecycle events for a specific app. To use these commands, the device must have developer mode enabled.
CommandDescription
fwbeacons/track fwbeacons/track/<channelId>
(POST request)		Enables tracking of app and media lifecycle events for a specific app. When tracking is enabled, a maximum of 1,000 events may be queued for retrieval with the query/fwbeacons command; events may be lost if not queried. If tracking is enabled with a different channel ID, all queued events on the previous app are discarded.

If the channelId path parameter is not specified, the query is run on the foreground UI app.

All devices may monitor a sideloaded app. Devices that are keyed may monitor apps from the Streaming Store that are signed with the same developer key.
query/fwbeaconsRetrieves the app and media lifecycle events that have occurred since the previous query, or since tracking was enabled if no query has been done.
fwbeacons/untrackDisables tracking of app and media lifecycle events (if enabled) and discards all queued events.
Developer mode enabled

Control by mobile apps setting “Enabled”
query/app-object-counts/<channelId>

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Returns the counts for the different BrightScript node objects in the app. This helps developers determine the counts of each type of object held by their Brightscript app.

The app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.		Developer mode enabled

Control by mobile apps setting “Enabled”
query/app-state/<appId>

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Returns the current app state: "active", "background" (suspended; running in the background), or "inactive".

The app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.

If the app is not installed, this command returns an error.		Developer mode enabled

Control by mobile apps setting “Enabled”
exit-app

(POST request)

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Suspends or terminates an app that is running:
  • If the app supports Instant Resume and is running in the foreground, sending this command suspends the app (the app runs in the background).
  • If the app supports Instant Resume and is running in the background or the app does not support Instant Resume and is running, sending this command terminates the app.
Developer mode enabled

Control by mobile apps setting “Enabled”
inputSends custom events to the current application. It takes a user defined list of name-value pairs sent as query string URI parameters. The external control server places these name-value pairs into an associative array, and passes them directly through to the currently executing app script using a Message Port attached to a created roInput object.

[Input Command Conventions](doc:external-control-api#input-command-conventions) includes detailed recommendations on how to pass your data.

Messages of type [roInputEvent](doc:roinputevent) have a GetInfo() method that will obtain the associative array. The arguments must be URL-encoded.

This command is sent using an HTTP POST with no body. Example: POST /input?acceleration.x=0.0&acceleration.y=0.0&acceleration.z=9.8
-`} + + + + + + + + + + + + + + + + + + + + + + + + + +
CommandDescriptionRequired Device Settings
query/media-playerReturns a child element named 'player' that identifies the media player state. The information returned includes the current stream segment and position of the content being played, the running time of the content, audio format, and buffering. This command is accessed using an HTTP GET.
keydown/<KEY>Equivalent to pressing the remote control key identified after the slash. This command is sent using an HTTP POST with no body.Control by mobile apps setting "Enabled"
keyup/<KEY>Equivalent to releasing the remote control key identified after the slash. This command is sent using an HTTP POST with no body.Control by mobile apps setting "Enabled"
keypress/<KEY>Equivalent to pressing down and releasing the remote control key identified after the slash. You can also use this command, and the keydown and keyup commands, to send keyboard alphanumeric characters when a keyboard screen is active, as described in Keypress Key Values. This command is sent using an HTTP POST with no body.Control by mobile apps setting "Enabled"
query/device-infoRetrieves device information similar to that returned by roDeviceInfo. This command is accessed using an HTTP GET.

As of [Roku OS 15.0](doc:release-notes#roku-os-150), this command returns the following fields that indicate whether TV power and audio volume control have been enabled on a Roku streaming player:

- supports-tv-power-control
- supports-audio-volume-control
query/icon/<APP_ID>supports-tv-power-control supports-audio-volume-controlReturns an icon corresponding to the application identified by appID. The binary data with an identifying MIME-type header is returned. This command is accessed using an HTTP GET. Example: GET /query/icon/1Control by mobile apps setting "Enabled"
query/chanperf

query/chanperf/<channelld>?duration-seconds=<seconds>		Returns the current memory and CPU utilization of the app running in the foreground (RAM usage is reported bytes). The foreground app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.

As of [Roku OS 15.2](doc:release-notes#roku-os-152), the command response includes a new **proc-stat** field that reports the raw Linux CPU and processing status information ([/proc/pid/stat](https://www.man7.org/linux/man-pages//man5/proc_pid_stat.5.html)).

Developers can use this data in their own monitoring and debugging tools to optimize app performance.
  • Including the channelId option in the path outputs statistics for a specific app from the Streaming Store. To use this command, the device must be keyed with the same developer ID/key that was used to generate the package file. The app's process ID (pid) is added to the output of this command.
Developer mode enabled

Control by mobile apps setting "Enabled"
query/r2d2-bitmapsReturns a list of the assets that have been loaded into texture memory and the amount of used, available, and maximum memory on your device (in bytes).

As of [Roku OS 11.5](doc:release-notes#roku-os-115), this query returns all bitmaps in texture memory, including those that cannot be directly attributed to an app.		Developer mode enabled

Control by mobile apps setting "Enabled"
query/sgnodes/all?count_only=true&sizes=trueReturns all the nodes created by the currently running app. This includes the number of osref references to the node (held in the Roku platform) and bscref references (held in the app).

  • The bcsref count includes references from "m." variable and local variables. Child references and field references do not increase bscref counts. The bscref count provides a more relevant and accurate indication of the resources that the app itself controls.
- The count_only parameter returns the total number of objects as a parameter in the All-Nodes field .
- The size parameter returns the memory used by the object (in kB).		Developer mode enabled

Control by mobile apps setting "Enabled"
query/sgnodes/roots?count_only=true&sizes=truePrints every existing node without a parent that has been created by the currently running app. The existence of these un-parented nodes means they are being kept alive by direct BrightScript references. These could be in variables local to a function, arrays, or associative arrays, including a component global m or an associative array field of a node.Developer mode enabled

Control by mobile apps setting "Enabled"
query/sgnodes/nodes?node-id=nodeId&count_only=true&sizes=truePrints nodes with an id field set to node_ID, except it, bypasses all the hierarchy and rules and just runs straight down the whole list in the order of node creation. It will list multiple nodes if there are several that match.Developer mode enabled

Control by mobile apps setting "Enabled"
sgrendezvousLists the node rendezvous events for a sideloaded app or production/beta app linked to the Roku developer's account.

Use the following commands to enable the logging of rendezvous events, log the events, and disable logging. To use these commands, the device must have developer mode enabled.

+
+ + + + + + + + + +
CommandArgumentDescription
sgrendezvous/track
(POST request)		channel_id (optional)Starts the logging of node rendezvous events node between threads. Only one app can be tracked at a time. Tracking a different app clears any queued rendezvous events.

To track rendezvous events, send a POST command with no JSON body: 
POST http://[IP address]:8060/query/sgrendezvous/trackPOST http://[IP address]:8060/query/sgrendezvous/track/[channel_id]
The response to this command is as follows: 
<sgrendezvous>    <tracking-enabled>true</tracking-enabled>    <status>OK</status></sgrendezvous>
query/sgrendezvousReturns the rendezvous events that have occurred since tracking was enabled, or since the previous call to query/sgrendezvous. A maximum of 1,000 events are queued between calls; events beyond this limit are not logged. If events are dropped, the response includes the total count of those dropped events.

To retrieve rendezvous events, send a GET command: 
GET http://[IP address]:8060/query/sgrendezvous

See query/sgrendezvous example for details on the command response.
sgrendezvous/untrackTo stop the tracking of rendezvous events, send a POST command with no JSON body: 
POST http://[IP address]:8060/query/sgrendezvous/untrack

The response to this command is as follows: 
<sgrendezvous>    <tracking-enabled>false</tracking-enabled>    <status>OK</status></sgrendezvous>
+
Developer mode enabled

Control by mobile apps setting "Enabled"
query/registry/<channelld>Lists the entries in the device registry for a sideloaded app or production/beta app linked to the Roku developer's account. The app ID must be provided; for sideloaded apps, use "dev" as the channelId.Developer mode enabled

Control by mobile apps setting "Enabled"
query/graphics-frame-rate

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		Returns the recent number of rendered graphics frames per seconds (this value is separate from the video frame rate). Developer mode must be enabled to use this command.Developer mode enabled

Control by mobile apps setting "Enabled"
fwbeacons

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		Tracks app and media lifecycle events for a specific app. To use these commands, the device must have developer mode enabled.
+
+ + + + + + + + + +
CommandDescription
fwbeacons/track fwbeacons/track/<channelId>
(POST request)		Enables tracking of app and media lifecycle events for a specific app. When tracking is enabled, a maximum of 1,000 events may be queued for retrieval with the query/fwbeacons command; events may be lost if not queried. If tracking is enabled with a different channel ID, all queued events on the previous app are discarded.

If the channelId path parameter is not specified, the query is run on the foreground UI app.

All devices may monitor a sideloaded app. Devices that are keyed may monitor apps from the Streaming Store that are signed with the same developer key.
query/fwbeaconsRetrieves the app and media lifecycle events that have occurred since the previous query, or since tracking was enabled if no query has been done.
fwbeacons/untrackDisables tracking of app and media lifecycle events (if enabled) and discards all queued events.
+
Developer mode enabled

Control by mobile apps setting "Enabled"
query/app-object-counts/<channelId>

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Returns the counts for the different BrightScript node objects in the app. This helps developers determine the counts of each type of object held by their Brightscript app.

The app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.		Developer mode enabled

Control by mobile apps setting "Enabled"
query/app-state/<appId>

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Returns the current app state: "active", "background" (suspended; running in the background), or "inactive".

The app may either be a sideloaded app or an app from the Streaming Store. To output the results for an app in the app store, the device must be keyed with the same developer ID/key that was used to generate the package file.

If the app is not installed, this command returns an error.		Developer mode enabled

Control by mobile apps setting "Enabled"
exit-app

(POST request)

Available since [Roku OS 13.0](doc:release-notes#roku-os-130)		Suspends or terminates an app that is running:
  • If the app supports Instant Resume and is running in the foreground, sending this command suspends the app (the app runs in the background).
  • If the app supports Instant Resume and is running in the background or the app does not support Instant Resume and is running, sending this command terminates the app.
Developer mode enabled

Control by mobile apps setting "Enabled"
inputSends custom events to the current application. It takes a user defined list of name-value pairs sent as query string URI parameters. The external control server places these name-value pairs into an associative array, and passes them directly through to the currently executing app script using a Message Port attached to a created roInput object.

[Input Command Conventions](doc:external-control-api#input-command-conventions) includes detailed recommendations on how to pass your data.

Messages of type [roInputEvent](doc:roinputevent) have a GetInfo() method that will obtain the associative array. The arguments must be URL-encoded.

This command is sent using an HTTP POST with no body. Example: POST /input?acceleration.x=0.0&acceleration.y=0.0&acceleration.z=9.8
## Input command conventions @@ -909,7 +956,7 @@ protocol (ECP) which includes functionality similar to DIAL. An experienced Roku developer may thus fairly ask the question "why do I need DIAL?" One reason is that you may already have a DIAL based second screen implementation for use with other platforms. DIAL support on the -Roku platform means that you don’t need to add a second protocol to your +Roku platform means that you don't need to add a second protocol to your current application for discovery and launch. [The Roku DIAL sample](https://github.com/rokudev/samples/tree/master/utilities) contains