# Remote Access Services

The **BrightScript Simulator** desktop app, the same way all Roku devices, implements some remote access services in order to enable automation and monitoring of the apps being executed. It allows among other possibilities, to integrate the simulator to the [VSCode BrightScript Extension](https://marketplace.visualstudio.com/items?itemName=celsoaf.brightscript) (see [how to integrate to VSCode](vscode-integration.md)). Below you will find a quick reference documentation about the services available.

## Application Installer

This service allows you to remotely _side load_ an app in the simulator, it has a web interface that can be accessed using a browser, or any _HTTP_ client application. It also has a `Utilities` option where the user can request a screenshot of the currently running app.

[![Application Installer](./images/installer-screenshot.gif)](./images/installer-screenshot.gif)

The **Development Application Installer**  by default listens to the _TCP_ port 80 and requires authentication to be used. Because this port is the default _HTTP_ port, it may cause conflict with existing services or be blocked by IT security policies. To overcome that, is possible to configure a different port, either using the [Settings Screen](docs/how-to-use.md#settings-screen) or running the simulator with the command line `--web=<newport>`, this option is saved in the app local storage. An icon is shown in the status bar with the listening port number indicating the service is active, if the icon is clicked it will open the Installer page on the default browser (image above).

The **Installer** default user and password are both `rokudev`, besides the [Settings Screen](docs/how-to-use.md#settings-screen), the password can also be changed (and saved) by using the command line `--pwd=<newpwd>`.

> [!IMPORTANT]
>
> On Linux systems, due to OS restrictions, the Installer service can not be started on port 80, so the service is disabled by default.
> To enable it, you must specify a different port.

## ECP (External Control Protocol)

Once it's enabled the **ECP API** allows the simulator to be controlled over the network by providing a number of external control commands. When the **ECP** is enabled it is discoverable using **SSDP** (Simple Service Discovery Protocol) just like a Roku device. **ECP** is a simple _RESTful API_ that can be accessed by programs in virtually any programming environment. Please check the [ECP official documentation](https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md) for detailed documentation of the protocol.

The **ECP** listens to the _TCP_ port 8060 and is disabled by default, it can be enabled either by using the options under the [Device Menu](how-to-use.md#device-menu) or via the [command line option](how-to-use.md#command-line-options) `--ecp`. An icon on the status bar with the port number indicates that the service is active, if the icon is clicked it shows the XML result of the `query/device-info` command on the default browser.

### Supported Commands

The **BrightScript Simulator** desktop app only implements a subset of **ECP** commands, here a list of supported commands:

| Command               | Description                                                                                                       |
|-----------------------|-------------------------------------------------------------------------------------------------------------------|
| query/device-info     | Retrieves device information similar to that returned by roDeviceInfo. (HTTP GET) |
| query/apps            | Returns a map of all the recent opened apps paired with their application ID. (HTTP GET) |
| query/active-app      | Returns a child element named 'app' with the active application, in the same format as 'query/apps'. (HTTP GET) |
| query/icon/`appID`    | Returns an icon corresponding to the application identified by appID. (HTTP GET) |
| query/registry/`appID`| Lists the entries in the device registry for apps. (HTTP GET) |
| query/input           | Sends custom events to the current application. It takes a user defined list of name-value pairs sent as query string URI parameters. (HTTP POST) |
| launch/`appID`        | Launches the app identified by appID. (HTTP POST) |
| exit-app/`appID`      | Terminates the app identified by appID if running. (HTTP POST) |
| keypress/`key`        | Equivalent to pressing down and releasing the remote control key identified after the slash. (HTTP POST) |
| keydown/`key`         | Equivalent to pressing the remote control key identified after the slash. (HTTP POST) |
| keyup/`key`           | Equivalent to releasing the remote control key identified after the slash. (HTTP POST) |

**Note:** The Application ID in the simulator is a simple hash of the full path of the app zip/bpk file.

## BrightScript Remote Console

The **Remote Console** can be accessed using telnet through a shell application such as [PuTTY](http://www.putty.org/) for Windows or terminal on Mac and Linux:

```console
telnet <simulator-ip-address> 8085
```

The simulator now supports the interactive debugging using the **Remote Console**, the list below has the Roku MicroDebugger commands currently implemented:

- `bt` - Print backtrace of call function context frames
- `cont|c` - Continue script execution
- `down|d` - Move down the function context chain one
- `exit|q` - Exit shell
- `gc` - Run garbage collector"
- `last|l` - Show last line that executed
- `next|n` - Show the next line to execute
- `list` - List current function
- `step|s|t` - Step one program statement
- `thread|th` - Show selected thread
- `threads|ths` - List all threads of execution
- `over|v` - Step over one program statement (for now act as step)
- `out|o` - Step out from current function (for now act as step)
- `var` - Display local variables and their types/values
- `print|p|?` - Print variable value or expression
- `exit` or `quit` - Finishes current app execution
- `close` - Disconnect from the remote console
- `help` - Show a list of supported commands

When the debugger is activated (either with `STOP` statement or via `Ctrl+Break`) you can type any expression for a live compile and run, in the context of the current function.

If the **Remote Console** is enabled an icon is shown in the status bar together with the port number 8085.