Difference between revisions of "Developing widgets for chumby"

From Chumby Wiki
Jump to: navigation, search
(→‎Most Common Problems)
(Adding haxe link)
 
(138 intermediate revisions by 31 users not shown)
Line 1: Line 1:
 +
See also [[Developing Widgets for Chumby: Insignia TV]]
 +
 +
See also [[Developing Widgets for Chumby: Liquid layout]]
 +
 +
See also [[Developing Widgets for Chumby: ActionScript 3]]
 +
 +
See also [[Developing Widgets for Chumby: Haxe]]
 +
 +
See also [[Developing Widgets for Chumby: Testing Widgets]]
 +
 +
See also [[Developing Widgets for Chumby: Sensor Access]]
 +
 +
See also [[Developing Widgets for Foo/Katamari]]
 +
 
=Summary=
 
=Summary=
−
Widgets for the Chumby are developed for Adobe Flash Lite 2, possibly with Flash Lite 2.1 being used in the future. Flash Lite 2 has a feature-set like that of Flash 7, meaning no Flash video (as the device alone isn't fast enough to play back video at a usable rate anyhow, though future implementations may allow for the use of the Alpha Chumby's processor's hardware accelerator for video).  
+
This page describes the development of widgets for the "Ironforge" production chumby hardware.
 +
Widgets for the Chumby are developed for Adobe Flash Lite 3.1. Flash Lite 3.1 has a feature-set based on desktop Flash Player 8.
  
−
As of right now,
+
The version of the Flash Lite Player is 3.1.5 as of November 2009.
−
* PNG and GIF image format aren't included. This could change in the future.
+
−
* Progressive JPEG support isn't included.
+
−
* It does not support video (Sorenson or On2) or Nelly Moser audio
+
−
* It does not support LocalConnection or XMLSocket.
+
−
* It does not support the Flash Communication Server
+
−
* There are no device fonts - all fonts must be embedded in the movie
+
−
* Playback of external audio files (MP3, etc) are not yet supported.
+
  
−
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.
+
Supported Features:
 +
* Flash video (FLV) encoded with ON2 and Sorenson Spark codecs
 +
* Video, NetStream and NetConnection classes
 +
* Internal PNG Transparent (PNG-24)
 +
* Internal GIF Transparent
 +
* External MP3 files
 +
* External PNG, GIF, non-progressive JPEGs
  
−
For efficiency's sake, Flash Lite downsamples images and embedded fonts, so avoid resizing images and small serif fonts, as detail will be lost.
+
Not supported:
 +
* Bitmap caching, bitmap effects or enhancements
 +
* Filters
 +
* Blend modes
 +
* Stylesheets
 +
* Non-default code pages
 +
* Focal gradients
 +
* Progressive JPEGs
 +
* External GIF Transparent
 +
* Non-round line caps and joins
  
−
Developers should avoid "play" or "repeat" buttons, and whenever possible opt for as little complex interactions with Chumby as possible; it is recommended that widgets need no human interaction. Text entry should also be avoided whenever possible, as the Chumby's text input system is crude at the moment, and most methods of touch screen text input are covered by patents and thusly won't be included in Chumby. (Most on-screen keyboards need more space than Chumby has, or are designed to operate with a stylus, which is not recommended for use with Chumby).
+
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 example, buttons should not be designed to have a separate 'over' state, since the Flash player can't determine when to switch in and out of that state.  Instead, button over states should be the same as their 'up' state.
  
−
=Performance and optimizations=
+
For efficiency's sake, Flash Lite downsamples images and embedded fonts, so avoid resizing images and small serif fonts, as detail will be lost.
  
−
The protoype chumby has a 266Mhz 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.
+
=Developer Environment=
 +
 
 +
While the chumby runs Flash Lite, it's actually a fairly normal Flash Player, and will run most of the content created for Flash 7, as well as a few of the newer features.  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 the 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 [http://www.adobe.com/products/flash/ Flash CS4 Professional])
 +
 
 +
You can also use the freeware [[FlashDevelop]].
 +
 
 +
=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 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.
Line 37: Line 70:
 
* '''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.
 
* '''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.
+
* '''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 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.
 
* '''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.
−
=Leaks=
 
−
Even Flash can be subject to memory leaks - the most common way to create a memory leak is to allocate '''XML''' objects as local variables.  For instance, the code
 
  
−
  function someFunction() {
+
* '''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.
−
    var x = new XML();
+
−
    x.onLoad = doSomething;
+
−
    x.load("http://some.url");
+
−
  }
+
  
−
...will result in a memory leak.  '''XML''' objects should be assigned to movieclip properties, and assigned to '''undefined''' when no longer used.
+
* '''Watch your variables.''' Properly declare (var variableName:Type;) and scope variables. Remove variables when no longer necessary (delete variableName;) to remove from memory.
  
−
Eventually, memory leaks will cause the chumby to crash, although not always in the offending widget.
+
=Widget Environment=
 +
Widgets are passed a set of properties on the _root timeline about the
 +
Chumby such as its name, the current channel, the user (you), the music source, information about the clock, and so forth.  These are set by control panel before each and every widget. The current parameters can be found in the [[Chumby Property Dictionary]] page.
  
−
Another class of leaks is "interval" leaks.  The use of '''setInterval()''' without corresponding '''clearInterval()''' will result in interval objects accumulating.  Since widgets can be unloaded at any time, it's possible that the opportunity to clear an interval may not happen.  Therefore, intervals should be avoided within widgets.  The typical symptom of an interval leak is the widget seeming to get too many interval callbacks, although eventually the CPU will get overloaded with too many interval firings, and the chumby becoming extremely sluggish.
+
For a simple example using the Chumby properties, refer to the following tutorial:
−
 
+
−
=Widget Environment=
+
−
Widgets are given a set of parameters about the environment of the chumby: For example:
+
  
−
this['_chumby_movie_url']='http://www.chumby.com/xml/movies/12345678-1234-1234-1234-123456781234'
+
*[[Chumby_Tutorials#Say Hello Using Parameters|Say Hello Using Parameters]]
−
this['_chumby_chumby_id']='87654321-4321-4321-4321-432187654321'
+
−
this['_chumby_chumby_name']='TestChumby'
+
−
this['_chumby_profile_id']='ABCDEF12-ABCD-ABCD-ABCD-ABCDEF12345678'
+
−
this['_chumby_profile_name']='Default'
+
−
this['_chumby_user_id']='FEDCBA9876-FEDC-FEDC-FEDC-FEDCBA98765432'
+
−
this['_chumby_user_name']='johndoe'
+
−
this['_chumby_widget_instance_href']='http://www.chumby.com/xml/widgetinstances/12121212-1212-1212-1212-121212121212'
+
−
this['_chumby_widget_instance_id']='12121212-1212-1212-1212-121212121212'
+
−
this['_chumby_base_url']='http://www.chumby.com'
+
  
−
A widget that has a configuration dialog may create additional values - for instance, a horoscope widget might create:
+
Note also that widgets are occasionally loaded into other movies (typically the "virtual chumby") - that means you cannot rely on the movie's background color to be used.  A widget should generally include a background graphic with the desired color or image behind all of the other graphics.
−
this['sign'] = 'Scorpio'
+
  
 
=Security=
 
=Security=
Line 79: Line 95:
 
* [http://www.adobe.com/devnet/flash/articles/fplayer_security.html Security Changes in Macromedia Flash Player 7]
 
* [http://www.adobe.com/devnet/flash/articles/fplayer_security.html Security Changes in Macromedia Flash Player 7]
  
−
One should also build widgets so they can be loadMovie()'d into another "virtual chumby" movie at some level other than _root - this means you should try to avoid adding random properties to _root or the built-in objects.
+
For help creating a crossdomain.xml file refer to this tutorial:
 +
*[[Chumby Tutorials#Creating a crossdomain.xml File|Creating a crossdomain.xml File]]
 +
 
 +
If you wish your widget to be compatible with "Virtual Chumby", in addition to functioning on the device itself, then you should build widgets so that they can be <code>loadMovie()</code>'d into another movie at some level other than <code>_level0</code> - this means you should try to avoid adding random properties to <code>_level0</code>, <code>_global</code>, or the built-in objects.  If you wish to use <code>_root</code>, then you should set <code>_lockroot = true</code> 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.
 
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.
  
−
=Testing a widget locally=
+
=Uploading a Widget=
−
The chumby itself has no substantial local storage, so you should not expect to store widgets on the chumby.  The protoype ''does'' allow write access to the built-in NAND Flash, however, there's isn't much free space and it will be entirely overwritten by firmware updates.  Future versions of the chumby will be read-only. If you want to run Flash movies on the device itself without uploading to the chumby servers, you'll need to do it from a USB mass storage device plugged into the back of the chumby.
+
−
 
+
−
* Get a USB dongle, formatted as VFAT, and put your Flash movie on the top level.
+
−
* Create a script file on the dongle called "'''debugchumby'''" with the contents
+
−
#!/bin/sh
+
−
/usr/bin/chumbyflashplayer.x -i /mnt/usb/<name of flash file>.swf
+
−
The file must use UNIX-style line terminations, and the last line must be terminated.
+
−
* Plug the dongle into the USB port on the back of your chumby
+
−
* Power it up - after the opening animation, your widget should run
+
−
 
+
−
=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.
 
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.
Line 100: Line 108:
 
* Create an account with chumby.com, if you haven't already
 
* 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
 
* 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 "my widgets" from the "my chumby" menu
+
* Select the "upload a widget" item from the "widgets" menu
−
* Click the "upload a widget" link
+
 
* Fill in the information
 
* 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.
 
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.  In the future, you'll be able to share these widgets with your friends, and even submit them to chumby for public access.
+
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. Important: Widgets should not play sound without user interaction. Your widget is unlikely to be shared publicly if it plays audio automatically, unless that's a user-set option that defaults to off.
  
−
=Using "virtual chumby"=
+
=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 a 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
  
−
The website has a mechanism for testing widgets in a Flash-based simulation of the widget playback of a real chumby.  You do not need a physical chumby to utilize this functionality.
+
For more information on creating Widget Configuration Dialogs, please refer to the [[Sample Banner Widget]] and the [[Widget Parameter Example]].
  
−
* Create an account with chumby.com, if you haven't already.
+
Widget parameters that are preceded by "_private" are not copied when a widget is sent or forwarded to another user - this allows user-specific configuration that is not passed on, such as passwords or other authentication tokens.
−
* 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 "my widget mixes" from the "my chumby" menu.
+
−
* Click the "virtual chumby for this widget mix" link for one of the widget mixes - you should have at least one called "Default".
+
  
−
You can add widgets to any given widget mix.  Both the real and virtual chumbys will check in for updated widget mixes every five minutes or so, or you can simple restart the Flash movie by reloading the virtual chumby's page.
+
=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.
  
−
=Example widgets=
+
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.
  
−
Here are some Flash source (.fla) files for various types of widgets:
+
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.
  
−
* [[Sample Clock Widget]]
+
=Example Widgets, Templates, and Components=
−
* [[Sample Binary Clock Widget]]
+
* Chumbian authored [[Example Widgets]]
−
* [[Sample RSS Widget]]
+
* [http://code.google.com/p/chumbydevelop Raff's FlashDevelop Template & Mini-Components]
−
* [[Sample Webcam Widget]]
+
* [http://www.aromatic.org/chumby Raff's older Chumby Widget code]
−
* [[Sample Banner Widget]]
+
* [http://www.discarded-ideas.org/chumby/photoframe PhotoFrame Widget w/source]
 +
* [http://code.google.com/p/chumby Chumby Radio Alarm Clock]
 +
* [http://gizmoware.net/chumby WryBread's sources]
 +
* [http://www.cyphergate.com/package-tracker.zip ApoXX's Package Tracker source]
 +
* [http://www.risacher.org/local/reference/swf Risacher's sources]
 +
* [http://www.hoffswell.com/flashdevelop/webcam-fd.zip KayakPete's WebCam source]
 +
* [http://files.chumby.com/dave/code/masterclock.rar djchumby's MasterClock source (FlashDevelop project)]
  
−
=Using SCP to Test Applications=
+
=Video=
  
−
Do you know the joke about the how to avoid getting lost and stranded on a forest trek? Bring some vermouth and gin with you, and if you get lost, sit on a tree stump and mix 3/4 cup gin with a 1/4 vermouth and from all around the forest, people will jump at you and say, "that's no way to mix a martini"... and you're saved!
+
The optimal video settings for the production chumbys using Flash Lite 3 are:
  
−
In a similar vein, I'm putting up how I was able to get a edit/compile/debug cycle going for the Chumby in the hopes someone who can improve it, "jumps out".
+
*Frame rate: 12fps
 +
*Video data rate: 220kbps
 +
*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
  
−
I was able to develop and test a few FlashLite apps using the method of placing a file on the USB key and moving and back and forth to the Chumby. This got old quickly, so I found this (somewhat) better workflow.
+
Avoid using the FLVPlayback component, as there are performance and untypical behavior bugs. Instead, use the Video, NetStream, and NetConnection objects. See [http://livedocs.adobe.com/flash/9.0/main/00001034.html Playing back external FLV files dynamically] in the Adobe ActionScript 2.0 documentation for information on how to use these objects.
−
Although SSH is available using the method above, so you can remotely open a shell from your development workstation, scp is not on the chumby.
+
  
−
* Create a VFAT formatted usb key as described above.
+
Refer to the following tutorial for the proper way to use .FLV video with the Chumby:
−
* Create a executable file on the dongle called "'''debugchumby'''" with the contents
+
−
#!/bin/sh
+
−
/bin/sshd
+
−
* Test that this is working by restarting the Chumby and ensure you can ssh into this as root from your development box.  Since root doesn't have a password, it's a good idea to remove the key and reboot after you finish development.
+
−
  ssh -l root chumby
+
−
You should get a root prompt at this point. Note, I've got dnsmasq running so my chumby has a 'name', it might just be an IP address for you (e.g. ssh -l root 192.168.0.XXX)
+
−
* Note where your usb key is mounted on the chumby - it's /mnt/usb for me (and likely for you)
+
−
* Put usb key back in your development box.
+
−
* Get a copy of '''scp''' either by compiling it for ARM-linux, or find a precompiled ARM version. For instance, for Zaurus, there an scp in the OpenSSH package: http://www.killefiz.de/zaurus/showdetail.php?app=1035. The files can be unzipped & untarred, eventually locating '''scp'''.
+
−
* place '''scp''' in the usb key root directory.
+
−
* place usb key back in the chumby, and then reboot the chumby again
+
−
* cd to /usr/bin on the chumby and create a symlink to the scp on /mnt/usb/. You could also just copy scp to /usr/bin, and I'm sure there's some clever way to set the path to have the /mnt/usb/scp, but I didn't bother (can be done with <code>PATH=$PATH:/mnt/usb</code>)
+
−
(on Chumby)
+
−
  cd /usr/bin
+
−
  ln -s /mnt/usb/scp /usr/bin
+
−
  cd /mnt/usb
+
−
  chmod +x scp
+
−
* from your development box terminal window, as sudo (or root), you should now be able to copy a file
+
−
  sudo scp <filename> chumby:
+
−
* from your chumby terminal window, you should now see the file you've just uploaded in /mnt/usb/<filename>
+
  
−
Good luck! This is much easier than moving the usb key back and forth!
+
*[[Chumby Tutorials#Playing .FLV Files Using NetConnection|Playing .FLV Files Using NetConnection]]
  
−
* Notes: sftp_server can be done similarly. This would be nicer because there's some nice GUI front-ends for it. however, I'm not able to get it working with the few minutes I've spent on it. I believe it has something to do with the sextopus ascii logo that is creating a problem for the sftp initiation, according to some googling on sftp_server failure modes. I'd like to temporarily remove this ascii art and see if it helps (where is it being called from?). Or maybe not...
+
=Cooperative Mode=
−
* Clearly you can save a step above by putting the scp on the key first. I thought it was worth getting ssh running first...
+
−
* Samba would be very nice, you could save the flash swf on the chumby right from Flash Professional.
+
−
* File Access Monitor to detect newly dropped SWF file, and automatically reinvoke Chumbyplayer.x
+
  
−
-hbchumby
+
Some widgets, such as videos and certain games, fall in a category that's best to run in "cooperative mode", meaning they don't expire after a set time period.  Instead, they run until they set the flag called _chumby_widget_done on the _root timeline.  The chumby control panel continuously looks for the _chumby_widget_done flag on the _root timeline of the widget.  When that variable is set to true, the control panel will advance to the next widget in the channel, even if the timeout hasn't been reached yet.
  
−
=Iterating With chumbyflashplayer.x=
+
A user can set any widget to run "forever" if she chooses to, but if you develop a widget that would run better in cooperative mode, you may request that it run that way by default.
  
−
Now that you can move files to the Chumby easily, how can you iterate?
+
Before Chumby sets your widget to cooperative mode, it must meet some criteria.  It must set the aforementioned flag in the following circumstances:
−
What I did is create a similar script on the Chumby (in <code>/mnt/usb</code>) that kills the current Chumby player and restarts it with my test application:
+
 +
# If the widget first comes up and the user doesn't interact with it at all for 20 seconds.
 +
# If the user already interacted, but there is a period of inactivity since the last interaction (typically 30 seconds).
 +
# If the widget is done (video complete or game over, for example) and the user does not start another game/video within 10 seconds.
 +
 +
In the case of #2 above, it's possible (but not required) to bring up an overlay 5 seconds before the timeout saying something like "to stay on this widget, tap the screen." 
  
−
  #!/bin/sh
+
Once you set the flag to true, don't assume the widget will necessarily stop running. For example, if it's the only one in the channel, it will stay active.
−
  rm /tmp/flashplayer_started
+
−
  killall chumbyflashplayer.x
+
−
  /usr/bin/chumbyflashplayer.x -i mytestapp.swf
+
  
−
The chumby has a watchdog timer that looks for lockups in the FlashLite Player or Control Panel - deleting <code>/tmp/flashplayer_started</code> prevents it from relaunching the player.
+
Even non-cooperative-mode widgets can set the _chumby_widget_done flag to true in order to time-out early.
  
−
-hbchumby
+
'''To enable cooperative mode:''' Please contact Chumby Industries after uploading your widget.
  
−
=Flash Access to Sensors=
+
=Sending Email=
−
The Chumby Flash Player has some ASnative calls to access the various sensors
+
Chumby Industries can enable email sending for certain widgets that have good reason to do so.  By default, this functionality is not available to widgets.  Once enabled, plain text emails can be sent to the address that Chumby has on file for the owner of the device.
  
−
'''NOTE''': These are very likely to change in future releases - use at your own peril.
+
The code sample below shows how the email request is sent to the server.  This code snippet makes use of variables that the control panel writes to the _root timeline of each widget when it starts, such as the _root._chumby_widget_instance_id.
 +
<pre>
 +
var baseURL:String = (_root._chumby_base_url == undefined) ? "http://www.chumby.com" : _root._chumby_base_url;
 +
var url:String = baseURL+'/xml/email/'+_root._chumby_widget_instance_id;
 +
var emailXML:XML = new XML('<email subject="The Subject">Message body goes here.</email>');
 +
emailXML.sendAndLoad(url,response_xml);
 +
</pre>
  
−
==Touchscreen==
+
=Detecting/filtering based on GeoIP=
  
−
Normally, the touchscreen is calibrated by the user using the Control Panel, however, raw coordinates are available.
+
GeoIP is a service chumby is providing to our partners and developers. It provides country look-up based on IP address.  We are using the database [http://www.maxmind.com/app/geolitecountry provided] by [http://www.maxmind.com MaxMind].  There is another service [http://iplocationtools.com/index.php here].
  
−
_rawX = ASnative(5,10); // get the last raw touchscreen X coordinate
+
The requests look like:
−
_rawY = ASnative(5,11); // get the last raw touchscreen Y coordinate
+
−
trace('x:'+_rawX()+', y:'+_rawY());
+
  
−
==Bend Sensor==
+
http://content.chumby.com/geoip?ip=64.73.214.3 # uses IP from param
 +
or
 +
http://content.chumby.com/geoip                # uses IP of sender
  
−
The bend sensor is currently used by the Control Panel to bring up the controls.
+
The response will resemble:
  
−
  _bend = ASnative(5,14); // get the "last" bend sensor reading
+
  <?xml version="1.0"?>
−
  trace(_bend());
+
<geoip ip="64.73.214.3" iso_country="US">
 +
  <ack>This product includes GeoLite data created by MaxMind, available from http://maxmind.com/</ack>
 +
  <license>http://geolite.maxmind.com/download/geoip/database/LICENSE.txt</license>
 +
  <link>http://geolite.maxmind.com/download/geoip/database/GeoIPCountryCSV.zip</link>
 +
  </geoip>
  
−
_bent = ASnative(5,25); // get the "bent" flag (0/1)
+
=Most Common Problems=
−
trace(_bent());
+
  
−
_bendAverage = ASnative(5,28); // get the 10-second running average of the bend sensor
+
The most common problems with widgets that seem to fail on the chumby are:
  
−
==Light Sensor==
+
* 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
  
−
_light = ASnative(5,15); // get the ambient light sensor reading
+
=International support=
−
trace(_light());
+
In order to be accessible and operable by the ensemble of the users, the widgets MUST support characters outside of ASCII-7. Otherwise, characters like "é, ê, ñ, À, Œ, ç" will not be displayed, resulting on unreadable texts.
  
−
==Display==
+
The solution is to use UTF-8 for encoding, and insert fonts containing commonly used characters in principal languages such as French, German, Spanish and so. The [http://dejavu-fonts.org/ DejaVu fonts] provide such support.
  
−
This allows you turn off the display, perhaps for power reasons.
+
This affect all the widgets deployed on a chumby : RSS reader, social widgets (Facebook, Twitter, FriendFeed…), corporate widgets and so.
  
−
_getLCDMute = ASnative(5,19); // get the value of the LCD "mute"
+
See the [http://forum.chumby.com/viewtopic.php?id=4155 forums] for initial discussion.
−
_setLCDMute = ASnative(5,20); // set the value of the LCD "mute"
+
−
trace(_getLCDMute());
+
−
_setLCDMute(1);
+
−
 
+
−
The "brightness" values are used by the Linux kernel to automatically dim the display. There are 16 subranges, each with its own threshold
+
−
and associated brightness values.
+
−
 
+
−
_getBrightnessForRange = ASnative(5,21); // get the display brightness for the indexed light level  range
+
−
_setBrightnessForRange = ASnative(5,22); // set the display brightness for the indexed light level range
+
−
for (i=0;i<16;i++) trace(_getBrightnessForRange(i));
+
−
_setBrightnessForRange(5,255);
+
−
 
+
−
_getBrightnessThresholdForRange = ASnative(5,23); // get the threshold for the indexed light level range
+
−
_setBrightnessThresholdForRange = ASnative(5,24); // set the threshold for the indexed light level range
+
−
trace(_getBrightnessThresholdForRange(5));
+
−
_setBrightnessThresholdForRange(5,24);
+
−
 
+
−
==Speaker==
+
−
 
+
−
This cuts off audio to the built in speakers, but still allows audio through the headphone jack.
+
−
 
+
−
_getSpeakerMute = ASnative(5,17);
+
−
_setSpeakerMute = ASnative(5,18);
+
−
trace(_getSpeakerMute());
+
−
_setSpeakerMute(1);
+
−
 
+
−
==DC Power==
+
−
 
+
−
This tells you whether the device is connected to the DC power adaptor, or if it's running on the 9V battery.  Currently, the Control Panel will turn off the display if the device is running on battery.
+
−
 
+
−
_dcPower = ASnative(5,16);
+
−
trace(_dcPower());
+
−
 
+
−
=Most Common Problems=
+
−
 
+
−
The most common problems with widgets that seem to fail on the chumby are:
+
−
 
+
−
* The movie is the wrong version - FlashLite 2 will not play Flash 8 or Flash 9 movies.
+
−
* The movie does not have sufficient security privileges - crossdomain files may not exist on the external content servers
+
−
* The movie is not written to be loaded into another movie - this is often the case with movies with preloaders that reference _root or _level0 - if you need something globally accessible, consider making it a property of Object.
+
−
* The movie uses device fonts - be sure all the required fonts are embedded
+
−
* The movie has the wrong frame rate - the chumby wants widgets to be 12fps
+
−
* The movie has the wrong dimensions  - the widgets should be 320x240
+
−
* The movie contains Flash Video - FlashLite 2 does not support Flash Video
+

Latest revision as of 14:57, 17 July 2014

See also Developing Widgets for Chumby: Insignia TV

See also Developing Widgets for Chumby: Liquid layout

See also Developing Widgets for Chumby: ActionScript 3

See also Developing Widgets for Chumby: Haxe

See also Developing Widgets for Chumby: Testing Widgets

See also Developing Widgets for Chumby: Sensor Access

See also Developing Widgets for Foo/Katamari

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.1. Flash Lite 3.1 has a feature-set based on desktop Flash Player 8.

The version of the Flash Lite Player is 3.1.5 as of November 2009.

Supported Features:

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

Not supported:

  • Bitmap caching, bitmap effects or enhancements
  • Filters
  • Blend modes
  • Stylesheets
  • Non-default code pages
  • Focal gradients
  • Progressive JPEGs
  • External GIF Transparent
  • Non-round line caps and joins

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 example, buttons should not be designed to have a separate 'over' state, since the Flash player can't determine when to switch in and out of that state. Instead, button over states should be the same as their 'up' state.

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 most of the content created for Flash 7, as well as a few of the newer features. 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 the 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 CS4 Professional)

You can also use the freeware FlashDevelop.

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.
  • Watch your variables. Properly declare (var variableName:Type;) and scope variables. Remove variables when no longer necessary (delete variableName;) to remove from memory.

Widget Environment

Widgets are passed a set of properties on the _root timeline about the Chumby such as its name, the current channel, the user (you), the music source, information about the clock, and so forth. These are set by control panel before each and every widget. The current parameters can be found in the Chumby Property Dictionary page.

For a simple example using the Chumby properties, refer to the following tutorial:

Note also that widgets are occasionally loaded into other movies (typically the "virtual chumby") - that means you cannot rely on the movie's background color to be used. A widget should generally include a background graphic with the desired color or image behind all of the other graphics.

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:

For help creating a crossdomain.xml file refer to this tutorial:

If you wish your widget to be compatible with "Virtual Chumby", in addition to functioning on the device itself, then you should build widgets so that 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 should 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. Important: Widgets should not play sound without user interaction. Your widget is unlikely to be shared publicly if it plays audio automatically, unless that's a user-set option that defaults to off.

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 a 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 and the Widget Parameter Example.

Widget parameters that are preceded by "_private" are not copied when a widget is sent or forwarded to another user - this allows user-specific configuration that is not passed on, such as passwords or other authentication tokens.

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, Templates, and Components

Video

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

  • Frame rate: 12fps
  • Video data rate: 220kbps
  • 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

Avoid using the FLVPlayback component, as there are performance and untypical behavior bugs. Instead, use the Video, NetStream, and NetConnection objects. See Playing back external FLV files dynamically in the Adobe ActionScript 2.0 documentation for information on how to use these objects.

Refer to the following tutorial for the proper way to use .FLV video with the Chumby:

Cooperative Mode

Some widgets, such as videos and certain games, fall in a category that's best to run in "cooperative mode", meaning they don't expire after a set time period. Instead, they run until they set the flag called _chumby_widget_done on the _root timeline. The chumby control panel continuously looks for the _chumby_widget_done flag on the _root timeline of the widget. When that variable is set to true, the control panel will advance to the next widget in the channel, even if the timeout hasn't been reached yet.

A user can set any widget to run "forever" if she chooses to, but if you develop a widget that would run better in cooperative mode, you may request that it run that way by default.

Before Chumby sets your widget to cooperative mode, it must meet some criteria. It must set the aforementioned flag in the following circumstances:

  1. If the widget first comes up and the user doesn't interact with it at all for 20 seconds.
  2. If the user already interacted, but there is a period of inactivity since the last interaction (typically 30 seconds).
  3. If the widget is done (video complete or game over, for example) and the user does not start another game/video within 10 seconds.

In the case of #2 above, it's possible (but not required) to bring up an overlay 5 seconds before the timeout saying something like "to stay on this widget, tap the screen."

Once you set the flag to true, don't assume the widget will necessarily stop running. For example, if it's the only one in the channel, it will stay active.

Even non-cooperative-mode widgets can set the _chumby_widget_done flag to true in order to time-out early.

To enable cooperative mode: Please contact Chumby Industries after uploading your widget.

Sending Email

Chumby Industries can enable email sending for certain widgets that have good reason to do so. By default, this functionality is not available to widgets. Once enabled, plain text emails can be sent to the address that Chumby has on file for the owner of the device.

The code sample below shows how the email request is sent to the server. This code snippet makes use of variables that the control panel writes to the _root timeline of each widget when it starts, such as the _root._chumby_widget_instance_id. 

var baseURL:String = (_root._chumby_base_url == undefined) ? "http://www.chumby.com" : _root._chumby_base_url;
var url:String = baseURL+'/xml/email/'+_root._chumby_widget_instance_id;
var emailXML:XML = new XML('<email subject="The Subject">Message body goes here.</email>');
emailXML.sendAndLoad(url,response_xml);

Detecting/filtering based on GeoIP

GeoIP is a service chumby is providing to our partners and developers. It provides country look-up based on IP address. We are using the database provided by MaxMind. There is another service here.

The requests look like: 

http://content.chumby.com/geoip?ip=64.73.214.3 # uses IP from param
or
http://content.chumby.com/geoip                # uses IP of sender

The response will resemble: 

<?xml version="1.0"?>
<geoip ip="64.73.214.3" iso_country="US">
  <ack>This product includes GeoLite data created by MaxMind, available from http://maxmind.com/</ack>
  <license>http://geolite.maxmind.com/download/geoip/database/LICENSE.txt</license>
  <link>http://geolite.maxmind.com/download/geoip/database/GeoIPCountryCSV.zip</link>
</geoip>

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

International support

In order to be accessible and operable by the ensemble of the users, the widgets MUST support characters outside of ASCII-7. Otherwise, characters like "é, ê, ñ, À, Œ, ç" will not be displayed, resulting on unreadable texts.

The solution is to use UTF-8 for encoding, and insert fonts containing commonly used characters in principal languages such as French, German, Spanish and so. The DejaVu fonts provide such support.

This affect all the widgets deployed on a chumby : RSS reader, social widgets (Facebook, Twitter, FriendFeed…), corporate widgets and so.

See the forums for initial discussion.

Retrieved from "http://wiki.chumby.com/index.php?title=Developing_widgets_for_chumby&oldid=3518"