Start developing for the Roku Part 1: My first channel

There's quite a few posts on the Roku Developer Forum about how to get started developing for the Roku, given that the platform uses a proprietary language called BrightScript. So much so, in fact, that I decided it's time to write up a few tutorials on how to get your first channel going, starting from scratch.

This isn't intended for those intending to just take an example channel (of which there are many in the SDK) and alter it, but for those struggling with the core concepts of the language, or that have trouble following what's happening in the examples provided.

This is Part 1, which covers how to create the content of a very simple channel. Part 2 will cover how to package and upload this channel to the Roku.

First, we need to create the directory/folder structure for the channel, which will look like this:

-- myfirstchannel
   |-- manifest (a text file)
   |-- source (a folder)
   |   `-- main.brs (text file for BrightScript code)
   `-- images (a folder)
       `-- ... (no contents currently)

As you can see, we have a folder for the channel, containing a manifest file, and two more folders, source and images. Within the source folder there is a file called main.brs which will contain our starting code.

Note: The file containing the code can be called anything as long as it resides within the source folder or a sub-folder of it, and ends in .brs. More specifically, any file ending in .brs in source will be concatenated together at run-time, so the specific file names don't matter at all.

First things first, we need some content for our manifest file. Let's use the following for now:

title=Tutorial Channel
subtitle=The basics of BrightScript programming
mm_icon_focus_hd=pkg:/images/not_here.png
mm_icon_side_hd=pkg:/images/not_here.png
mm_icon_focus_sd=pkg:/images/not_here.png
mm_icon_side_sd=pkg:/images/not_here.png
major_version=1
minor_version=0
build_version=00000

In Windows, you'll want to make sure you can see file extensions, and that there isn't one. The file contains text, but it doesn't have a .txt extension. If you double click the file and it automatically opens in a text editor, you need to look into how to rename the file so there is no extension. Also, please make sure you are saving these files as ASCII (non Word/RTF) text.

Now we need to add some content to the channel. Let's open up (create) source/main.brs in a text editor and add some content:

sub main()
    canvas = CreateObject("roImageCanvas")
    canvas.setLayer(0, { color: "#884400" })
    canvas.show()
    print "canvas shown"
    sleep(5000)
end sub

Here we have a few things to examine. Firstly, there's a subroutine (a function without a return value) called main. This is how the Roku determines where to start executing code. After concatenating all the source files together, and parsing the code, it looks for a function or subroutine called main to run, and starts there.

Second, we create an object of type roImageCanvas and assign it to the canvas variable. The CreateObject() function is how you access built in BrightScript and Roku components that have been provided to enhance the platform. Almost every complex component of the system will be created with a call similar to this.

Third, we call the setLayer() method on the canvas object to assign some data. in this case, we are creating a layer 0 with an orange-ish color (as specified by the hex color #884400). Don't worry too much about the curly braces, we'll cover those a bit later. Just remember that we passed in a color attribute when we set the layer.

Fourth, we call the show() method on the canvas object, which will cause it to actually show on the screen. Without this command any changes to the canvas object are non-visible.

Lastly, we print a simple statement that the canvas has been shown, and sleep for 5 seconds (5000 ms). The print output won't be visible on the screen, it is only output to the debugger console, but we'll see it later. The sleep statement pauses execution for a time. If we didn't do this, you wouldn't see much for your channel, as the main subroutine would end, and the channel would exit back to the Roku main screen almost immediately.

That concludes the first part of the tutorial. In Part 2 we'll cover how to package the channel you just made and upload it to the Roku for testing.