This Is Not a Blog

BBX Python: Self-contained Demo App

2011-11-29T18:12:00Z

Earlier today I wrote about how it turns out that the Tablet OS (2.0.0 beta or later) actually recognizes Python as a direct "entry point" for apps, as it does for apps built using AIR or the Native SDK (WebWorks apps use the AIR entry point at this time).

With the original crude launcher, we'd developed a small set of experiments and demonstration scripts, which you had to copy over the network to "documents/scripts", with the bbxrun.py file sitting above to let you select which one to run.

I've taken the whole mess and packaged it up using the new approach, with a signed .bar file up so you can try it out for yourself if you'd like. (Download link is at the end of this post.)

Some of the demo scripts are purely experimental or proofs-of-concept, without even a visible UI (except a blank screen) while they run. Some do something visible in the UI or interact in other ways. Following is a brief description of each.

Name	Description
deviceinfo.py	Dispay a dialog with "device information" such as PIN and serial number.
display_info.py	Dump information about attached displays (LCD and HDMI) to log file.
event_test.py	For 6s get screen, navigator, and virtual KB events, output to log file.
geotrace.py	For 60s get GPS updates and output to log file, with satellite count.
image_test.py	For 3.5s blast small bitmap scaled to 1/4 size to screen.
notifications.py	Generate several notifications in different styles, one being interactive.
os_info.py	Write data from Python "os" package to log file (e.g. PID, current directory).
play_sound.py	Play a brief WAV file.
psychedelic.py	For 5s randomly flash the screen different colours 25 times per second.
python_info.py	Write data from Python "system" package to log file (e.g. version, path).

The log file the demo app writes to is the usual in-sandbox file (under logs/log) but once you exit the app using the Cancel button it copies it to documents/ca.microcode.bbxpython.demo.log so you can view it on your computer. (It should be possible to respond to the NAVIGATOR_EXIT event by doing the same thing in a later update.)

I should be able to include the font_test.py demo in a few days after I get a chance to refactor and optimize it a bit.

The demo app is available in the downloads folder as bbxpython-demo-x.x.x.x.bar with whatever version it happens to be at when you download it.

Source code code is in the bbx-python bitbucket repository, or you could just look in the .bar file since this version doesn't use compiled bytecode, but .py source files.

Future updates won't result in this page changing... I'll start including in-app documentation and/or a separate page in the wiki where it can more easily be maintained.

As usual, follow the news on Twitter using hash tag #bbx-python or follow me at @peter9477.

BBX Python: Direct Entry Point!

2011-11-29T12:06:00Z

Okay, this is just too cool not to mention right away!

Jeff Kehres from RIM has been following the progress on and off, and pointed out today the existence of the blackberry-pythonpackager that's already included in the NDK tools.

I therefore herewith present the classic tiny "hello, world" app for the PlayBook, written in Python and with output going only to the appdata/logs/log file (to which stdout is redirected by default).

print "hello, world"

Okay, and let's make a nice icon for it (and by "nice", I mean only "really small file size"):

Now we need a bar-descriptor.xml file. I'll include one stripped of comments and whatever else I can find that's optional. Note the line with entry="true" type="Qnx/Python" as that right there is the magic key to the kingdom. Also you do need the run_native action (including the system="true" part if you'll ever sign the app for distribution):

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<qnx xmlns="http://www.qnx.com/schemas/application/1.0">
    <id>ca.microcode.bbxpython.m2</id>
    <name>BBXPyTiny</name>
    <versionNumber>0.0.1</versionNumber>
    <description>BBX-Python Tiny App</description>
    <author>Your Name Here</author>
    <authorId>gYAUseYour_OwnIdvPY</authorId>
    <initialWindow>
    <systemChrome>none</systemChrome>
    <transparent>false</transparent>
    </initialWindow>
    <icon><image>icon.png</image></icon>
    <asset path="icon.png">icon.png</asset>
    <asset path="main.py" entry="true" type="Qnx/Python">main.py</asset>
    <action system="true">run_native</action>
</qnx>

We need to build and deploy it:

c:\dev\bbxpy\tiny> bbndk-env.bat
...
c:\dev\bbxpy\tiny> blackberry-pythonpackager -devMode test.bar bar-descriptor.xml
Info: Package created: test.bar

c:\dev\bbxpy\tiny> blackberry-deploy -installApp -package test.bar -device PBIP -password PBPASS
Info: Sending request: Install
Info: Action: Install
Info: File size: 2414
Info: Installing ...
Info: Processing 2414 bytes
actual_dname::ca.microcode.bbxpython.m2.testDev_bxpython_m2f3b6aa2c
actual_id::testDev_bxpython_m2f3b6aa2c
actual_version::0.0.1.0
result::success

Note the file size... it's always nice when you don't need a lot of setup and boilerplate code in the way. Of course, it doesn't actually do much, but we can bloat it up a bit later.

That worked because I had a debug token (from which I got my authorId info for the bar-descriptor.xml file above) already installed on my tablet. The alternative would be not to use -devMode during packaging, but use your code signing key instead, with the -sign option and info about your keystore and password.

Here it is installed and ready to run, as the last icon in the list:

Run it, and you briefly get an all-white screen and then it exits.

Let's log in via SSH using PuTTY and see the aftermath:

Using username "devuser".
Authenticating with public key ...
$ cd /accounts/1000/appdata/ca.microcode.bbxpython.m2.testDev_bxpython_m2f3b6aa2c
$ cd logs
$ cat devmode_exitcode.txt
0
$ cat log
hello, world

And what's the installed app code folder look like?

$ ls -l /apps/ca.microcode.bbxpython.m2.testDev_bxpython_m2f3b6aa2c/
total 16
drwxrwx---   2 apps      dev1           4096 Nov 29 12:28 META-INF
drwxrwx---   2 apps      dev1           4096 Nov 29 12:28 python
$ ls -l /apps/ca.microcode.bbxpython.m2.testDev_bxpython_m2f3b6aa2c/python
total 5
-rw-rw----   1 apps      dev1            710 Nov 29 12:28 bar-descriptor.xml
-rw-rw----   1 apps      dev1            796 Nov 29 12:28 icon.png
-rw-rw----   1 apps      dev1             22 Nov 29 12:28 main.py

So that pretty much eliminates the need for the native stub launcher code that started this whole thing off for me. Hasta la vista, baby. It's over for us: I've found someone younger... and 25K thinner.

Thanks for sharing that tip, Jeff! I'm happy not to spend time on improving the build tools for now, and this cuts out one more bit of complexity. Python should always look this clean and simple!

One note to any rookies: Python actually compiles to bytecode, which is stored in .pyc files. It's unlikely you'd want to include your entire app in source form (.py files), so for any real app you'll among other things want to compile the .py files to .pyc at packaging time and include those instead of a mass of .py files. The package will be smaller and startup time will be shortened a bit as the runtime won't be compiling your code each time the app launches. I'll go into more detail on this whole area in later posts.

BBX Python: FreeType2 Fonts

2011-11-27T00:05:00Z

This is definitely not ready for serious use, but I thought I'd share a screenshot with the first text rendering support for BBX-Python.

The code's too crude to commit yet, and it's ridiculously sluggish at the moment, since I'm using FreeType to render each character and then -- in Python! -- copying over each pixel into a libscreen pixmap buffer which is then blitted onto the screen. One character at a time.

But hey! I've got some text output!

Here's the top-level code which generated that screen:

screen.fill_screen(0x337733)

xpos = 20
draw_image(xpos, 15, b'shared/documents/scripts/logo.png')

color = 0xff5511
fontsize = 48
leading = 70
ypos = 200
for text in [
    'BBX-Python!',
    'The time is %s' % datetime.datetime.now(),
    'Python ' + sys.version.split('\n', 1)[0],
    'Visit http://microcode.ca/bbx-python/ to learn more.',
    ]:
    draw_text(xpos, ypos, text, fontsize=fontsize, color=color)
    ypos += leading
    fontsize = 36
    color = 0xffffff

BBX Python: Quick Update #1

2011-11-24T23:31:00Z

Here are a few quick notes on what's happened with BBX-Python since the last update.

Core: Launcher

I stripped almost everything out of the launcher, leaving it as just the bare bones required to initialize the Python interpreter and run the main script.

That meant taking out all the OpenGL code, along with everything to do with screen contexts, event handling, and other BPS stuff.

This brought it down to under 24K for the native code portion of the launcher, but had the unfortunate side effect of triggering the OS app police, which terminates any app which doesn't post a window update within 30s of launching.

User Interface

I looked into using PyOpenGL but it appears we have only OpenGL ES on the PlayBook, and the author of PyOpenGL (Mike Fletcher) tells me that it's likely non-trivial to modify/port PyOpenGL to work with it. The two are apparently quite similar, but have enough differences that it could be quite a pain. I'll leave this on the back-burner until later, or until I learn more.

In the interim, we've got the QNX Dialog support, and full Notifications support. The dialog demo code is doing system modal dialogs, which is a pain, but I wouldn't expect it's hard to make that non-modal at which point it should prove to be quite usable.

I've also integrated the minimal app requirements into bbxrun.py, so that it no longer times out after 30s and gets turfed by the OS.

It shouldn't be a huge amount of work to get some basic bitmap stuff going with the img/img.h functions, so that's high on the list of todos. With some third-party bitmap library (PIL?), either pure Python or ported to QNX, we could probably do some decent basic UIs using just bitmaps.

Libraries

I've added some ctypes wrapper modules for much of bps/bps.h (and siblings) and all of screen/screen.h. This allowed doing the "minimal app requirements" above: create screen context, window, buffer, post one update to window.

There's code integrated into the latest bbxrun.py to set this up, and simplistic demo code in psychedelic.py to rapidly flash the screen different colours.

The bps and screen modules also allow event handling, so I threw in an event_test.py quickly, just to verify it will work. No real problems with that, but it will need an Event class and subclasses added to wrap all these events. No idea how people actually write apps using the low-level C stuff this is all built on... or maybe nobody really does. Anyway, the Python version will be much easier on the eyes, brain, and fingers.

Next Priorities

I think I'll probably attack the following things next, in order:

Basic bitmap support through img/img.h, at least part of it. Goal will be to display at least full-screen bitmaps, preferably including smaller bitmaps at arbitrary positions. Could go pretty far with just that.
Event class and a core App class that can provide the basic event-handling loop, and allow the rest of the app to be written as event-driven code in conventional fashion. This stuff is mostly tedious but straightforward. I'll need to add some more ctypes wrappers; for now I'm doing that manually but in the long run it will be better handled with some automated conversion of the header files. The ctypeslib can do that, though it's alpha-stage code and my first attempts at using it failed for various and sundry reasons, when tried on QNX, Windows, or Linux. I've done this before for other projects, and it's not terribly hard; it should be even easier in this case because the QNX header files are quite consistent and clean.
With those two things, one could actually write some simple apps. That will push the focus back to the BBX-Python core and the launcher, plus tools. Next step will be to make the launcher able to run code specified in an environment variable (that gets into the MANIFEST.MF Entry-Point), and make a basic tool to generate .bar files combining the canned launcher code plus the developer's Python code. That would probably constitute completion of the first phase of this project...

What else? Now's a good time to start chiming in with some comments here, or discussion on the #bbx-python IRC chat on freenode.net (go to webchat.freenode.net if you don't have an IRC client installed, and join the #bbx-python channel.

Alternatively, follow the #bbx-python hash tag on Twitter to stay abreast of progress.

Note that one purpose of this project is to make visible the existence of a potential Python/PlayBook community: if you're interested but staying silent, you're working against your own interests! Speak up and be seen!

BBX Python: Next Steps

2011-11-21T08:42:00Z

My recent posts have talked about running Python 3.2 on the PlayBook. While all versions of the PlayBook OS have used Python internally [1], the beta 2.0 OS is the first to have a Python interpreter with read permissions set such that apps can access it... for now, anyway. (Unfortunately we have no guarantees that it will remain accessible, but your input to RIM will help influence decisions about that.)

This project is in an early stage, and could go any number of directions (perhaps all at the same time).

User Interfaces

Rob Paskowitz is taking a stab at hooking up the Qt port through the LGPL PySide bindings.

There's also an SDL port, so getting Pygame running is a definite possibility.

Another step for Flash-loving people would be to use an ANE layer from an AIR app replacing the Python launcher, so that a Flash user interface could be hooked to "back-end" business logic written in Python. May sound crazy to some people, but from a testability point of view, Python is potentially unmatched, while from a UI point of view Flash has a lot of things working for it.

I'm personally not highly concerned about the UI, partly because I can leave that to others, partly because I have some confidence we'll eventually see RIM release their PyCascadesSDK package (presumably layered on Qt as well) and the issue will be moot, and partly because I'm better at the plumbing...

The Plumbing

One idea I have is to simplify the "native stub" launcher code so that it doesn't even bother with initializing anything aside from Python. Maybe it would still have to do a bps_initialize() and a few basics, but I could skip the screen stuff. It would invoke a Python script named probably in an environment variable (specified in MANIFEST.MF), and that's it. Anything else would be done through libraries, from Python.

Doing this would allow me to prepare a simple app packager, which would itself be in Python, which would combine the native stub, the Python code, and a generated MANIFEST.MF file together into a .bar file which would be a complete self-contained app. For now it could rely on having one of the other SDKs installed (Native, AIR, or WebWorks) for the code-signing capability, but aside from that it appears possible to do already. A couple of the required entries in a MANIFEST.MF file appear to be "opaque" hashes of some kind (the short ones like Package-Version-Id) but I believe those could be reverse-engineered if necessary, and the rest is straight-forward. (If you have any knowledge of those hashes, aside from the obvious SHA512 ones, please let me know.)

Third-Party Native Extensions

While any 3.2-compatible pure Python packages will work perfectly and without change in this environment, there are also many interesting third-party libraries which include some native code. While I expect many of them will work without much problem, there's still a need to compile them with the NDK to make binaries available, and to test them out. First one I'd like to see, personally, is Greenlet though I don't even see that they've built it for Python 3.2 yet.

We might also just want to start compiling a list in the repository's wiki (which anyone with a free bitbucket account can edit). Which such packages would provide functionality that would really add value on the PlayBook? Which won't work that well, because of memory requirements, performance issues, or maybe other dependencies that aren't yet supported under Python 3.2?

Documentation

There's hardly enough here yet to document, but if there's one thing that's been the downfall of many an otherwise-promising open source project, it's documentation. I noticed I'm already short one key thing: a license! For the record, I'm planning on using MIT [2] or maybe BSD [3] unless there's a good reason to use something else (such as, maybe RIM insists on Apache 2.0, as I want to keep this compatible with their plans).

I think I've made a reasonable start already, for a project that's only four days old! Still, what I think needs to be documented isn't the same as what some other people think needs to be documented. Are you being held back from participating because something's missing? What is it?

BBX-specific Packages

This one is an interesting area. RIM's already got a whole batch of libraries in the 2.0 beta, with no major issues seen yet with any of them. They're wholly unsupported, of course, and as I've mentioned earlier we've got no guarantee that RIM will continue to expose these for us to use. Here's a few of the packages available so far:

Name	Description
qnx.audio	Play and record WAV/RIFF files
qnx.device	Access device properties: versions, PIN, serial number (requires read_device_identifying_information)
qnx.dialog	PPS dialog service: alerts, file browse, login, popup, prompt, etc.
qnx.geolocation	PPS geolocation service (GPS, etc.)
qnx.mmaudioplayer	Control playback of an audio file (MP3 or other)
qnx.notification	Display notification messages
qnx.pps	General-purpose interface to PPS objects

Those were presumably written to be used by RIM's own code, however, and third-party apps may have other needs. Packages could be written to add useful new functionality. One option is to use the ctypes module to wrap existing dynamically loaded (shared) libraries (.so files). This is relatively straightforward if you have the header file for the library, and provides a very quick way to expose native functionality to Python. You could do useful work in this area if you know C well, even if you're just starting to learn Python.

Get Involved!

This project represents a real frontier for hackers (in the old-style meaning of the term: those who find cool ways to make technology behave). The PlayBook is being revealed as an awesome and versatile platform, and will be an excellent place for high-performance [4] Python programs to run as apps. Now's a good time to get involved, so you can have a direct influence on the direction this initiative will take.

Footnotes:

[1]	Python 2.7, used for either the system updates and/or when installing apps.

[2]	The MIT License: http://www.opensource.org/licenses/mit-license.php

[3]	The BSD License: http://www.opensource.org/licenses/bsd-license.php

[4]	Benchmarking reports 11330 pystones/sec, in line with the 1GHz clock speed, compared to my 2.4GHz Intel CPU at 29000 pystones/sec

BBX Python: Project Site

2011-11-19T18:19:00Z

In case you've been following the work on a native launcher for Python apps on BBX (PlayBook), you'll be happy to I've just set up a BBX-Python project web page with the code hosted the bbx-python bitbucket repository.

There's a downloads folder (not using the Bitbucket one... wouldn't let me upload because of some Amazon service crashing apparently), with a first release of the launcher. Also a wiki page with Quick Start instructions to get you going, and some sample code.

One fellow (artoo) in the IRC chat (#bbx-python on freenode.net) has already written an extended launcher in Python, which uses a "popup" dialog to show you a list of other Python scripts from which you can select one to run.

BBX Python: Progress, Stage Two

2011-11-18T20:49:00Z

So without much more effort today, I'm got it running a separate script (bbxmain.py) that is bundled into the .bar file. Again, the heart of things is trivial, just these two lines:

FILE * bbxmain = fopen("app/native/bbxmain.py", "r");
PyRun_SimpleFile(bbxmain, "__main__");

For the record, here's the first script I wrote:

import sys, time

with open('/accounts/1000/shared/misc/bbxmain.out', 'a') as f:
    f.write('-' * 40)
    f.write(' %s\n' % time.time())
    for i, arg in enumerate(sys.argv):
        f.write('arg %s: %s\n' % (i, arg))
    f.write("It's alive!\n")
    f.write('__name__ is %s\n' % __name__)
    f.write('myver is %s\n' % sys.myver)

if __name__ == '__main__':
    print('Hello, world!')

And here's the output in that file in shared/misc:

---------------------------------------- 1321663133.906571
arg 0: com.example.study_poc.testDev_e_study_pocc037301d
It's alive!
__name__ is __main__
myver is BBX Python! v3.2.1 (default, Sep  1 2011, 14:08:17) [GCC 4.4.2] on qnx6

If you know Python and don't recognize sys.myver, don't worry... it's just a string built using an earlier call to PyRun_SimpleString() in my setup code from an older experiment, from sys.version and sys.platform. I've got the same thing displayed as output in the OpenGL screen context:

Join me on #bbx-python on freenode.net if you're interested in following this, add add a comment to this post, or follow @peter9477 on Twitter. Thanks!

BBX Python: Proof Of Concept

2011-11-18T01:37:00Z

Short post, since it's late.

Python on the PlayBook. What will be BBX-Python, some day...

So I wrote an app. First time using the Tablet OS Native SDK so lots of learning curve to climb with Momentics (the IDE) and some of its warts. Generally it was way better than I'd expected actually, and the warts are the sort of thing you work around then gradually forget they're even there.

The app for now pretty much consists of the following code:

fprintf(stderr, "py_initialize\n");
Py_VerboseFlag = 1;
Py_Initialize();

// ... other stuff in a loop waiting for the end of the world

Py_Finalize();

There's a bit more to it than that, but nothing that's relevant to the Python aspect. I did have to set up an environment variable to point to the library, so there's an "LD_PRELOAD=/usr/lib/libpython3.2m.so.1.0" somewhere, too.

The beautiful thing is that it just worked. Here's the output, courtesy of the one debug line above and the output triggered by the verbose flag:

py_initialize
# installing zipimport hook
import zipimport # builtin
# installed zipimport hook
import encodings # directory /usr/lib/python3.2/encodings
import encodings # precompiled from /usr/lib/python3.2/encodings/__init__.pyc
import codecs # precompiled from /usr/lib/python3.2/codecs.pyc
import _codecs # builtin
...
import bisect # precompiled from /usr/lib/python3.2/bisect.pyc
dlopen("/usr/lib/python3.2/lib-dynload/_bisect.so", 2);
import _bisect # dynamically loaded from /usr/lib/python3.2/lib-dynload/_bisect.so
dlopen("/usr/lib/python3.2/lib-dynload/_heapq.so", 2);
import _heapq # dynamically loaded from /usr/lib/python3.2/lib-dynload/_heapq.so
import weakref # precompiled from /usr/lib/python3.2/weakref.pyc
import reprlib # precompiled from /usr/lib/python3.2/reprlib.pyc
import _thread # builtin
import _locale # builtin
import encodings.ascii # precompiled from /usr/lib/python3.2/encodings/ascii.pyc

Next step will be to tell it to execute a script with PyEval_EvalCode() or something like that.

Join me on #bbx-python on freenode.net if you're interested in following this, or add a comment to this post. I'll also be tweeting a bit as @peter9477. Thanks!

SQLite: Negative Integer Primary Keys

2011-06-19T09:16:00Z

I was working on the design of a PlayBook app which would perform some data logging, and considered using SQLite as the primary mechanism. Alternatives included a simple text file (CSV format), XML, or SharedObject (not really).

Since the user may want to acquire data for a very long time, possibly on an ongoing basis for years, it seemed important to spend at least a bit of time considering the storage space that would be used.

With my prototype, which simply appends rows to a CSV file each time a reading occurs, the file would grow to approximately 50MB in the course of a year if the app were always running. Each record is roughly 204 bytes including newline.

The nature of the data is largely integers, but I realized that many of them would be negative, and wondered about how this would affect the file size of a SQLite database.

SQLite is interesting in many ways, one of which is that it uses a variable-length format for integers, using anywhere from 1 to 8 bytes depending on the size. That page may be inaccurate, because in a more detailed description it says it could be 1 to 9 bytes.

I built a small test database with an INTEGER PRIMARY KEY column, some text, and another integer column, and created rows with a variety of data. I then analyzed a hex dump of the records in the data area.

I immediately noted that my rows that had negative primary key values were taking up space for lots of FF bytes for the primary key. Yikes! I thought, is it really this bad for storing negative integers? Here's a couple of samples (note, this output doesn't actually match the schema I mentioned above, but it doesn't matter for this analysis):

0A FF FF FF FF FF FF FF FF 81 05 00 17 00 00 66 2D 31 32 37 "f-127"
08 FF FF FF FF FF FF FF FF FD 05 00 13 00 00 66 2D 33       "f-3"
08 FF FF FF FF FF FF FF FF FE 05 00 13 00 00 66 2D 32       "f-2"
08 03 05 00 13 00 00 66 2B 33                               "f+3"
09 40 05 00 15 00 00 66 2B 36 34                            "f+64"
0A 81 00 05 00 17 00 00 66 2B 31 32 38                      "f+128"

Note all those FF bytes. What a waste of space. The positive integers are stored compactly, with 3 and 64 requiring only a single byte, and 128 taking up two bytes. (Note that it would have made comparison easier had I used the same length of text in each row.)

Upon further inspection and reading, I sorted it out. Every row, even if you don't specify an INTEGER PRIMARY KEY, has a ROWID assigned by the database to track it. If you specify any other column as the INTEGER type, even negative values will be stored compactly. A -3 is stored as just FD, rather than FF FF FF FF FF FF FF FD as shown in the ROWID sample earlier.

Here's the key point: if you have a column which is defined as the INTEGER PRIMARY KEY, then SQLite doesn't bother creating a real column just for that data. It will reuse the ROWID instead. But if you plan to store lots of small negative values in that field, you'll potentially be using up lots of extra bytes for all those FFs! The "varint" format for ROWID is compact only for positive values.

It would take a very particular type of data for this even possibly to be a problem. You'd have to have lots of negative values between -1 and maybe -16 million or so.

If this were an issue, the "fix" would be to define a separate column for your data, and a INTEGER PRIMARY KEY which you mostly ignore, allowing SQLite to auto-assign and increment as positive values.

As a crude estimate of the difference in space used, here are file sizes for the two versions, one where we store our negative values in the INTEGER PRIMARY KEY column where they end up becoming the ROWID, and the other where we assign a second column just for that data. Each example assumes a million rows, with data going from -1 to -999,999, and I'm ignoring any overhead for tracking b-tree pages, the database header, etc.

Mode	File Size
reuse ROWID	10.5MB
separate field	6.6MB

Okay, well, that about ties things up. Quite clearly, even on the PlayBook, it's unlikely a difference of 4MB is going to matter to anyone. And none of this would have affected me anyway, as the values I need for my primary key fields turn out not to be negative!

PlayBook: Power Consumption

2011-06-15T12:40:00Z

I've been taking power consumption measurements while running the PlayBook under various loads, and some of the results are pretty interesting. I'll write up more later, but here's an initial overview of some data that may be useful to you, either as a user, or as a developer.

First a bit of background. The PlayBook has two battery packs in it, with the combined pair providing nominally 5400mAh, which at an average voltage of 3.7V provides 19.98Wh of energy. See for example the ifixit.com teardown for some pics of the labelling.

In actual fact, Lithium-Ion Polymer batteries never provide the full rated capacity and, at least in the case of my own PlayBook, I can confirm that the capacity as shipped was only around 93% of that. The initial drop can be disconcertingly rapid, too, and after 42 recharge cycles their capacity is now only 90%, or about 18Wh.

That Watt-hour capacity value can tell you roughly how long a battery will run your device by dividing by the average power used. If, for example, the device used 1W on a continuous basis, 18Wh would give 18h of use.

A PlayBook, sitting idle but with the screen turned on, backlight at 50%, running no apps, uses about 2.3W. That means even if you basically didn't do anything useful with it, you'd get only about 7.8h under those conditions. There's a reason the screen and backlight turn off so quickly!

Here are some other basic numbers for you to compare. The values shown are in milliwatts (50mW is the same as 0.05W). The "Life at Constant Load" value is an approximation based on a battery at 90% health, which is probably typical for most PlayBook owners as of this date.

Power consumption (in mW) under different loads for PlayBook
Load	Power	Life at Constant Load
Standby	52mW	15 days
Screen on/backlight 0%	1680mW	10.7h
Screen on/backlight 50%	2300mW	7.8h
Screen on/backlight 100%	3000mW	6.0h
Standby/White Noise on/volume 50%	360mW	50h
Standby/GPS @2Hz	213mW	85h
Video 720P/volume 0%/backlight 30%	2300mW	7.8h
Video 720P minimized/volume 10%/backlight 100%	3500mW	5.1h
Video 720P fullscreen/volume 10%/backlight 100%	3240mW	5.6h
Flash video on CNN site (not fullscreen)/backlight 100%	4000mW	4.5h

The White Noise app mentioned there is my own, available from App World. It's written "properly" so it will generate smooth, pure, non-repeating random noise even when the PlayBook is on standby, just as you'd want for masking background noise and letting you get a good sleep!

The most interesting results so far are that the GPS consumes so little power (yay!) and that the backlight and screen together consume so much. It also appears that playing fullscreen video uses less power than running it in a web page or with the video player app minimized (but active). I need more measurements to say for sure but it looks like this holds true whether it's a Flash player in the browser or the standard video player.

Advice for maximizing battery life? Keep the screen off as much as possible! Set the timeouts for as short as you can live with and make liberal use of that shiny new "Stand By" button found in the System Tray battery popup.

If you have to actually use the screen (i.e. for most real uses), keep the backlight as low as possible. Depending on lighting conditions, you may find that having the backlight at minimum is acceptable, or as low as 25% may be okay.

Finally, run video fullscreen where possible.

So, who wants a battery monitor app? You won't find anything better than Battery Guru for the BlackBerry PlayBook. :-)

PlayBook Browser Viewport Size

2011-05-27T00:00:00Z

Although the resolution of the screen on the 7" PlayBook is 1024x600, the browser window size is always less.

In the default configuration, the browser viewport is 1024x512 pixels. That's when the back/forward buttons, address field, history/bookmark and fullscreen toggle switch are showing.

I think it would have been nice if "fullscreen" mode on the browser eliminated all window chrome, including the title bar, but unfortunately that's not how they've done it.

With only the title bar showing, your window size is 1024x569 pixels, so the title bar steals 31 of those valuable pixels just to show you the name of the page you're on, as if you didn't know already and couldn't tell easily by doing a top-swipe to see the address field.

I found this site helpful in identifying these numbers, and it also has a nice bit of code (jQuery-based) that looks useful for making a site which can adjust its content to fit the browser window size, which seems especially helpful for mobile devices.

I have some internal-use sites which I will be adapting to better fit the limited resolution of tablets. There was never a reason to with smartphones, as I find them just too tiny to be effective for real work, but after almost a month of use I've definitely concluded that a tablet is a different story, and has serious productivity advantages when used appropriately.

PlayBook: Errata #1

2011-04-17T00:00:00Z

Wow, I've been slow getting back to this non-blog. Sorry for the long silence, and I do intend to post more often again.

In the last couple of months, much has happened and, unfortunately, a few things have not. For one thing, we don't have our PlayBooks yet, as of this writing. Nor do we have a 1.0 SDK and a decent simulator. Nor, for that matter, has the PlayBook even been released, except to a few lucky members of the press.

Nevertheless, information does ooze out, be it ever so slowly. A few things contradict or outdate things I said earlier. I'll summarize the changes here:

Top-Swipe Menu: I believe my design was flawless for the simulator up to 0.9.4, but reports from someone at RIM who tested my app suggest that the SWIPE_START behaviour is different in 1.0. He describes my menu as being usable only once... he can open it, change settings, and close it, but after that the menu doesn't respond any more. If you used the design in that post, your menu stands a good chance of not working and I suggest you switch to SWIPE_DOWN until the problems are sorted out. I will post an update as soon as I get something with 1.0 on it for testing.
Application Lifecycle describes invoking, exiting, and activate/deactivate, but only in the context of the simulators before 1.0. Now there will be three modes for multitasking, only one of which acts the same as the current simulator. In Showcase mode you will not get any ACTIVATE/DEACTIVATE events. The simulator is currently representative only of the Default multitasking mode in the real thing. (The Paused mode basically freezes an app when inactive, so it probably looks like a DEACTIVATE followed by a long pause with no scheduling of the app before it later gets an ACTIVATE again.)
Font List noted the fonts from an early simulator. In more recent ones, several fonts have been added, but more importantly the default font was quietly changed to "Myriad Pro". This can mess up formatting compared to "BBAlpha Sans", the previous default font.

PlayBook: debug trace() statements

2011-02-10T00:00:00Z

When debugging AIR apps in the PlayBook simulator, you build your app using the -debug option to the amxmlc compiler... or your IDE does it for you. With that flag, and appropriate options passed to blackberry-airpackager (specifically -target bar-debug) and blackberry-deploy (-debugHost X.X.X.X), your app will attempt to connect to the debugger running at the specified address, and among other useful things you'll be able to see the output of your trace() calls.

But what if you decide to cancel the debug session, or just never start it, and only then find a problem with your app? You might have to restart, this time connecting to the debugger. This is never a good situation, and you'll be lucky if you can reproduce the problem.

Fortunately, if the app was compiled with the debug flag, and if you included the -devMode option when you packaged, your trace() output is available anyway.

First, connect using SSH. Change directories with cd /accounts/1000/appdata, then type ls to list the subfolders. Find the one for your app and change into it with another cd command.

The -devMode option is what allows you to do this, as without it the sandbox is protected from other users, including the one you've connected with ("devuser"). With this option the app is installed under one of six special user groups, named dev0 through dev5, and devuser is a member of each of those groups. (Note the devMode bug which may interfere with this if you have installed more than 6 apps using -devMode.)

In the app sandbox there are several subfolders. Three of them, data/, logs/ and tmp/ are created when the app is installed, while four symlinks (app, db, pps, shared) are created the first time the app is launched.

The output of the trace() calls is recorded in the file logs/air-trace, provided you used -debug when compiling. (If you did not, those statements are stripped out, taking up no space or CPU time in "release mode" apps.)

The best way to view the file for a running app is this command (with the dollar sign being the command line prompt, so don't type it):

$ tail -f air-trace
XMLList:
extensionsDeviceBundledDirectory is null
app:/META-INF/AIR/extensions
Extensions to load: 0

The next four lines shown are the output I see with my own app. I assume you'll see the same, as those are not from my own trace() calls.

If you want more help on the tail command, type use tail. Note above that I've used the -f option, which makes tail stay running so it shows new lines as they are appended by your app. Hit Ctrl-C to get back to the prompt. Note also that if you exit the app and restart it, tail doesn't notice that a new air-trace file has been created so it won't switch to it automatically and you won't see any more output until you run tail again.

If your app has crashed and you just want to see the full file contents, use cat air-trace to dump it to the console. You could also use sftp or scp to transfer the file to your host machine.

PlayBook: SWIPE_START Simplified

2011-02-05T00:00:00Z

Warning: in the 1.0 release, SWIPE_START may no longer work exactly as described here. If you use it in your app, you may need to switch to SWIPE_DOWN until the 1.0 software has been released and can be analyzed fully.

In my previous post I wrote at length about the two ways to handle top-swipe events with the Adobe AIR SDK in the BlackBerry PlayBook.

As always happens after I spend a long time polishing some code and writing documentation for it, shortly afterwards I realized it could be simplifier. In this case, there's a way to use swipeStart without dealing with mouseMove at all.

From the last post, here's the sequence of events that you'll get if you subscribe to QNXApplicationEvent.SWIPE_START and perform a top-swipe:

QNXApplicationEvent.SWIPE_START
MouseEvent.MOVE (once only)
MouseEvent.DOWN (at same coords)
MouseEvent.MOVE (many)
MouseEvent.UP
MouseEvent.CLICK

Now as I pointed out in the previous post, it's possible to contrive to generate the same sequence without really doing a swipe, but just tapping and releasing in the top bezel (i.e. don't move your mouse/finger), then down in the screen area doing a proper swipe.

The simplification to my ca.microcode.menu.TopSwipeMenu code would be to ignore MouseEvent.MOVE entirely, and just use the MouseEvent.DOWN which follows the swipeStart as the signal that the top-swipe gesture has really begun provided the mouse coordinates lie in the bezel area. That is, check for "stage.mouseY < 0" and cancel the swipe if that's not true.

There's a minor defect with this approach, since it's possible to tap just off the top of the screen (Y value just below 0) to generate the swipeStart, yet not have the mouseDown event be issued until the position is already at 0 or higher. You can choose how to deal with this, but the simple approach would be to ignore it. That would mean users have to start the top-swipe just the slightest bit above the top edge of the screen (depending on how fast they swipe), but it seems unlikely anyone would ever notice the limitation so this is a mere technicality.

I won't post sample code for this (yet) as I haven't tried it out myself, but anyone who can deal with the state machine code should have no trouble modifying it to work this way. I'd also like to just wait until I have real hardware on which to test, since:

the behaviour may be different by release time, and
the response to touches may differ slightly from mouse clicks in the simulator.

PlayBook: Top-Swipe Menu

2011-02-05T00:00:00Z

Warning: the approach described here for SWIPE_START was carefully designed based on the observed performance of the simulator as it was at the time. Unfortunately, at least one app built around this approach does not work correctly on the "1.0" software running on the real hardware. If you've used this code in your app, you may encounter the same issue, in which case for now, switching to the more primitive SWIPE_DOWN mechanism.

In the BlackBerry PlayBook Developer Forum (Tablet OS SDK for Adobe AIR) there have been several threads about the SWIPE_START event and SWIPE_DOWN event and how to use them to implement an application menu. None of these have yet given a complete picture of how those events really work. But don't worry, I've analyzed it all for you!

SWIPE_DOWN Event

I'll cover this one first, because with it you can implement a simple "top-swipe" app menu with only a few lines of code.

SWIPE_DOWN is one of two events dispatched by the QNXApplication.qnxApplication singleton instance to signal user swiping activity in the top bezel area.

To top-swipe, the user begins swiping in the top bezel in the appropriate region. This region lies between X (horizontal) coordinates 50 and 975, leaving a 50-pixel-wide margin at either side for the top-left and top-right swipes (see image). These "corner" swipes are used to "peek" at the system status bar (as long as you hold your finger down) or to expose it completely if you raise your finger. (Note how the status bar "pushes" the app stage down, rather than sliding over.)

If the user continues swiping down far enough into the screen area (apparently to a Y value of around 21) then the SWIPE_DOWN event is issued immediately. That's all there is to it.

Given that your app has no advance knowledge of the imminent arrival of SWIPE_DOWN, it can't do anything before receiving it. Upon receipt, it could either tween a menu panel down into place, or even just make it appear instantly (e.g. with addChild()). That's about as simple as you can get. The following few lines add this to any app, as a starting point. Imports are left out to simplify the example.

QNXApplication.qnxApplication.addEventListener(QNXApplicationEvent.SWIPE_DOWN, onSwipeDown);
...

private const MENU_HEIGHT:int = 50;
private function onSwipeDown(e:Event):void {
    if (!menu) {
        menu = new Sprite();
        menu.graphics.beginFill(0x654321);
        menu.graphics.drawRect(0, 0, stage.stageWidth, MENU_HEIGHT);
        menu.addEventListener(MouseEvent.CLICK, closeMenu);
    }
    addChild(menu);
    // include the next two lines to animate the menu opening
    menu.y = -MENU_HEIGHT;
    Tweener.addTween(menu, {y: 0, time: 1});
}

private var menu:Sprite;
private function closeMenu(e:Event):void {
    removeChild(menu);
}

Note, however, how the animation completes regardless of what you do. It doesn't "track" the position of your finger, and you can't change your mind and return to the top: the menu will open no matter what. This approach is simple, but a bit crude.

SWIPE_START Event

In contrast to SWIPE_DOWN, there's not much you can do with SWIPE_START that doesn't involve a lot more lines of code. SWIPE_START is sent immediately whenever your finger touches the top bezel area in the top-swipe region. There are several interesting behaviours associated with it.

One is that you don't actually have to respond to any MouseEvents or touch events... you can watch for SWIPE_START and take some action based on that, even opening a menu as shown above for SWIPE_DOWN. That's neat, but possibly unfriendly to users who are used to the more conventional swiping behaviour.

If you want to respond to the actual swiping gesture you'll need to monitor several MouseEvents (on the stage), which is the reason this one is more complex than SWIPE_DOWN. The second interesting thing about SWIPE_START is that if you are listening for it, and the user's finger moves (as opposed to just being raised again), you will receive MouseEvents associated with the top-swipe. You won't see these MouseEvents if you don't listen for SWIPE_START.

But wait, there's more! You'll get the MouseEvents even if the swiping finger stays in the bezel area, and even if it moves across the top and down along the sides to the bottom! That should suggest a few interesting (but again, unconventional and possibly annoying) ways of responding to user actions.

The actual sequence of events for a real swipe will be this:

QNXApplicationEvent.SWIPE_START [also known as swipeStart]
MouseEvent.MOVE (a single one) [mouseMove]
MouseEvent.DOWN [mouseDown]
MouseEvent.MOVE (zero or more)
MouseEvent.UP [mouseUp]
MouseEvent.CLICK [click]

The mouseDown event will be seen immediately after the first mouseMove. If the finger keeps moving, you'll get lots more mouseMove events, followed eventually by a mouseUp and click (even if the finger never leaves the bezel region).

If the user simply touches and lifts the finger without moving it, you'll see just this:

QNXApplicationEvent.SWIPE_START [swipeStart]
MouseEvent.MOVE (a single one) [mouseMove]

You don't need to handle all the events shown, but you'll likely want at least the mouseDown event along with either mouseMove or an enterFrame handler, followed by the mouseUp event. (That's assuming you are still interested in implementing a conventional menu, and not heading right off to play with odd top-bezel gestures like a kid with a new toy.)

It's your choice which event to use to track the mouse motion, but you'll get way more mouseMove events than you need, so to reduce CPU usage you're probably better off with an enterFrame handler for the tracking.

The reason you should listen for the mouseDown event is to avoid taking action when the user merely brushes the bezel ("touch and release"). A naive implementation would use swipeStart to set up the position tracking, but then you'd do the wrong thing if the user tapped the bezel, then started a real swipe gesture inside the screen area.

Faking a Top-Swipe Gesture

Actually, you may have noticed there's a loophole in RIM's current design. If you touch-and-release in the bezel, generating a swipeStart then mouseMove, then touch and drag inside the screen, generating a mouseDown and more mouseMove events, the sequence is the same as a real top-swipe. (If you try this with a mouse, you'll see more mouseMove events as soon as the pointer moves into the screen area, but that's cheating. Without a mouse, there's no pointer and no mouseMove events unless you're touching the screen.)

The problem with ignoring this is that the user could abort a top-swipe but you'd respond to the next actual drag inside the app stage as if the user were still swiping. My original top-swipe implementation in the support forums suffers from this problem. Try it: click above the app (but don't swipe), then click and drag inside the screen area... you should see the menu open even though this isn't a valid top-swipe gesture.

There are probably several workarounds. The simplest would be to check whether the mouseDown event has coordinates very close to the swipeStart event, cancelling the top-swipe if it does not. The problem with this is that the coordinates reported for stage.mouseX (and mouseY) seem to correspond to the last-seen position (from a previous MouseEvent), not where the finger actually is at swipeStart.

A more complex approach involves listening for mouseMove following swipeStart, and noting the coordinates. Then filter the next mouseDown event and check that it's coordinates are the same. (I assume they should be exactly the same, especially as the mouseDown seems to be generated, not the real one that presumably triggered the swipeStart.) If the next mouse event is not mouseDown, or if the mouseDown position is different, then the user cancelled the swipe and is doing a non-top-swipe somewhere, even if it's right at the edge of the screen.

The Implementation

The code for this is a bit long, so I'm not including it directly here. If you want to peek at it, look at ca.microcode.menu.TopSwipeMenu and the demo program that uses it in MenuTest. (By putting it there, I can also make changes more easily, and you can submit issues to the tracker, if you like.)

The code implements a 7-state finite state machine that cleanly steps through the various stages possible. The design ensures that only the necessary listeners are active at any given time, so you don't wastefully watch for (especially) mouseMove or enterFrame events when it's not required. See the figure below.

As implemented, it requires you to specify a width and height for the menu, and optionally a background colour for the panel. You can adjust the "swipe_region" (probably not a good term for it, but it defines how far you have to swipe into the screen before you can release and have the menu continue opening on its own) and "slide_time" (duration in seconds for the complete menu slide) as class properties.

To close the menu you can either click below it, add a Done button as in the MenuTest example code, or touch the top bezel again.

I hope it proves useful to someone. It's taken quite a few hours to get it to this stage; I would appreciate a small credit somewhere in your app or docs if you choose to use it. At least let me know where it's been used, for my own satisfaction. (Legally you don't have to do either, as I've released it under the MIT License, but you must preserve my copyright notice and the license even if you change the code.)

Addendum

I wrote a follow-up with a suggestion for a simplified version that doesn't require listening for mouseMove at all.

Convert EPS to PNG with ImageMagick

2011-01-24T00:00:00Z

Coincidentally, after getting by until recently without having a good reason to try ImageMagick, I needed it again just today. I had a company logo in EPS format which I needed turned into PNG format.

Since I'm on Windows, and don't have Adobe Photoshop, this isn't a 10-second operation. At least, not until you install the right stuff. Even on Windows, however, ImageMagick knows how to call out to Ghostscript if it's installed.

The first attempt to convert produced a nice clean 52K PNG file at 2254x751. Okay, so basic conversion works:

convert myfile.eps foo.png

I wanted it to be 300 pixels wide, however, so I tried the obvious. Yes, without reading the docs... but who reads the docs the first time?

convert myfile.eps -size 300x76 foo.png

This gave the same output... Hmm. Better actually read the docs.

Okay, so -size is for when an image doesn't have known dimensions, such as can happen with certain file formats. I want -resize instead:

convert myfile.eps -resize 300x76 foo.png

That works well, except the resulting file is 60K, which is too big. Why? Explorer shows that it's a 48-bit image... rather more than I need. How to get less depth?

convert myfile.eps -resize 300x76 -depth 8 foo.png

Well, same quality but 24-bit depth and only 28K. Huh? Where did 24-bit come from when I asked for 8? It looks like the -depth option specifies per-colour depth. Using identify -verbose foo.png gives more detail than I need to learn all about that. Trying again with -depth 4 gives me as much quality as I need, at 4 bits per colour, and just over 13K.

But the file is still larger than I'd like... using "strings foo.png" shows me there is lots of metadata present in the file, leftover from the original EPS file which was apparently built in Adobe Illustrator. The -strip option will "strip the image of any profiles or comments" say the docs so let's try that:

convert myfile.eps -resize 300x76 -depth 4 -strip foo.png

That shrinks it down to only 3.8K, which is even smaller than I'd hoped for and, incidentally, 0.075% of the original EPS file size. Job done: thanks ImageMagick sponsors!

PlayBook Simulator FTP Transfer Fails

2011-01-21T07:29:00Z

This morning one of the forum posts was a question about problems using URLLoader to retrieve a file over FTP.

My first response was to suggest that the poster may be mistakenly thinking he could use the HTTP protocol to get to something over FTP. There was nothing in the URLLoader docs to suggest it handles FTP, and as usual with my ActionScript3 queries I found almost nothing on the web with a search or two, other than one post where people said you can't do it.

It turns out I was quite wrong and, as with the Python urllib tools, URLLoader transparently handles FTP under the covers. You can even include a userid and password in the URL, as with Python's approach. (It works, but I still find no docs or search results saying that.)

Unfortunately, with the current simulator (Beta 2, v0.9.2) it doesn't actually work. I analyzed with tcpdump on my router and was able to see the full FTP session, with login, switch to passive mode, checking size of file, and retrieval of data. For my test case, it was a local FTP site with authentication and an 82 byte text file, but I also tried with an external anonymous site and a larger file.

Basically the complete transfer succeeds, with all data received, yet before sending Event.COMPLETE the data seems to be simply discarded, with no indication why.

The original poster filed this as ticket TABLET-50. (Note that the link won't work for you unless you're logged into the BlackBerry issue tracker, and they make the ticket public. In the past all tickets were visible but I guess as they get closer to release they've decided it's time to make tickets private by default, so they can vet them for security risks and such.)

Here's the code for a simple test:

package
{
    import flash.display.Sprite;
    import flash.text.TextFieldAutoSize;
    import flash.text.TextFormat;
    import flash.events.*;
    import flash.utils.*;
    import flash.net.*;
    import mx.utils.ObjectUtil;

    import qnx.ui.text.Label;

    [SWF(width="1024", height="600", backgroundColor="#5588ff", frameRate="20")]
    public class FtpTest extends Sprite
    {
        private var logo:Label;
        private var loader:URLLoader;

        public function FtpTest()
        {
            var logoFormat:TextFormat = new TextFormat();
            logoFormat = new TextFormat();
            logoFormat.size = 22;

            logo = new Label();
            logo.format = logoFormat;
            logo.text = "FTP Test";
            logo.autoSize = TextFieldAutoSize.LEFT;
            logo.x = logo.y = 10;

            addChild(logo);

            var request:URLRequest = new URLRequest("ftp://ftp2.bom.gov.au/anon/gen/fwo/IDA00001.dat");
            // next one shows how to do authenticated login, the above is anonymous
            // var request:URLRequest = new URLRequest("ftp://user:password@example.com/path/myfile.text");
            request.method = URLRequestMethod.GET;

            loader = new URLLoader();
            loader.addEventListener(Event.COMPLETE, onEvent);
            loader.addEventListener(IOErrorEvent.IO_ERROR, onEvent);
            loader.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onEvent);
            loader.load(request);
            }

        private function onEvent(e:Event):void
        {
            trace(e.type, e);
            if (e.type == Event.COMPLETE) {
                trace("data", ObjectUtil.toString(loader.data));
                logo.text = "Got " + String(loader.bytesLoaded) + " bytes" +
                    "\nData: " + ObjectUtil.toString(loader.data);
            }
        }
    }
}

PicasaPhotoViewer Process Doesn't Terminate

2011-01-20T15:43:00Z

I have the Picasa photo viewer (PicasaPhotoViewer.exe) set up as my default app for basic image viewing. It's generally fast, makes it easy to scroll through a folder full of images, and lets me zoom in and out at lightning speed using the mouse wheel. All good.

Unfortunately, sometimes I would notice in my Task Manager window (this is on Windows 7 Pro) that I had a whole pile of PicasaPhotoViewer.exe processes still running, even with no photos left open onscreen. It was easy to terminate them (though with 30 processes a bit tedious) but it's always annoying when things like that happen, especially when you can't find an obvious answer.

I googled several times but never saw any mention of it, until I checked again today and found others had asked about it and, amazingly, actually got a useful answer.

As it turns out, the process may (or perhaps will) stay resident if you are loading files across the network. I have a server with a largish hard drive (RAID5) and keep lots of photos and such on it, so from time to time I browse a folder on the network. If I'm repeatedly viewing an image then closing the viewer, regenerating the image (say) at the command line, then reloading it, each iteration opens a new process and leaves the old one in memory.

So there's no fix, but at least I now have an answer and can stop worrying about it. It's just another of those little annoyances from Google, where if you could only just figure out how to get someone there to hear about, acknowledge, and fix your problem -- or do any one of those! -- life would be great.

Thanks "neilwales", whoever you are. :)

Edit: this is fixed in build 117.38 and later, at least for some people.

Using ImageMagick to Filter Page Scans

2011-01-20T12:13:00Z

I had a need to clean up some not-so-great scans of photocopies. The pages included both text and music. This made it a bit tricky to process since the music had very thin lines. I needed the text darker, but without amplifying the background noise, and this tended to fade out the lines in the staff. I was able to get good results from Paint.NET using just the Auto Levels adjustment but I had 48 pages to process and there's no way I was going to do it manually; as far as I know you can't script Paint.NET.

I briefly considered a few options, including GIMP, before re-stumbling over ImageMagick, which I've known about for ages but actually never had a need to use before. Quoting from its web site, it's "a software suite to create, edit, compose, or convert bitmap images.... [It is] typically utilized from the command line...." It handles just about every format under the sun including JPEG and PDF, which is what I needed.

There are a gazillion things you can do with it, including writing very sophisticated scripts around it, such as those included on Fred's ImageMagick Scripts page. I tried out a couple meant for thresholding (i.e. making your background fade out more while your foreground is strengthened... like boosting the contrast), including kmeansthresh, textcleaner, and 2colorthresh before finding the excellent threshold comparison study which, for my purposes, suggested that the "Local Adaptive" filter (localthresh) could be the best bet.

I cycled through a series of test runs with varying parameters (manual optimization). I settled on localthresh -n yes -m 3 -r 35 -b 20 which means:

-n yes: "negate", since my image was black-on-white and the tool needs the inverse
-m 3: "local mean and mean absolute deviation" mode, because the other two modes gave bad results
-r 35: radius of 35 pixels, just larger than the thickest feature, which was some title text
-b 20: a bias of 20, chosen empirically

The radius value matches roughly the thickness of the largest text in the page, and anything less would result in an outline (black around white regions) rather than solid lines making up the letters.

The scans were JPG format at 600dpi, about 4900x6900 pixels. I used PNG for the output files to avoid any incremental degradation, as JPG uses lossy compression (PNG is lossless). I did this as I expected to need some subsequent processing, but as it turns out this first pass was adequate (quite good, really) so that's as far as it went.

To ease printing, I wanted to combine all the images into a PDF as well. ImageMagick does that, too. Note that ImageMagick's default PDF output is uncompressed so to avoid massive file sizes I specified zip compression:

convert -compress zip *.png foo.pdf

I packaged all this up into a Python script (see below), so the whole thing was automatic (except the scanning, intermittently feeding sheets to the scanner over several hours while reading news online).

And now some before and after pictures to compare the results. Note that the main goal here was to make it easier to read the music (when reprinted) and note how much stronger the staff lines are. The text was fine either way, though it didn't hurt if it improved a bit (or lost a tiny bit of clarity, if that was the tradeoff we had to accept).

Here's a small section of music as a raw scan:

And the same section after filtering:

For comparison here's a small bit of text:

And the filtered output:

Here's the script. Note that it is meant for Linux, mainly because of the "localthresh" script which uses Bash shell syntax. The script assumes you have ImageMagick installed and that you have downloaded localthresh into the current directory, and did chmod +x localthresh to make it executable. Make appropriate changes for other systems and note that as usual Windows is a second class citizen.

To invoke it, make sure to escape any wildcards with single quotes, as in ./scans2pdf.py '/home/foo/*.jpg' or the shell will expand them and

#!/usr/bin/env python
'''Mass filtering of page scans to improve text quality using ImageMagick.'''

import argparse
import glob
import os
import shutil
import tempfile


def main(args):
    tempdir = tempfile.mkdtemp()
    try:
        files = []
        for arg in args.input:
            files.extend(glob.glob(arg))
        for name in sorted(files):
            convert(name, tempdir)

        if os.path.exists(args.output):
            if args.force:
                os.remove(args.output)
            else:
                sys.exit('Output file "%s" exists.  Use -f or --force to overwrite.')

        os.system('convert %s/*.png -compress zip %s' % (tempdir, args.output))

    finally:
        shutil.rmtree(tempdir)


def convert(filename, tempdir):
    inf = os.path.splitext(os.path.basename(filename))[0]
    outf = os.path.join(tempdir, 'out-' + inf + '.png')
    os.system('./localthresh -n yes -m 3 -r 35 -b 20 %s %s' % (inf, outf))


if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description='Mass filtering of page scans using ImageMagick.')
    parser.add_argument('input', nargs='+',
        help='Files or glob pattern(s) for input file, e.g. /home/foo/scan-*.jpg')
    parser.add_argument('-o', '--output', default='output.pdf',
        help='Name of output file, default "%(default)s"')
    parser.add_argument('-f', '--force', action='store_true',
        help='Overwrite if output file already exists.')
    args = parser.parse_args()
    main(args)

All this is offered up primarily for beginners looking for examples, rather than as a paragon of image processing virtuosity. Experts could do better, but this did just fine for my purposes and I hope some part of it helps out someone else.

PlayBook Simulator File Access

2011-01-17T09:25:00Z

Some developers have a legitimate need to share files with the PlayBook simulator. This is broken in the Beta 2 simulator. If you don't care why, jump ahead to the workarounds.

With the first (Beta 1) simulator this could be done using FTP. The simulator had little in the way of security: all apps ran as "root" and you could log in via Telnet or FTP as the root user. They didn't even make any attempt to make the password difficult to guess!

Unfortunately, with the Beta 2 simulator, they've tightened up security substantially. This is overall a good thing, since the final release should be very secure so we need to test under the same conditions, but it has hampered some testing efforts.

So in Beta 2, they removed Telnet and FTP, and added Secure Shell (SSH) access. Hurray! Except... what you can do with it is very limited due to several bugs, for now.

While SSH normally supports scp or sftp, someone at QNX got a bit creative with security and made /etc/passwd unreadable to non-root users. This has the unfortunate side-effect of breaking scp and sftp as I discovered. It's also entirely unnecessary because, in spite of its name, /etc/passwd is not a password file. It used to be, but in modern times the password hashes have all been moved to /etc/shadow, which of course is not readable by regular users.

There's another problem which makes things difficult, even if you figure out how to transfer files using just SSH. They apparently intended to make an app's "sandbox" folder accessible to the development user when running in development mode (specifically, with the -devMode option on blackberry-airpackager). It looks like that doesn't actually work either -- at least, I can't get it to work, and no one else reports success yet either. When you log in with SSH, you become "devuser" (uid 100). Unfortunately the sandbox folders are all under /accounts/1000 and "devuser" cannot access or read any of them, even those for apps installed with that mystical -devMode option. [This was fixed in 0.9.3. -Ed]

Workarounds

I've found a few primitive workarounds so far. Depending on your needs, one or more of these may work:

Your app can of course access its own files (in File.applicationDirectory, which maps to /accounts/1000/appdata/MyAppName.MY-APP-ID-HASH/data. The simplest approach is not to use external access via SSH, but just bundle your files with your app, and provide app-specific ways of manipulating them. Use things like File.copyTo() in the simulator, or flash.net.FileReference to transfer files between your web server and the simulator. Doesn't help if you don't have a web server and don't know how to set one up, even locally.
Use basic command-line tools via SSH. This won't work well for binary data, but if you just need to get a text file into the sim, something like this will work when executed at the command line on your host machine:
```
# transfer myfile from simulator to host
ssh devuser@MYSIMIP cat myfile >myfile

# transfer myfile from host to simulator
type myfile | ssh devuser@MYSIMIP "cat >myfile"
```
The first command executes "cat myfile" remotely on the simulator, and the output is redirected into a file on your host machine.

The second command outputs local myfile to stdout, piping it through SSH, and on the remote side redirects stdin to a new copy of myfile. That will end up in /accounts/devuser/myfile. To read this in your app, you'll need to do two things.
1. Make your devuser folder world-readable: chmod a+rx ~
2. Use an absolute path of File('/accounts/devuser/myfile') to read it in your app.
If you need to get files from the app, do chmod a+wrx ~ to make that folder writable as well as readable, and make sure your app writes to that folder rather than File.applicationStorageDirectory where it normally would.
Transfer files using FTP, with the simulator as the client, to the devuser home folder. You first need to run an FTP server outside the simulator. Log into the simulator using SSH and type "ftp MYHOSTIP" then log in to FTP. Transfer files the usual way, making sure to type "binary" to switch to binary mode for file transfers unless you're doing just text files.
If you're desperate to the file transfers, you could run Python2.7 on the simulator and use Python's ftplib module. In the old simulator you could just do "python2.7" but another minor issue in the new one means you have to use a full path of /base/usr/bin/python2.7. You can write a script that will, for example, run on the simulator side and maintain a mirror with periodic updates to keep things in sync. [In 0.9.4 they changed the permissions so "devuser" cannot run Python on the simulator, rather sadly for me. -Ed]

If you combine options 1 and 4, you can have a fully automated way of moving files between your app's storage directory and your host machine. Just set up a Timer, have it trigger some File.copyToAsync() calls to exchange files with the /accounts/devuser folder, and after logging in via SSH run a timed Python script to exchange files with your host machine. Crufty, but until the next release it's the best I can think of!

Well, that's it. There are always options...

Note

Originally the post referred to this simulator version as "Beta 3" because we all thought that's what it was. As RIM seems to think confusing us is a good idea, they issued the Beta3 SDK with the Beta2 simulator even though both are called v0.9.2... Go figure!

PlayBook Beta 3 SDK

2011-01-12T15:08:00Z

Hurray! The next SDK and simulator for the PlayBook are out. Actually, not only have the Beta 3 AIR SDK and simulator been released, but there's now a Blackberry WebWorks SDK for PlayBook available on the Tablet OS Development site.

The AIR SDK release notes tell us what is new and changed. Here are the highlights, from my point of view:

"application control permissions" need to be set in your blackberry-tablet.xml file (note: that's not the same as the application.xml file!) to access certain things, such as camera or microphone.
audio is working! Sort of. And apparently video should work, but I don't think it really does yet for anyone.
numerous bug fixes (and some new bugs!)
Secure SHell (SSH) connections to the tablet, so they've ditched telnet and used something sensible (i.e. secure), not to mention making this an officially supported way to access the device: I don't have to be coy about using telnet any more.
custom splash screen for any app
Payment Service SDK!
the QNXStageWebView is documented, thus basically available, though still flaky

As for the simulator, it now supports orientation changes (using the "bottom right" swipe that I mentioned earlier).

Given how long it took, that's actually a fairly small list of significant items. I was expecting at least to see Notification support, among many other things that are still missing.

There are several bugs to note, and in fact many are thinking this version is showing pretty poor quality control, but given how late it is we're mostly just grateful to finally see it at all.

Some bugs with the auto-orientation support:

When you swipe to rotate, the app appears to be minimized afterwards. You can't just click on it. Instead, bottom-swipe (the regular "minimize app" gesture) and then click on the app. It will now expand with the new orientation.
Although stage.orientation is deprecated, stage.deviceOrientation always contains "unknown" so we have no choice about which to use yet. The orientation event has an "afterOrientation" property you can use, but that doesn't help with the next item.
If you rotate while the app is minimized, not only will it not get an event (which could let it re-render so it can update its minimized view) but after you restore it the value in stage.orientation will not have changed. There's no known workaround other than just re-rotating back and forth again while it's active.

The audio works, at least for flash.media.Sound, but so far not for the qnx.media stuff. And lots of people are seeing their simulator freeze while playing audio, though at the moment we suspect it's not directly related to audio. QNX is overly mum on the matter, as before, and so we waste significant quantities of developer time investigating things they probably already know about. I just wish they had a manager in charge who was capable of improving their communications with the dev community. Hey, I'm available!

There are also problems with the SSH support. For now, scp and sftp do not work, because QNX went overboard in their efforts to secure the thing and protected /etc/passwd from reading by anyone but the root user. They must have thought it actually contained passwords or something, which it does not. [They fixed this in the 0.9.3 release. -Ed]

The worst thing from my point of view is that they also set incorrect permissions on the app sandbox folders, so that even with the "-devMode" option on blackberry-deploy you cannot see into your app's data, or the shared folder, when you connect via SSH as "devuser". The workaround here is to do "chmod o=rwx /accounts/devuser" and have your app read and write to the /accounts/devuser folder, for any state that you need to access for testing purposes. [This was also fixed in 0.9.3. -Ed]

All in all, I'm glad it's out, but it could have been so much better.

PlayBook Tidbits #2

2011-01-07T07:54:00Z

More small observations from the goings-on at CES in 2011.

In the SlashGear.com video with Mike Lazaridis we can see some interesting new navigating gestures Mike uses. Note that these aren't available on the SDK yet:
1. While swiping sideways between running apps without minimizing them so the Navigator is visible, he can flick an app upwards to terminate it. This is similar to how you close them in the shuttle bar area in Navigator but it's new.
2. In the "between-app" view (as above), you can just drag left or right to continuing moving between apps, rather than having to swipe in from one of the bezels as you do in the current SDK. He even shows holding position between two apps while they both keep rendering. Obviously you can also just swipe from the bezel but that's really needed only to enter this new "switching mode".
3. (This wasn't Mike, but my own observation on the simulator.) You can not only swipe up to expand the icon area, but you can swipe up again to minimize it. Not sure that will make it through to the production unit since it might be too inconsistent for user comfort.
In the Navigator, in the category selection area above the app icons, there are arrow icons that you use to maximize or shrink the icon area. In many of the CES demo units you can now also see a little "pencil" icon at the left edge. CrackBerry.com's latest video shows that you can use this to reorganize your app icons in the Navigator.
In the beta SDK a minimized app had a red X close widget in the upper right corner. In the demo units it has moved down to follow the app title (a good move).
The three simultaneous ray-tracing demos running side-by-side, with Mike interacting with them in realtime, pretty much prove that this baby kicks any wimpy Star Trek gadgetry in the teeth. Take that, 24th century technology!
Someone pointed out in one video that along the top is not just one but two microphones... stereo. In theory that could be a big help for noise cancellation, though I don't know if the stereo nature of it will be exposed up through to the AIR APIs.
Mike L. mentions that the "USB connection can drive Ethernet", so they either have or intend to have driver support for some USB-Ethernet adapters. This is good for anyone thinking of driving serious business presentations out the HDMI without risking wireless glitches (assuming your source is on a network). (For anyone who hadn't heard, by the way, the HDMI output can technically function as an independent display, which would totally rock for business presentations, or just for letting someone watch a video on your TV while you surf the web.)
Mike commented that running his third instance of the ray-tracing app would start to slow down the system, so clearly they have the multicore support functioning in the demo units now. Or, at least, in his!

PlayBook Tidbits #1

2011-01-05T23:58:00Z

Lots of interesting tidbits starting to come out from CES 2011 with a slew of new videos (well, I've seen two so far, but compared to the recent dearth of new stuff I call that a slew).

Product Manager Ryan Bidan tells Information Week that the "target" battery life is 8 hours "in regular use". So much for Shaw Wu's bogus and questionably slanted claims that the device will have only "a few hours" of battery life.
In the same video, you can see him swipe through the installed apps on that particular beta unit, and one of the games is Quake III, and indeed Today in Tech refers to this and shows a screenshot. CNET senior editor Donald Bell has a BlackBerry PlayBook hands-on video that shows a few seconds of live video from Quake III.
Bidan says they are still "committed to delivering this product in Q1" but he can't be more specific. For a brief time Google had cached a WSJ article with the title "RIM Tablet Delayed Until Summer", but obviously someone with a clue thought better of that title as it now leads to an article titled "RIM Joins With Sprint on Tablet", where it talks about the 4G version in partnership with Sprint.
Some of the earliest approved apps by us little guys are even showing up in that InfoWeek video, including Jason Fincanon's Memory4Kidz. There's also Nic Nac Noe (Ninja Tic Tac Toe), with a couple of screen shown in the CNET video mentioned above, though I don't see that on App World yet.

PlayBook: Exit From an App Using ActionScript

2010-12-27T19:35:00Z

In a previous post I talked about several non-obvious gestures that let you exit from an app but, if you're a developer, you'll sometimes want to provide a Close button or some other way for users to edit more directly.

The most straightforward way is stage.nativeWindow.close(). This is actually a call that must be made from within a method in your main Sprite class, or any other suitable DisplayObject since it references the read-only stage property.

The actual call is to the NativeWindow.close() method. There are certain events associated with closing a window, or deactivating it, which I've covered in a previous post.

To summarize, here's a snippet to give yourself a Close button in your Sprite:

    ...
    var closeBut:LabelButton = new LabelButton();
    closeBut.label = "Close";
    closeBut.addEventListener(MouseEvent.CLICK, closeApp);
}

private function closeApp(event:MouseEvent):void {
    stage.nativeWindow.close();
}

PlayBook: Font List

2010-12-23T17:10:00Z

Using the flash.text.Font.enumerateFonts() routine one can see the following fonts available (at the moment... back at SDK beta 2) in the PlayBook simulator (skipping over some Japanese, Thai, and Indian fonts, and grouping related ones with slashes, to keep the list shorter):

Andale Mono
Arial
BBAlpha Sans (plus Condensed/Mono)
BBAlpha Serif
BBArabic Keypad
BBGlobal Sans
BBGlobal Serif
Bitstream Vera Sans (plus Mono)
Bitstream Vera Serif
Comic Sans MS
Courier New
DejaVu Sans (plus Mono)
DejaVu Serif
Droid Sans Mono
Georgia
Impact
Liberation Mono/Sans/Serif
Tahoma
Times New Roman
Trebuchet MS
Verdana
Webdings
Wingdings (plus 2 and 3)

It seems they're also taking requests for other fonts to be available in the final release.

[Edit: a handful of new fonts was added in the 0.9.4 release, and most importantly the default font changed from "BB Alpha Sans" to "Myriad Pro".]

Fixing cibcvisagold.com

2010-12-21T20:10:00Z

I did a little technical support tonight for a major Canadian bank. Unpaid. Unrequested, too, actually. Not unappreciated though.

We were browsing the World of Gold Rewards site to see what "reward" my wife might want as a birthday present from her father. (Yes, we have everything we need, so she wanted my help choosing. :-) )

The pictures were not showing up on the rewards, just empty boxes where they should have been. I was using my daughter's computer, which runs Ubuntu, so I popped down to my own Windows machine to compare, and got the same results. Checking the source for the page showed me lots of Javascript, plus some IMG elements with their source URL pointing to https://www.fairlanezip.com, whoever they are. Clicking on the links in Firefox's source view showed me a security warning because of an SSL certificate expiry three days ago. I guess maybe these fairlanezip people aren't particularly competent or something.

Anyway, that was the easy part. The hard part, of course, was trying to tell CIBC about it. Their "Contact Us" page has only a phone number (toll-free), so a simple email was out of the question. At least their hours of operation were generous -- until midnight.

To avoid a long story: I called the number, faced five menu items with no suitable option, pressed a few random numbers and the pound sign, got to someone who heard the word "web" and passed me off to their "online banking" department... who said they were only for personal banking, not VISA, but they could transfer me back and would talk to someone there first to smooth the way.

They did that for a few minutes, then told me the best approach would be to just call the number again and ask for a supervisor. Rather remarkably, given that I was doing this as a favour, I did call back, got a supervisor with no hassle, and told him I'd seen a problem and knew what was causing it. He was actually grateful, as they had had reports of a problem but obviously no answer yet, and took the information I had to pass on to their in-house IT staff (who, presumably, are about as on-the-ball as the fairlanezip people, which is to say not very since they hadn't seen or fixed the problem after three days). With any luck, they'll have it fixed shortly, maybe by tomorrow morning.

The nice thing about this was that everyone I spoke to was pleasant even while not necessarily being able to help, and all who understood what I was trying to do for them expressed their thanks. I'll stay a happy TD Canada Trust customer, but it's nice to know a big bank, even when their own size and possible dead-weight is working against them, can have nice and polite people answering the phone.

PlayBook Usability: Discoverability

2010-12-21T07:31:00Z

As mentioned in my previous post I have some concerns about UI design in the tablets. One of those concerns is "discoverability", as described in Jakob Nielsen's summary posting about his early iPad usability study.

I found this to be a problem the first time I touched an iPad. While some things are done very well -- it didn't take a second to understand how to unlock the device -- others are pretty obscure. Note that this first screen a user ever sees even has a nice clear instruction to "slide to unlock", and a sharp-looking slider, but they could have done as well with other features inside.

I was using my father-in-law's new iPad in a quick attempt to learn enough to provide basic instruction. I got it hooked to the house network easily enough... well, with minor annoyances, but I don't recall the specifics. I do recall, however, once we got his email loaded up that the first thing we wanted to do after viewing a message was delete it. Hmm... how do you do that? Is there a nice X widget somewhere? A trash can? A button labelled "Delete"? No such luck... fortunately I'm an old hand at UI testing and troubleshooting, so after a few trial-and-error efforts I quickly found that you "swipe" sideways within the list and a shiny red "Delete" button magically appears for you to tap. Thanks for hiding that, since deleting emails is something I do, like, so rarely.

The real lesson is this: you no longer have your desktop OS highlighting the active components as you "hover" the mouse over them. With a direct-interaction interface like these tablets have, there's no "hover"... you either touch something or you don't.

My advice: look for ways to make sure the user knows what the heck she can tap, press, swipe, flick, or otherwise fiddle with. How about having a nice blue glow "evanesce" around all the active elements when a page is first displayed? Or a subtle animation where those elements periodically have a "gleam" appear in one corner (possibly supplemented by a more 3D appearance than we often see on tablets so far). Or some nice tooltip/hint things, like balloons in a comic strip, which appear next to the key controls for all new users, or if new user doesn't discover a particular feature (like that email delete button on the iPad) soon enough. These could all be subtle, and made to disappear gradually over time or even immediately upon first use of any given feature by a new user.

A related effect works reasonably well when a page has lots of content but few other controls. Just touching the content area makes the hidden controls appear briefly, then fade again after a second or two. Users will quickly learn that there are controls available at the touch of a finger, at which point they're all clearly visible. This wouldn't be as safe in a complex view, where touching certain elements could have an irreversible effect, so use it wisely. (I believe the PlayBook camera app uses this technique, with only a couple of primary controls always shown. Yes, I know that's actually a chat app, but the camera app looks similar and I didn't find a good picture of it yet.)

PlayBook Usability: Consistency

2010-12-21T06:24:00Z

While responding to a question in the Tablet OS Developers' Forum I ran across links to a free 93-page iPad usability report by Jakob Nielsen. (Actually, you may prefer his summary posting if you don't have time to read a 93 page PDF.)

Jakob's comments about inconsistency in the initial iPad apps reminded me of my first concern as I listened to the Fourth PlayBook Webcast. I thought that RIM was being pretty sparse on the guidelines.

I think they've had a year to review the iPad situation and learn from its mistakes, and they would do well to provide more thorough and substantial guidelines. Unfortunately they seem to be too busy with getting the product ready to give due attention to the quality of the user experience.

It seems clear that this lack of guidance will lead to each app being different. Users won't have a clue what to do in many apps, especially those written by Flash-only developers with no usability training, no experience with tablets (since who among us does?), and a growing desperation to get that free PlayBook!.

Nielsen certainly found inconsistent designs among the 35 apps and web sites they used in their usability study. Touching an image produced one of five outcomes, including doing nothing, enlarging the picture, and hyperlinking. I think generally the user was not given any hint ahead of time as to what the outcome might be in any given case. Advancing in a block of text could be done at least three ways: scrolling (with the finger), swiping left, swiping up.

My advice: watch closely other apps as they come out, try to identify the most intuitive, obvious, and effective mechanisms, and try to reuse them in your own apps. With diligence and speed, we can avoid the problems that will doubtless be caused by a lack of adequate design (by RIM) up front.

PlayBook: Application Lifecycle

2010-12-19T11:33:00Z

On the PlayBook an application goes through several stages in its lifecycle, and various events are issued to allow an app to monitor its externally controlled state. I say "externally controlled" because these state changes are generally out of the control of an application.

When an app is first launched, the NativeApplication.nativeApplication object will get an InvokeEvent.INVOKE event. This is likely not of much use, as an application knows it was just invoked when it enters its main constructor routine (generally a subclass of flash.display.Sprite).

When the application first becomes visible and fills the screen, where it's considered to be really running, an Event.ACTIVATE event will be sent and can be captured on the main Sprite. This same event is sent whenever a previously minimized app is restored, or when side-swiping changes to your application from another one.

An Event.DEACTIVATE is sent when the user switches away from your application, either by side-swiping or by swiping up from the bottom bezel to minimize the application in the "shuttle bar".

The call NativeApplication.nativeApplication.addEventListener(Event.EXITING, callback) can be used to subscribe a callback routine to an event sent when the user closes your application, either by clicking on the X button in the upper right of the minimized app's window, or by dragging it up from the shuttle bar to close it. This event is also sent when your application calls stage.nativeWindow.close().

Because you can't call event.preventDefault() on the Event.EXITING event, you can't prevent your application from closing, it appears. For that reason and probably others, it's definitely best to try to preserve all important state in response to a DEACTIVATE event, so that if the user subsequently closes your app you have already saved.

Lastly, though perhaps of no more use than EXITING, you can call stage.nativeWindow.addEventListener() with Event.CLOSING to hear about a CLOSING event that is sent after the EXITING event. It also is not cancellable with preventDefault(), even though both report true on their cancelable properties.

[Edit: Note that if the PlayBook is set for "Showcase" mode, where apps are left fully running even when you switch away from them, you may never receive a DEACTIVATE event. You shouldn't rely solely on this event to signal that it's time to save your state.]

PlayBook Screen Template

2010-12-19T10:00:00Z

One of the first things I did with the PlayBook -- or, rather, with the lack of one -- was to build a simulator. Not the SDK simulator... everyone has one of those. I mean a physical one. It's nothing more than an old copy of a Rand McNally world atlas with a couple of sheets of thin steel wrapped around it to stiffen it and add weight, some black construction paper and a sheet of clear plastic for the screen area.

It has the same dimensions as the real thing except that it's thicker. Turns out there aren't that many materials with the same density as the PlayBook (1.6 g/cm³)... straight metal is way too heavy, paper is too light, and although a solid block of magnesium would be almost perfect I just didn't have any kicking around. The combination of paper and metal brings this one to precisely 400g; I figured having the right weight was more important than having the right thickness.

To simulate the screen I can slide a screenshot under the plastic window. I can also just use it to draw screen designs on paper and often tape them to the front on top of the plastic. At the moment I have about 10 sheets representing different pages of the app taped one on top of the other so I can flip through them.

The screen area of the PlayBook, based on 0.15mm per pixel and 1024 by 600 pixels, is exactly 153.6mm by 90.0mm. A regular A4 sheet of paper (8.5" by 11") turns out to hold three of those screens nicely.

I'm making a PDF available for anyone to use if they want to make their own simulator, or just want to draw some screen ideas on paper. The Python code (using ReportLab) is also available:

PlayBook: Showing System Menu

2010-12-17T15:00:00Z

On the PlayBook, not only can you drag from the lower left corner to make the virtual keyboard appear, but inside an application you can still get the System menu to appear by dragging from either the left or right upper corners.

The top bezel "swipe down" action is reserved for applications to use for their own purposes, but they've left a region about 50 pixels wide at either end along the top edge of the viewable region where if you swipe down you'll get the System menu instead of the application's own menu.

So far, I can't see anything associated with the bottom right corner. [Update: although this may of course be different by the release date, or the third beta SDK, the bottom right swipe would trigger an orientation change. Since the simulator doesn't support this yet the swipe is ignored.]

ActionScript: Useful Bits #1

2010-12-17T06:25:00Z

I'm rather new to ActionScript3 (and AIR) though I've done a lot of Javascript in the past. In fact, I'm so new I wasn't aware until a week ago that ActionScript had evolved so much since I first checked it out when AIR was in its first beta. I was impressed to see that it is now a "real" language. Anyway, following are some random notes covering useful features I've stumbled over, as a reference for myself.

String Operations

The String class is okay, but still feels a bit clunky (compared to strings in Python) for your basic wet work. There are a few utility routines buried in different places that look useful.

Package mx.utils.StringUtil has a few goodies, including:

restrict() to strip out unwanted characters (could also use a regex)
substitute() does what it says, like %s in C and various techniques in Python
trim() removes leading and trailing whitespace. What, they couldn't put this in the base class?!

Debugging

mx.utils.ObjectUtil.toString() gives a great debug dump of any object, and the class has a bunch of other useful functions like dateCompare() and copy() and clone() (though it's unclear to me what's different about the latter two).
flash.utils.describeType() barfs back an XML representation of an object, with signatures for all methods, properties, etc.
flash.utils also has getDefinitionByName() for retrieving classes by name and getQualifiedClassName() for retrieving names (String) of classes.

PlayBook Internals: Part 1

2010-12-16T08:30:00Z

As mentioned in an earlier post I've been perusing the PlayBook simulator's filesystem in an effort to learn more about its architecture so I can improve my ability to build good apps for it.

PPS Service

I didn't know anything about QNX before getting into PlayBook development, but one very interesting looking technology from that side is the Persistent Publish/Subscribe (PPS) mechanism that was added fairly recently to QNX. Paul Leroux has written a nice overview on PPS.

I can see signs this may be used in numerous interesting ways in the PlayBook, though possibly it will all end up being under the covers, hidden behind API calls that make it look like something else.

For now, my main use of it has been to toggle development mode (which you can just do through the UI anyway) and to change my wallpaper (which will obviously be supported later but which I'm happy to be able to do now).

I think I'll ask someone at RIM whether they'd consider documenting a number of the PPS objects and attributes for developers to use. It would likely let us get more things working for the initial release date than it currently appears we will be able. Maybe it would also let RIM focus their efforts on more critical things than, say, exposing an API for changing the wallpaper.

Python 2.7

Wow... I didn't expect to see this here. I have no idea if it will survive into the release version, but it looks like someone had the excellent idea of using Python (2.7) to manage firmware updates (or maybe it's something else...) in the PlayBook. Python has proven highly effective (and robust) in such roles thousands of times over, and I consider this another sign of strong technical merits in the product, even if they never expose Python to third-party developers.

On the other hand, if they did provide some API support for Python (or just let others build one), I think it would be great. ActionScript3 is fun and all, and especially effective for UIs (duh), but for the business logic in a complex app it's hard to beat Python for productivity and simplicity.

qconn

The qconn service provides an interface used by the QNX Momentics IDE for remote debugging. Since this is listening on port 8000 and announces itself rather clearly, I figured it's safe for me to mention it:

$ telnet pbsim 8000
QCONN
<qconn-broker>

Try the "info" command for output that largely duplicates what you can see in the PlayBook Settings "About" page in the simulator.

This isn't much use right now to most of us, but will obviously be a huge boon for those using the native (C/C++) SDK when it's released, as it should provide support for (among many other things) profiling, memory analysis, tracing and other debugging goodies.

PlayBook Remote Debugger

2010-12-16T00:12:00Z

Since I don't have any Flash/Flex development tools other than the freebie command line stuff, I tried using the command line debugger to monitor trace() output in my ActionScript code. It didn't work.

The BlackBerry Development Knowledge Base has an article called Compile and Debug without Flash Builder Using a Command Line which describes how it's supposed to work.

In a nutshell, you compile with -compiler.debug, and package with -target bar-debug -connect [YOUR COMPUTER'S IP ADDRESS]. This sets up the application to connect back to your PC when it runs. Before you launch it, you run fdb locally, then enter the run command. At this point the debugger starts lisening on port 7935 for connections, and you go deploy/launch your app.

At this point, magic things should happen. They don't, at least for me. I'm pretty sure it's an incompatibility between the version of the debug fixture code built into the app and the version of fdb in use. Either way I had no luck, and things would simply stall until the app gave up and continued, while the debugger showed no activity.

So I built my own debugger. Using Python, naturally. It's very crude, but since all I wanted was the equivalent of "print" statements (which in ActionScript3 is your trace() calls), it's Good Enough.

In all it's crude glory then, I present pyfdb and the following instructions for use:

Build your app for debug mode.
Launch the debugger: python pyfdb.py
The debugger should print "listening on 7935" (the Flash debug port)
Deploy/launch your app.
The debugger should show interesting things, followed by the output of any trace() statements in your code.

I'm absolutely certain there are many things it could do that it doesn't, not the least of which is sending back from the debugger to the application a bunch of configuration changes that I can see fdb send when I connect to it with telnet.

But it works for me. Released under the Simplified BSD License.

Download it here: pyfdb v0.0

PlayBook Internal Secrets

2010-12-15T22:41:00Z

While building a filesystem explorer I discovered several mechanisms left for developers, which let you get into the PlayBook simulator. The most obvious and useful one is a simple telnet interface, to which you merely need to know the userid and password (but these were pretty obvious). [This feature was replaced with an SSH interface in more recent versions. -Ed]

Over the next few days I'll be posting details about some interesting discoveries I've made, not the least of which is that the unit will have Python 2.7 inside!

Edit: after re-reading the BlackBerry Table OS SDK License Agreement, I think I'd be wise to take into account section "12. Confidentiality". I'll limit myself to things that are fairly far from being considered potential trade secrets or RIM-confidential information. That means I'll just go hide my draft article that describes the filesystem layout...

BlackBerry PlayBook Webcast 5 of 5

2010-12-09T14:00:00Z

This post contains notes taken during the PlayBook webcast on December 9, 2010, not necessarily understandable out of context.

BlackBerry Payment Service
- can use for digital stuff, in-app only
- not for physical goods, shared across apps, or virtual currencies
- one approach: free app with paid upgrade/turn-on of features
- 70% share to developer
BlackBerry Advertising Service
- RIM partnership with many ad agencies
- 60% share to developer (supposedly standard in industry, but AdSense is 68%. - Ed)
- device-side SDK simplifies it all
- HTML 5, rich media, app world click-throughs
- mediation platform: can customize to e.g. exclude an advertiser/network
- can specify keywords to exclude certain ads that don't fit your app
- full schedule available "soon"
BlackBerry Analytics Service
- powered by Webtrends
- see who is using your app how, when, where
Free BlackBerry PlayBook Offer
- one tablet per vendor
- free marketing around the apps
App World Approval Process
- 10-day turnaround
- submitted, reviewed by RIM, then approved (or feedback)
- vendor then lists app in App World
- code-signing apps: Dec 15 will open new servers, free, no cost for keys
- differences for PlayBook from regular BlackBerry: just the .bar files
Questions (long but incomplete list)
1. BlackBerry/PlayBook app sharing? No
2. Monthly subscriptions in-app: how? Alex outlines an approach.
3. When will simulator have sound? Later...?
4. Can users opt out of analytics service? No.
5. Czech Republic: is free PlayBook offer available there? Yes.
6. To register as vendor? No promo or code needed now, need PayPal to offer app for sale.
7. Is there a Bluetooth API in AIR to connect PBs together? APIs not solidified yet.
8. When will Payment SDK be avail? For BlackBerries, now. For PB will have sched "shortly".
9. SWF decompilation risks? "Theoretical maybe but risk is limited by security features, e.g. code-signing. Major risk is loss of IP, consider other tools to help." (paraphrased)
10. In-game currency, can I use third-party system for that? Yes.
11. What are in-app credits? Buy something to use in future, effectively virtual, so no.
12. PlayBook has existing gestures, how do we add others? Swipe down is only app-wide gesture available to developer. Can role own but have to be within screen, not from bezel. (So you can't override app-switch side-swipe in your app, but you can do one within your own app.) See qnx.application class or forum for more.
13. How do I get code-signing keys? Go to portal, need credit card to validate identity.
14. Can I use GPS from Torch in PB app? Not defined yet.
15. Will Flex Mobile apps compiled with Hero be approved by App World? Should be. Reasons you might get rejected won't be related to the technology used.
16. What is cost for registration? Waived... free for now to register or submit apps.
17. Timeline on app approvals etc? 10 biz days. For PB apps will be longer. Should see some approved before end of year. Should be 10 days by launch.
18. Can we provide app for free and charge for use? Yes.
19. Will PB support USB storage etc? At launch: USB slave not host (so no).
20. Does PB have native text-to-speech API? Not yet.
21. Are there plans for Adobe Flash Pro to publish for PB? Yes, planned.
22. Will PB support SilverLight? Not planned.
23. Will AIR support geolocation soon? GPS will be on device... (?)
24. Can we reserve app id etc ahead of time? Yes, can do in advance...
25. What is cost to publish on App World? Today everything is free...
26. If more than 10 days to approve app (so it's past launch date), can we still get free PB? Yes!
27. Support USB On The Go (USB OTG) in future? Can't answer that today. (But note Mike L's clear indication that they can support an Ethernet interface via USB, so it's clearly more than a simple USB slave, in hardware.)
28. When does WebWorks for BB training start? As soon as tool gets out.
29. If app approved, when will freebie ship? Mike says ahead of launch... contradicts web.
30. Can we get full schedule for release of unsupported APIs? Yes, will get it together and Renaun says there's some info in release notes already.
31. Does existing PB have GPS? Yes! (We have yet to hear another confirmation of this, which was clearly stated but still may possibly have meant just "using GPS on tethered phone". -Ed)
32. Will external KBs etc be supported? Yes, intended, not sure of details.
33. Can PB tether to non-BB phone? No answer at this point.
34. Next steps for simulator, cookies, etc? Next version will have browser support etc.
35. Is there much hardware access in PB AIR SDK? Clock etc? Yes, not supported in simulator yet. Renaun says standard APIs supported.
36. Sensors supported? Accelerometer, GPS two biggest. (Note: again a clear mention of GPS on the unit, as a "sensor". -Ed)
37. Does RIM have online training for newbies? No real rookie stuff but lots of docs. On Adobe side, Adobe Developer Connection lots of resources for AIR.
38. Same BB id active on phone and PB? Yes, same on PB for AppWorld etc.
39. Since App World may reject, could a proposed app get reviewed before code developed? Answer: should be no real need, no, but don't worry about it.
40. Hello World avail? Yes. Also "Full RSS Reader" app.
41. Orientation in AIR? Get event, need to adjust height/width etc. If app lays itself out properly it won't actually have to do anything (other than perhaps listening to an event).
42. Can RIM announce when new stuff available on forums? Developer blog used heavily, but maybe they'll get the info into the forums as well.
43. For early approvals, how much will RIM assist in troubleshooting problems since we don't have PBs? Yes, RIM will have to help initially of course. If not using QNX stuff, can test on desktop on webcam etc if there's AIR support for it.
44. What dimension should screenshots be? Will get back to us.
45. Print from PB? Not in core product, will look to community for help.
46. Can you explain digital rights when submitting apps etc? Basically do we have the rights to submit content with an app. User-generated content, e.g. content or stories... do we have safeguards to reject objectionable content etc? Example: keeping porn away from kids.
47. Possible to lock orientation of app? Yes, in application descriptor file (XML).
48. Wire transfer to receive money for apps? Other options being looked at, yes, including wire transfer, direct deposit, etc.
49. In BB dev days in Mexico, would only give away 50 PBs: true? No, the overall offer is for all registered App World vendors, no limits.

Closing or Switching Apps

2010-12-09T10:30:00Z

The first time I built and installed the sample HelloWorld app I was annoyed to find that it didn't include a way to close itself. It has only a "Push Me" button which opens a page to ask for your name so it can greet you with it.

As it says carefully hidden away on this page it's quite simple to close any app, or to switch between them. That page describes "swiping" with the mouse from bottom to top of screen. This has the effect of minimizing the application into a region showing it and all other active applications (if there are any).

The app shown in the centre has a red X widget to let you close it, but you can actually close any of the applications shown by dragging it up to the top of the screen, sort of like a "toss it" gesture. Feels nice... Play a bit and see what else you can do by dragging and swiping around.

Uninstalling apps from PlayBook Simulator

2010-12-08T13:00:00Z

The BlackBerry Help Center page on removing your application using the command line says that the command line blackberry-airpackager utility supports an -uninstallApp argument. In the version I downloaded (as part of SDK 0.9.1) this option is actually on the blackberry-deploy utility (presumably having been moved).

Also, the arguments shown are now incorrect. After checking the help output (by running the utility with no options) and experimenting a bit, the following pattern worked:

blackberry-deploy -uninstallApp -device 192.168.40.128 -password XXX -package MyApp.bar

If you don't have your .bar file, you can use the Package-Id instead. If you don't know it, you can discover it using another option:

blackberry-deploy -listInstalledApps -device 192.168.40.128 -password XXX
blackberry-deploy -uninstalledApp -device 192.168.40.128 -password XXX -package-id YYYYYYY

There's also another approach which may be much simpler in a given situation. The simulator runs a little web server accessible via http and https. The http one seems useless, but if you go to https://192.168.40.128/appInstaller.html (substituting your sim's IP address) you'll see a few useful things.

Your package's Id is available in numerous places including the console output of the deploy tool, the MANIFEST.MF file inside your .bar file (which is just a .zip file with a different extension), or you can find it by clicking on the List button at the end of the above appInstaller.html page.

Once you know it, enter it into the Package Id field and click Uninstall. [This interface was removed in later versions, so use the command line approach described above. -Ed]

Performance Comparison of Micro-Frameworks in Python

2010-04-16T21:05:00Z

Micro-frameworks are all the rage lately. Though they've doubtless existed for as long as Python web development has been taking place, the recent release of bubble, juno, and now Flask have more people talking about them.

I've been fighting with the complexities of the major frameworks for a while now, lately getting fed up with the shocking list of dependencies brought in by TurboGears2, and fighting with Pylons and its view of how I should do unit testing and many other things.

I wanted to try something lighter weight in setting up this new site, which was initially running on a 64MB VPS running Ubuntu 9.04. Pylons was incapable of running in this environment, as merely launching it with the default demo site consumed all available memory! (Note that this VPS allows a reasonable amount of "burst" RAM to be temporarily used, but provides no swap space. Using up memory leads to a hard failure and kills the app.) So I was curious how well the micro-frameworks would do, and how they would stack up against each other.

What follows is a very simple comparison of memory usage and performance of three recent micro-frameworks. The test program was basically "Hello world", taken directly off each framework's web site and adjusted only to ensure the Content-Length was the same. (Note that the header lengths were slightly different: flask sent 15 bytes more because it included the charset (utf-8) in the Content-Type header.)

Performance shows transactions per second (tps) as measured using openload running on the same host.
Framework	Memory (K)	Performance (tps)
Bottle 0.6.4	8900	1680
Flask 0.1	14300	1220
Juno 0.1.2	16350	1570

All three frameworks loaded the CPU to about the same degree.

Other Comments

I don't think it's right to offer benchmark results without some comment on qualitative aspects.

Bottle comes in a single file (39K) and has no dependencies outside the standard library for basic operation. It can integrate with WSGI, CherryPy, Flup, Paste, and Fapws. It features auto-reload and supports several popular templating engines. The source is clean but has no tests included. It clocks in at 844 lines of code plus 181 doc/comment lines.

Flask itself is a single file (25K) but requires Werkzeug (which isn't tiny) and installs Jinja2 (also not small) even if you don't plan to use it. Of the code in that file, over half is comments: only 215 lines of code, 376 doc/comment lines! As it builds on Werkzeug, you can likely make use of most of the functionality included in that package.

Juno is also a single file (31K) with no non-stdlib dependencies for basic operation. You can also run behind WSGI, SCGI or FCGI (with Flup), or Google appengine. The code appears clean, reasonably commented and organized, with no automated tests included. It manages what it does in only 536 lines of code, with 168 doc/comment lines.