2011-05-17

Start developing for the Roku Part 2: Packaging and uploading

This is part 2 in a series. You may want to see Part 1 to figure out how we got to this point.

Part 2 of this tutorial will cover how to package and upload your channel to the Roku. This allows the Roku to compile your code and report any errors it encountered, and run the channel so you can test how it works.

Now that we have something to upload to the Roku, we need to package it for side-loading. Side-loading is the process of manually uploading a channel you've created using the Roku's developer mode. It doesn't require any special utilities out of the ordinary, and is very easy, but only one channel can be side-loaded at a time.

There are three steps to side-loading your channel:
  1. Enable developer mode
  2. Package your channel
  3. Upload your packaged channel
These are each extremely easy, and only #2 and #3 need be repeated to side-load after the first time.

Enabling Developer Mode

The first step to side-loading a channel is to enable developer mode. To enable developer mode on the Roku, you need to enter the3 following sequence on the remote: Home, Home, Home, Up, Up, Roght, Left, Right, Left, Right. This should cause a special "Developer Settings" screen to come up, which offers you the option to enable (or disable if it's already enabled) the installer. It will require a restart of the Roku, but after that you should be able to side-load channels without problem.

Packaging Your Channel

Packaging your channel for side-loading onto the Roku really just means compressing your channel into a ZIP archive. Most modern operating systems ship with some sort of built in archival utility that can create ZIP archives, but if your operating system doesn't, you can download either WinZIP or WinRAR's free versions for your OS and use that to create the archive.

Note: While packaging for side-loading requires only creating a ZIP archive, packaging for upload as a Private or Public channel requires the extra step of signing the package. This is covered in the Roku SDK in the Packaging and Publishing document, and may be covered in a future tutorial.

The important thing to remember when zipping your channel content is that the channel folder itself should not be part of the ZIP file. That is, if you examine the contents of the ZIP file, you should see a manifest file and source folder at the top level (plus any additional files, such as an images folder), NOT a single folder containing those items.

Uploading your channel

To finish side-loading your channel, you need to upload it to the Roku. To upload just browse to your Roku's IP address in a browser, which should bring up the channel packager and installer interface. Simply click the button to select your packaged (zipped) channel, and then click (or if you've already got a channel side-loaded) to upload the channel.

Note: You can find your Roku's IP address by going to the Settings section and choosing the Player Info section.

Upon uploading your channel, it will run automatically. It will also show up as the last channel in the list of channels on the Roku main screen so you can start it again without uploading it. Currently, it won't have a useful image, but that's because we haven't defined one in the manifest file.

Note: When a side-loaded channel is running, you can telnet to port 8085 using the Roku's IP address, and you'll have access to a debugger console. This will show the output of any print statements, as well as any errors encountered in compiling or running the code.

When the channel runs, you should see an orange-ish screen for 5 seconds (if you are uploading the package from Part 1) before it returns to the Roku home screen. If you had a telnet session to the debugger console open, you should also have seen a notice that the channel started running, and the output from the print statement we put in the channel in Part 1.

This concludes Part 2. In Part 3 we'll draw some more shapes on the screen and examine a few of the BrightScript core data types available (Arrays and Associative Arrays).

Changelog:
2011-05-22 21:47 Re-wrote and re-formatted.

9 comments:

  1. I've tried this several times and the channel never runs. Everything says it's been installed and packaged, but it never shows up on my roku. Any ideas?

    ReplyDelete
  2. I had to move sleep(5000) to the next line or I get an error.

    ReplyDelete
  3. Indeed, the sleep(5000) statement was meant to be on the subsequent line. I've fixed Part 1 now to reflect this.

    ReplyDelete
  4. For some reason the print line does not put anything on the screen. I do have the orange background though.

    ReplyDelete
    Replies
    1. "print" only works in the debugger. It never writes to your tv.

      Delete
  5. It says I have no manifest file. It is definitely there, it has no extension, and it is not nested in any folder, it is at the root level of the zip file. Are these instructions valid for a Roku 1?

    ReplyDelete
  6. Never mind, helps if you check your spelling, SMH

    ReplyDelete
  7. Do we need tv to run roku application

    ReplyDelete
    Replies
    1. No, but you do need an attached TV to see the output. That is, you can connect to the debugging console and see debug output, and your program should run without a TV attached (I think. Unless the Roku doesn't like no TV attached), but it won't generally do you a lot of good.

      Delete