Developing widgets for chumby

From Chumby Wiki
Revision as of 20:55, 12 November 2007 by Nbillig (Talk | contribs)

Jump to: navigation, search

See also Developing Widgets for Chumby: Testing Widgets See also Developing Widgets for Chumby: Sensor Access

Summary

This page describes the development of widgets for the "Ironforge" production chumby hardware. Widgets for the Chumby are developed for Adobe Flash Lite 3.0. Flash Lite 3.0 has a feature-set based on desktop Flash Player 8.

Supported Features:

  • Flash video (FLV) encoded with ON2 and Sorenson Spark codecs
  • Video, NetStream and NetConnection classes
  • External MP3 files
  • External PNG, GIF, non-progressive JPEGs

Not supported:

  • Bitmap caching, bitmap effects or enhancements
  • Stylesheets
  • non-default code pages
  • Focal gradients
  • Progressive JPEGs

Also important for developers to note is that the device's current input system is a touchscreen, meaning that mouseMove events will only occur while mouseDown (equivalent on current computers of only being able to move the mouse while holding a mouse button), which may/will have some effect on how your programs operate.

For efficiency's sake, Flash Lite downsamples images and embedded fonts, so avoid resizing images and small serif fonts, as detail will be lost.

Developer Environment

While the chumby runs Flash Lite, it's actually a fairly normal Flash Player, and will run content most created for Flash 8 and earlier. It's not necessary to specifically publish for Flash Lite 2 or Flash Lite 3 in the Flash development tools unless you plan on using the features specific to Flash Lite. Most of these features are designed more for mobile phones and thus don't apply to chumby devices.

The most common and complete development tools for Flash are those available from Adobe, however, there are several other third-party programs that will generate Flash movies. Any version of Adobe's Flash products is capable of producing widgets for chumby, not just the latest version (currently Flash CS 3 Professional)

Performance and Optimizations

The protoype chumby has a 350Mhz ARM9 processor - similar in performance to a low-end Pentium desktop. There are certain tricks and techniques that can make the difference between a sluggish movie and one that works smoothly.

  • Change property values only when necessary. The very act of changing a property can result in a redraw of that object, even if the value itself hasn't changed. Be sure to check to see if changing the property is necessary before changing it - for instance, don't change the _rotation value of the hour hand of a clock if it hasn't actually moved.
  • Change dynamic text only when necessary. If the text isn't actually different, don't change it.
  • Reduce the size of images by playing with compression settings. Make the images as small as possible with acceptable quality.
  • Reduce the size of audio by playing with compression settings. As with images, try for small size with acceptable quality.
  • Simplify vector graphics. See if you can use Flash's curve simplification to reduce the number of points and curves. For static graphics, you might even be better off creating bitmaps and using them instead.
  • Avoid layered translucent areas. Piling on a lot of translucency is expensive. You may be better off using PNGs with these effects already composited. If you can use masks, use them.
  • Avoid gradients. Gradient fills, particularly radial gradients and gradients with translucency, are expensive. Use them sparingly.
  • Avoid full-frame animation. Animation that changes large areas of the display can slow down the animation - try to keep the percentage of the screen being updated as small as possible for any given frame.
  • Use tweening sparingly. Try to keep tweening to one or two small objects at a time. Don't use shape tweens unless absolutely necessary - they're extremely expensive to compute.
  • Avoid processing a lot of data in a single frame. Try queuing data in an array and process one item per frame. It complicates things a little bit, but will result in smoother operation and will avoid Actionscript timeouts.
  • Avoid lots of text. Lots of small text can be expensive to render. The chumby is meant to be read from a few feet away, so you really should be using large text anyway.
  • Don't do too many network fetches at the same time - Flash Lite limits the number of fetches intiated on the same frame, and the total number of fetches in progress at the same time. Considering queuing fetches and intiating new fetches when the previous ones complete.


Widget Environment

Widgets are given a set of parameters about the environment of the chumby: For example: 

this['_chumby_chumby_name']='TestChumby'
this['_chumby_widget_instance_id']='12121212-1212-1212-1212-121212121212'

The _chumby_chumby_name field contains the name of the chumby as assigned by the user. The _chumby_widget_instance_id is the unique GUID assigned that that particular instance of the widget in that particular channel for that particular user.

A widget that has a configuration dialog may create additional values - for instance, a horoscope widget might create: 

this['sign'] = 'Scorpio'

See [

Security

The widget has a security sandbox similar to a movie running in a browser plugin - an external source of content should have an appropriate crossdomain.xml file to expose content to the widget. For more information, please see the following Flash Player Technotes and Articles:

If you wish you widget to be compatible with "Virtual Chumby", in addition to fucntioning on the device itself, then you should build widgets so they can be loadMovie()'d into another movie at some level other than _level0 - this means you should try to avoid adding random properties to _level0, _global, or the built-in objects. If you wish to use _root, then you shold set _lockroot = true on the main timeline of your widget movie.

In general, widgets should be under 100K in size in order to reduce download time and use the minimum of storage in the device itself.

Uploading a Widget

You can upload a widget to our service which you can then use on your chumby. You will need to have the SWF for your widget, and a 80x60 pixel JPEG thumbnail image which represents your widget.

  • Create an account with chumby.com, if you haven't already
  • Log in - you will probably be redirected to a page that offers to let you register a chumby, or a list of your current physical chumbys
  • Select the "upload a widget" item from the "widgets" menu
  • Fill in the information

Widgets should be under 100K in size in order to reduce download time and use the minimum of storage in the device itself.

A widget uploaded using this mechanism will show up in the widget mix configuration, and can be selected just like any other widget, however, these uploaded widgets will only be accessible from your account. If you'd like your widget to be visible to everyone, turn on the "Public" radio button on the upload page - your widget will be reviewed by a Chumby employee.


Widget Configuration Dialog

Widgets on Chumby.com can have a configuration dialog used to save custom user settings. For example, a simple RSS reader widget would want to save the URL of the desired RSS feed using such dialog. This configuration dialog is a small Flash movie which only appears on the Chumby site, it does not appear on the Chumby device.

  • Configuration Flash files can be any version of Flash
  • Configuration Flash files must be 320x240
  • Parameters saved using the configuration dialog are automatically placed on the root timeline of the actual widget

For more information on creating Widget Configuration Dialogs, please refer to the Sample Banner Widget.

Widget durations

As an author, you're limited in the duration your widget can run, a maximum of 999 seconds (around 15 minutes). It it not possible (without special permission from Chumby) to author a widget that will run an indeterminate amount of time, or forever. The user, however, does have a few simple options to choose to make a widget run "forever" - select "Forever" from the "customize" menu when they add a widget, put the widget alone in a channel, or press the "stay" button in the Control Panel.

It it possible, however, to indicate that a widget has completed its operation before it would naturally time out. Simply set the variable "_chumby_widget_done" to "true" on the main timeline of your widget movie - the Control Panel will detect that and immediately expire the widget's timer.

Several developers have argued that their widgets are so important to users that they must be allowed to run forever. As policy, we've decided to have the user make that determination, not the author.

Example widgets

Here are some Flash source (.fla) files for various types of widgets:

Video

The optimal video settings for the production chumbys using Flash Lite 3 are:

  • Frame rate: 12fps
  • Video data rate: 220
  • Audio data rate: 32kbps (mono) or less
  • Width: must be less than or equal to 320
  • Height: must be less than or equal to 240

Most Common Problems

The most common problems with widgets that seem to fail on the chumby are:

  • The movie is the wrong version - Flash Lite 3 will not play Flash 9 movies.
  • The movie does not have sufficient security privileges - crossdomain files may not exist on the external content servers
  • The movie has the wrong dimensions - the widgets should be 320x240
Retrieved from "http://wiki.chumby.com/index.php?title=Developing_widgets_for_chumby&oldid=1777"