![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
18 Mar 2010: By author request, changed all instances of hostapps.properties to hostapp.properties.
The OpenCable Application Platform (OCAP) is a platform for the cable television industry. Targeted at set-top boxes and televisions, OCAP provides a standard, hardware-independent basis for interactive applications that enhance the cable TV experience for consumers. The consumer-facing name for OCAP is tru2way; tru2way licensees include many well-known companies in the consumer electronics marketplace (see Resources).
The OCAP specification is developed by the CableLabs industry consortium. The document is publicly available, along with dozens of related specifications, at the CableLabs Web site (see Resources). The OCAP 1.1.2 document is 667 pages long, and like any good specification it builds on a foundation of many other documents. The sheer complexity of the platform makes it hard for a would-be OCAP developer to know where to begin. This three-article series aims to get Java™ developers interested in building applications for the platform off to an efficient start via the OCAP Reference Implementation (RI). Here in Part 1, you'll learn more about OCAP, download and install the RI, and run some applications on it. In Part 2, I'll cover how to create your own OCAP applications, using either a command line or the Eclipse IDE. Finally, Part 3 will take you under the hood and show you how you can build the OCAP RI yourself. It also includes a high-level guide to the source code.
Note: Currently, the OCAP RI is distributed and supported only on Microsoft® Windows®. However, as I'll discuss in Part 3, it is possible to build the RI on Linux® as well.
From an application perspective, it's helpful to consider OCAP as a collection of APIs. It includes graphics APIs for drawing on the screen, a tuner API for finding and showing TV channels, and many other APIs. But although it's helpful to think of OCAP as an API stack, it is an oversimplification. OCAP specifies many other behaviors, such as the minimum number of tuners a device should have and how much disk space should be available on an OCAP device.
With respect to APIs, OCAP builds on standard Java ME technology. Figure 1 shows the OCAP stack:
Figure 1. OCAP Stack
The OCAP stack has a long history, which means it's made up of many different pieces. It includes names such as DAVIC and HAVi as well as the components shown in Figure 1:
-
Java TV is a standard developed by Sun Microsystems.
-
JMF is the Java Media Framework, an API for rendering video and other media.
-
MHP (DVB Multimedia Home Platform) is another television standard.
-
CDC is Java ME's Connected Device Configuration. It forms the base of a Java technology stack. If you consider Java technology on a desktop computer as large, and Java technology on a mobile phone as small, then CDC would be medium. It is intended for devices such as television set-top boxes, automobile computers, and other midsized computers.
- The Foundation Profile (FP) and Personal Basis Profile (PBP) round out CDC with additional APIs, including APIs for user interface and graphics.
One of the crucial differences between CDC applications and standard desktop Java applications is in the application model. CDC applications are Xlets, which have a managed life cycle like applets, servlets (in enterprise Java technology), or MIDlets (in mobile Java technology).
Strictly speaking, OCAP is just a specification, so it is up to device manufacturers to implement it. To grease the wheels of this process, an RI is available.
The OCAP RI is an example of how to implement an OCAP stack. It makes life easier for device manufacturers because it provides a starting point — a known working implementation of the stack that can be adapted to various devices. It makes life easier for application programmers because it is a working OCAP stack that runs on desktop computers — a great place to run and debug applications before trying to deploy them to real devices.
Because the OCAP RI serves a variety of audiences, it is available in several forms:
-
A simple installer places binaries on a Windows computer. When the stack runs, it includes a simulated TV screen, a front-panel display, a remote control, and console output. It's useful if you want to run the OCAP stack with a minimum of setup. It's the version you'll use in this article.
-
An Eclipse plug-in provides support for creating OCAP applications using the Eclipse IDE
and testing them on the OCAP RI. You'll learn about the Eclipse plug-in in Part 2 of this series.
- The full source code is available if you want to build the OCAP RI yourself. This is helpful for people who are trying to implement OCAP on real devices or for anyone else who thinks it's fun to stare at huge piles of source code. Part 3 in this series describes how to build the OCAP RI.
Begin by downloading the installer for Windows. At this writing, the current version is 1.1.3RelA. If that link doesn't work, start at the OCAP RI page and follow links for the OCAP RI release.
It's a big download — about 155MB. After you have it, run the installer and answer the prompts. You don't need to make many choices, but if you are wondering what to do, consult the OCAP RI project Wiki page (see Resources).
After the installer is done, you'll have a desktop icon. Double-click it. A command-line window will pop up, followed shortly by the OCAP RI window, shown in Figure 2:
Figure 2. OCAP RI as it comes out of the box
It's set up to run an application called CirclesXlet, which I call the balls application. Go ahead and play with it. You can control the number and size of the balls by clicking the keys on the remote control.
To shut down the OCAP RI, find and select the command-line window, then press Ctrl-C. Windows asks Terminate batch job (Y/N)? Type n and press Enter. The OCAP RI window and the command-line window will both disappear.
The reason you type n is VLC (see Resources). VLC is one of those gems of the Internet, a highly capable open source application. You can use it to play video, transcode video, and serve streaming video. The OCAP RI uses VLC to simulate incoming video. When you shut down the OCAP RI, a script (batch file) tries to shut down VLC as well. Typing n at the prompt allows the script to do its job and shut down VLC.
Once again from the command line
Although it's convenient to start the OCAP RI from a desktop icon, you can launch it from the command line, which can be convenient for other reasons.
At the Windows command line (Start > All Programs > Accessories > Command Prompt), switch to the ocap-ri subdirectory where you installed the OCAP RI. If you accepted the default installation location, change directories like this:
C:\>cd CableLabs\tru2way\ocap-ri |
Now run the runRI.bat script by typing runRI.bat at the command prompt and pressing Enter. This is, of course, the same script that runs when you double-click the desktop icon. When you're finished playing with the balls, shut down the OCAP RI the same way as before: in the command-line window, hit Ctrl-C, then answer n to the prompt.
Working with applications on the OCAP RI
At some point you'll want to run more than just CirclesXlet. First, you need to understand how the OCAP RI decides which application to run. After that, you should understand a little bit about where console output goes.
Where did that application come from?
The OCAP RI locates an application using two main files. The first is mpeenv.ini, a crucial configuration file. It is located in ocap\bin\CableLabs\simulator\Win32\debug\env\ in the directory where the OCAP RI is installed. Open the file in a text editor and take a look. It contains oodles of settings.
Right now, the setting to care about is the classpath for the JVM. It's near the top of the file with the name VMOPT.0. In essence, it is a command-line parameter. The definition of VMOPT.0 is:
VMOPT.0=-Djava.class.path=/syscwd/sys/ocap-classes.jar;
/syscwd/sys/ocap-rez.jar;
/syscwd/sys/support.jar;
/syscwd/qa/ocap-test.jar;
/syscwd/qa/support-test.jar;
/syscwd;
/syscwd/usr;
/syscwd/apps/eas
|
The VMOPT.0 definition is on one long line, but here I've split it out for clarity. In the world of the OCAP RI, /syscwd means the current working directory, which in this case is the same as the location of mpeenv.ini.
The OCAP RI goes hunting through each entry in the classpath, looking for a hostapp.properties file. It launches the application described in that file. Knowing this, you can figure out how CirclesXlet gets run.
The first five entries in the classpath are JAR files that have no corresponding hostapp.properties. Next in the classpath is /syscwd. Take a look in ocap\bin\CableLabs\simulator\Win32\debug\env\ (which is really /syscwd in OCAP-land) and you will find a hostapp.properties file.
Open hostapp.properties in a text editor. It defines a few fields and provides an application class name. In this case, it's com.cablelabs.circlesxlet.CirclesXlet. Blackjack!
To understand how this all fits together, you will change hostapp.properties to run TuneTest instead. TuneTest is a relatively simple demonstration that exercises OCAP's television-tuning API.
First, comment out the application_name and initial_class_name for CirclesXlet by putting a hash mark (#) in front of those lines. Next, uncomment the four entries for TuneTest. When you're finished, the end of hostapp.properties should look like this:
app.0.application_identifier=0x000000015205 app.0.application_control_code=AUTOSTART app.0.visibility=VISIBLE app.0.priority=220 app.0.base_directory=/syscwd/qa/xlet #app.0.application_name=Circles #app.0.initial_class_name=com.cablelabs.circlesxlet.CirclesXlet app.0.application_name=TuneTest app.0.initial_class_name=org.cablelabs.xlet.TuneTest.TuneTestXlet app.0.args.0=config_file=config_tunetest.properties app.0.args.1=java_tv_channel_map=true |
You're almost ready to launch the OCAP RI again, but two more things must be put in place. First, you need to supply a configuration file for TuneTest. Second, you must break in the video-streaming software.
Look at the app.0.args.0 entry in hostapp.properties. It specifies the name of a configuration file that TuneTest expects to find. You need to put this file in the right place.
The configuration file is located in the extras directory of the OCAP RI installation, which is c:\CableLabs\tru2way\ocap-ri\extras if you used the default installation directory. Copy config_tunetest.properties and place it in ocap\bin\CableLabs\simulator\Win32\debug\env\qa\xlet, which is the same as /syscwd/qa/xlet, which you'll notice is specified as the base directory in hostapp.properties.
Because TuneTest shows incoming video, the OCAP RI will use VLC. Like a new baseball glove, VLC needs to be broken in before it can be used. The first time you run VLC, it presents a dialog with privacy settings. When the OCAP RI tries to run VLC, it gets stuck on the dialog (invisibly) and cannot be used to present video.
To break in VLC, open a command-line window. Navigate to ricommon\resources\Win32\VLC in the OCAP RI installation directory. Then type vlc and press Enter. The command prompt will return immediately, and after a few seconds you'll see VLC's privacy-settings dialog, shown in Figure 3:
Figure 3. VLC's privacy-settings dialog
All you need to do is click OK. The dialog goes away and you'll see VLC's main window, shown in Figure 4:
Figure 4. VLC's main window
You can quit VLC now. If you run it again, you'll go directly to the main window. VLC is now ready to be run automatically from the OCAP RI.
Now all your ducks are in a row. Launch the OCAP RI again with the runRI.bat command. Congratulations — you're watching simulated TV! Figure 5 shows what it looks like:
Figure 5. Grab a beer and some popcorn
The video playback is choppy at best, and switching channels can take a good 20 seconds. (If your hardware is faster than mine, you might get better results.)
Nevertheless, TuneTest is a good example of the television-y kinds of things you can do with OCAP.
You might have noticed that the OCAP RI produces an astonishing amount of output in the command-line window where it's running. Sometimes it can be useful to examine this output to help with debugging.
As the OCAP RI runs, it automatically stores an output log in the RILog.txt file. Feel free to open it up with a text editor to see what it looks like. If you're looking for something specific, it will be easier to find in a text editor instead of trolling back through your console.
Some settings in mpeenv.ini control the log output. The entries beginning with LOG.MPE control specific types of output. The ALL setting for LOG.MPE.DEFAULT turns on all messages. You can change it to NONE and then selectively enable other types of logging for more specific output.
Also, note that ALL is not the same as ALL DEBUG. You will get more console messages with ALL DEBUG.
By now, you are starting to understand what is cool about the OCAP RI. It is a powerful tool for developers who wish to create applications for the next generation of television devices. As you've seen, the OCAP RI is an accessible tool for running OCAP applications using only a Windows computer. You can create user interfaces and test advanced features like tuning without needing specialized hardware or a functioning television broadcast environment.
Tune in next time for Part 2 of this series, where you'll learn how to create applications that you can run on the OCAP RI and other OCAP devices. Finally, in Part 3, you'll learn about the innards of the OCAP RI itself.
Learn
-
OCAP: The OCAP specification is available online from CableLabs.
-
tru2way: tru2way is the consumer-facing brand for OCAP.
-
OCAP-RI Wiki: CableLabs hosts a Wiki dedicated to the OCAP RI.
-
VLC: The OCAP RI uses this cross-platform open source multimedia framework, player, and server to simulate
incoming video.
-
"Creating Interactive TV Applications With the Tru2way Platform and OCAP" (Bruce Hopkins, Sun Developer Network, April 2009): This article introduces the interactive TV concept and how to start out with OCAP/tru2way development (sans the RI).
-
"Blu-ray Disc Application Development with Java ME, Part 1: Creating Your First Application" (Bruce Hopkins, Sun Developer Network, September 2008): This article contains information about getting started with Blu-ray application development.
-
"Cable Technology - Why Tru2way Will Explode In The U.S. In 2009" (Jeff Bonin, TMCnet, May 2009): Get a cable TV industry insider's take on the reasons why OCAP is generating demand for new products and services.
-
Browse the
technology bookstore for books on these and other technical topics.
-
developerWorks Java technology zone: Find hundreds of articles about every aspect of Java programming.
Get products and technologies
-
OCAP RI: The OCAP RI project, hosted on java.net, is the place to go to download the binary installer or the Eclipse plug-in, or to learn how to get the source code.
Discuss
-
OCAP-RI Users forum: java.net hosts a forum for developers working with the OCAP RI.
- Get involved in the My developerWorks community.
Jonathan Knudsen is the author of several books and more than a hundred articles about Java technology and mobile robots. He is the husband of the most glorious woman to walk the Earth, the father of four amazing children, a decent piano player, and the scourge of many Bonsai trees. When Jonathan grows up, he wants to be a cowboy. For more information, see http://jonathanknudsen.com/.
