Debugging with Roku Client Logs

Multiple tools are available for debugging Cloud Apps. These debugging tools provide access to the runtime environment, crash logs, stack traces, and more.

BrightScript Console

The BrightScript Console shows the output of your Client during runtime. If the Client crashes, the BrightScript Console displays the line number of the error, as well as the contents of variables at the time of the crash. Compilation errors (such as Syntax Error) are also displayed here. To catch possible startup errors, keep the BrightScript Console open whenever you side-load the client.

To access the BrightScript Console, open a terminal window and run:

telnet <Roku device IP address> 8085

The BrightScript Console shows:

Current processes.
Custom logs.
Remote controller events.
Crash logs.

Custom logs

To display custom logs in the BrightScript Console, you must copy and modify a BrightScript client file. You can find the BrightScript client files in the ~/youiengine/<version>/src/cloud folder.

Important

Make sure to preserve the original folder structure. If you copy a file from the ~/youiengine/<version>/src/cloud/source folder, paste it in <project>/client/source.

To add custom logs:

Make a copy of main_implementation.brs for editing.

Open a terminal window and run the following commands from your <project>/client folder:
```
mkdir source
cp ~/youiengine/<version>/src/cloud/source/main_implementation.brs ./source
```
Add a custom log to <project>/client/source/main_implementation.brs.

There are multiple ways to print logs from BrightScript. You can use any of the following statements:
```
logMessage("Log message")
print "Log message"
? "Log message"
```
Pro tip
It’s good practice to set identifiers before the actual log contents (for example, POR123: Log message). A unique string makes searching the logs easier.
Side-load the client to your Roku device.
```
youi-tv roku-client -l -s <Roku device IP address> -u rokudev:<password>
```
Note
Don’t forget to run the JavaScript Metro bundler and the server before side-loading the client.

BrightScript Debug Shell

The BrightScript Debug Shell is an interactive debugging tool. It provides features and utilities such as:

Memory utilization.
CPU utilization.
FPS (frames per second).
Actions (for example, freeing device memory).

To access the BrightScript Debug Shell, open a terminal window and run:

telnet <Roku device IP address> 8080

See a full list of commands in the Roku Developer Documentation.

Troubleshooting common errors

Server error on launch

If launching the Client results in the error <App_Name> application Error, the client is likely unable to connect with the server.
Ensure your local machine and the Client device are both on the same network.
- Verify the host and port configuration in the client manifest file. Ensure that host is the Server IP address.
- Verify that the IP address of the local machine hasn’t changed from the value for host in the client manifest file.
- Use the Roku’s Settings page to check its network state. Ensure that the connection is good.

Scene export missing elements

If elements are missing from your scene export, try quitting the Client (with the home button) and then relaunching it. On the server side, this results in a re-export of the scene to the client. If the problem is fixed, the list likely wasn’t ready and visible when the scene was exported.

Focus map is incorrect

The focus map used by the client is static. It’s generated once a scene is exported and the server has a valid view in focus. One way to debug an incorrect focus map is to quit the client (with the home button) and then relaunch it. On the server side, this results in a re-export of the scene and the generation of a new focus map. If focus now behaves as expected, the given view was likely not focusable when the initial focus map was generated.
You can inspect the contents of the focus map by watching the client logs (the focus map arrives as JSON). For a prettier view of the structure, you can edit source/focus.brs and uncomment the debug output in focusMapCommand().

Images not appearing

If image assets aren’t loading on the Client, verify that permissions on your S3 store are set to Public.
Roku 8.0.0 and later have image caching. If you launch a Client and it fails to retrieve the images, it caches them as unfetchable. Rebooting the Roku device resolves this issue.