Roku SDK Documentation : Loading and Running Your Application

Table of Contents

Enabling Development Mode on your box

Before you are able to load a development application to your box, you must enable development mode on your Roku Streaming device. Development mode can be enabled only on a linked device. Your device must be linked to a Roku user account.  You can link your device by either resetting it to factory defaults or going to Streaming Channels on your device.

To enable development mode, enter the special remote control sequence: Home 3x, Up 2x, Right, Left, Right, Left, Right.  The entire sequence must be entered within 10 seconds.

You will be presented with the Developer Settings page where you can enable developer mode on the box. When developer mode is enabled, you can access the Application Installer page as specified in the next section.

If you would like to subsequently disable development mode on your box, simply enter the special remote code sequence again and select the "disable installer" option on screen.

Application Installer Page

Development applications are loaded onto the device using a standard web browser. When enabled for development mode the device hosts a web page for installing your application. To access the installer page, do the following:

1. From your Roku Streaming Player, navigate to "Roku Player Settings", "player info" to find the IP address of your box.
2. From your development workstation, open a standard web browser and type the following URL for the browser to open: http://rokuPlayer-ip-address. For example: http://192.168.1.100/.
   You should see the following screen:
   
   
   
   
3. Click the Browse button and navigate to the location of the application ZIP file on your development machine as shown below.
   The full path to the application ZIP file should appear in the text field.
   
   
   
   

4. The following image shows the standard windows file browser. Your development environment may be on Windows, Linux or Mac, since all you need are text editing tools, a web browser and the ability to generate ZIP files containing your application. Select your application ZIP file and you are ready to install.

   
   
   

5. Finally, click the Install button to deploy the application to the Roku player. The application should install and begin running immediately. You will see a message on the web page indicating it was successfully loaded as shown in Figure 3 (Application Installer Page – Installation Complete).
   
   
   
   
6. Run the application with the application debug console open. When you Telnet to the Roku Streaming Player on port 8085 (see Accessing the Debug Console) you will see the debug console from your application. If there are any errors in your code, they will show up on this console. There is even a debugger attached to this port that will give you source file and line number information for script errors.
   
   The Application Installer page only accepts applications using the ZIP file format (.zip). This process is often referred to as "side-loading" your application. It does not allow installation of signed applications package files (.pkg). A package file must be distributed through the Channel Store mechanism, as either a published or non-certified channel application.
   
   

7. The following image shows the Development Application Installer window after you've successfully installed your application.
   
   
   
   

   If you attempt to reinstall an identical version of an application that is already installed on the box, you will receive an error. You can always delete and re-install any application at any time.  Due to the limited amount of flash storage available, applications are limited to a maximum of 4MB in size.
   
   In general, since these are internet enabled applications, they tend to be much smaller and are typically less than 300KB in size. Most of the space is consumed by artwork and the code size is minimal. If you find that your application is too large to install, look at removing some of the artwork from your application package and placing it on the web where it is easier to modify and it can be downloaded dynamically at runtime.

Using the Makefile to "Side-Load" the channel

The SDK examples include Makefiles that can automate the steps needed to install the channel. The Makefiles use the ROKU_DEV_TARGET and the DEVPASSWORD environment variable.

1. You can either get the Makefile using the steps mentioned above in Application Installer Page or use this Makefile. 
   
   
2. Put the Makefile and the app.mk in the same directory as your manifest.    
   
   Note: You can further modify the "ZIP_EXCLUDE" line in the Makefile to exclude certain files.
   
   
3. Set the environment variables and then run “make install”
   
   % export ROKU_DEV_TARGET=192.168.1.140 
% export DEVPASSWORD=1234 
% cd <sdk>/examples/source/videoplayer 
% make install

ROKU_DEV_TARGET is your Roku's IP address, and DEVPASSWORD is the password set when you put the device in developer mode.

Building an Application

Now that you've installed some of the SDK examples, here's how to build a simple application from start to finish. We'll show you how to do it by building the simplest of all applications, an application that prints "Hello World!" on the screen.

First, create a directory named helloworld, with a sub-directory named source, such as: 

% mkdir helloworld
% cd helloworld 
% mkdir source

Using your favorite editor, create the manifest file for the Hello World application named manifest in the helloworld directory that contains the following content:

Hello World Application Manifest File

Now, create a BrightScript source code file named helloworld.brs in the helloworld/source directory that contains the following content:

Hello World Application BrightScript Code

Finally, use a ZIP program to create the compressed archive of your application, such as:

% zip -9 –r ../helloworld.zip .

Now you can follow the instructions in Application Installer Page to install helloworld.zip as a development application on a development test Roku device.