Firefox OS Simulator R.I.P. (Game Programming)

I've been writing this blog for about 4 months and have written 73 posts, half of which are about programming games for the Firefox OS on the phone (the other half are reviews of Firefox OS games on the phone). I still have lots to write about on making games, but yesterday when I went to install the first part of a series on a new game type, the Firefox OS Simulator greeted me with this note:

I've been using the Simulator to install my game code on my two phones (ZTE Open and Geeksphone Peak) and it has never let me down. I knew there was a better solution from Firefox OS called App Manager, but it required that my phones have Firefox OS 1.2 or greater. And, having heard horror stories of phones being bricked, I wasn't eager to try to flash my phones. I use the Peak every day for programming so I didn't want to risk losing it, and there have been some problems with the ZTE Open.

But now this message worried me. I tried the Simulator and ... it didn't work! The latest "normal" Firefox is 26 and I'm usually working with Nightly, so I was in trouble. Well, maybe flashing my Peak won't be that hard. Well, it was hard, but I'm now the proud owner of a Firefox OS version 1.2 Geeksphone Peak.

More about the installation later, but the first thing I did once I had a working phone was to try out the App Manager. It is really worth the trouble, because it does lots more than the old Firefox OS Simulator (which helped me do about 35 posts). The features that stand out to me:

1. You can see a little more progress when the app is loading onto the phone. In the lower right corner, there is a nice little window that tells you you're connected and the status of your loading.

2. You can actually debug apps running on the phone with your PC. Here's an example of some console action, courtesy of the App Manager:

3. You can take screenshots by clicking on a button in the App Manager. You can even run  apps on your phone and do the screenshots from your PC! Taking screenshots is a pain. Here is a screenshot from the App Manager:

Here is a screenshot from the actual phone (Power Button + Home Button):

There are only minor differences, but the saving of time and trouble is nice. There's lots of other stuff I need to explore, but it works, and some of the other debugging features will come in handy as I do more complicated things. Especially for phone-only features that can't be simulated on the Simulator. No amount of tilting my PC will work on the Simulator for Device Orientation. The only small hassle is that the App Manager only works if you zip up all your files into a single package. If you make lots of changes, this can take a little bit of extra time. Fortunately for most Firefox OS features, you can just test out your app in the Firefox desktop browser, and that's a very fast turnaround cycle!

You can read all about the App Manager here: https://developer.mozilla.org/en-US/Firefox_OS/Using_the_App_Manager. App Manager isn't a plug-in, but comes with any Firefox browser that is version 26 or higher. When you first run it (from the Developer Menu), it will ask you to install a 1.2 or 1.3 simulator and some ADB software from our friends at Google Android (ADB = Android Device Bridge). 

So I'm busy at work and you might be guessing that my next post will be about a cute little fox who escaped from a Pac Man game written in another dimension. Later!

What Went Wrong?

Mozilla provides this great article on how to upgrade a Geeksphone: https://developer.mozilla.org/en-US/Firefox_OS/Developer_phone_guide/Updating_and_Tweaking_Geeksphone. Great except for one tiny thing that threw me off for an hour or two. I'll get to that, but first I'll outline the steps.

1. Make sure your phone and PC are ready. They recommend this article: https://hacks.mozilla.org/2013/05/pushing-firefox-os-apps-to-the-geeksphone/. Essentially you must have your drivers in order (especially if you have a Windows PC, which is what I used, and I expect a few others do also). Drivers in Windows are always "interesting" and especially anything to do with USB drivers is always a problem. The actual USB architecture is pretty lame, and tries to squeeze too much, too fast, through a thin pipe. But Device Manager is your friend (or perhaps the Girlfriend from Hell) and you can get it to work. I'm on Windows 7 and my PC is a four-year-old Asus laptop. Essentially for my setup, everything works if Device Manager shows me this:

2. Get the proper image of the new OS you want to flash to your phone. Geeksphone is very good about this (and ZTE Open not so good). They offer stable (1.2) and unstable (1.3) and nightly, and I picked 1.2 because that's all I need right now, to make App Manager sing.

Get it here: http://downloads.geeksphone.com/.

3. Make sure Remote Debugging is set up on your phone. I already did this (but checked) because you need this for the Firefox OS Simulator. It's in the Developer section of your phone.

4. Unzip the image you got in step 2 and put it somewhere on your PC so you can find it later. I stuck mine in the root of the D: drive.

5. Open up a Command Prompt window (also fondly known as the DOS Box, but DOS is only emulated these days). Navigate to your image folder. Tip: the folder name is really long, so you can just type the first few letters, insert an asterisk, and press Enter. Then, type:

                       flash.bat

Things will happen. Stuff is copied to your phone. And then ....

6. Something went wrong. I got stuck on an orange screen I'd never seen before. Turns out this is the Recovery Screen and very useful, but no combination of buttons did anything except get me back to this screen, and no phone in sight. An endlessly looping ... BRICK!

What I needed to be at was a different part of the phone innards called the FASTBOOT screen, black with a few options. But how to get there?

The instructions said:

If you are in the process of modifying your phone and it becomes “unresponsive” you should be able to recover it using fastboot with a simple procedure. The following illustrates resetting the Keon but other phones should have a similar process. You will also need to verify that you have fastboot installed.

First remove the USB cable and then remove the battery from the phone for 30 seconds. Then reinsert the battery and press the volume down button while holding the power button for a few seconds. Next reconnect the USB cable and run the following commands from a terminal window in the directory that contains the latest img files described in the first section of this post:

fastboot flash recovery recovery.img
fastboot flash boot boot.img
fastboot flash userdata userdata.img
fastboot flash system system.img
fastboot reboot

This process should recover your phone. If it doesn't seem to work, you may have to try it a second time.

I've read enough to know my ZTE may not have Fastboot, but I'll worry about that later. Peak has it but getting it is ... not exactly what they said. After removing the battery and putting it back in, no amout of pressing the Volume Down and Power did anything except keep bringing me back to the dreaded orange Recovery Screen.

I surfed the web and wore out my fingers on those hard buttons, and finally found one post somewhere that said to press Power AND the both the Volume Up and Volume Down buttons. Something is fiddly with those buttons, but pressing all three worked the first time and I was now in the Fastboot screen on my phone and was able to type the above commands in the command window. A few short moments later my phone rebooted and I was at version 1.2.

As a retired engineer I can appreciate that the Peak only has 4 buttons, and that two of them are attached at the hip. I've seen other phones that required some serious finger and hand stretching to get them to reboot the right way, but I would have preferred a pinhole in the back. For the Peak, I've seen the following ways to get to the magic Fastboot screen:

1. Power + Volume Down
2. Power + Volume Up
3. Power + Volume Up + Volume Down

And sometimes the order is important. #3 worked on the first try, #1 and #2 never worked for me. Just do this:

1. Take the battery out.
2. Unplug the USB cable  (essentially if you don't, the phone is still powered)
3. Wait 30 seconds.
4. Put the battery back in.
5. Press Power + Volume Up + Volume Down (all at once).
6. Plug in the USB cable.
7. Type these commands, one at a time, and let them do their thing:

fastboot flash recovery recovery.img
fastboot flash boot boot.img
fastboot flash userdata userdata.img
fastboot flash system system.img
fastboot reboot

 8. The phone will now reboot after the usual questions (time zone, etc.) you're done!

I couldn't take a screenshot of the Fastboot or Recovery screens, but I found some similar ones that will give you an idea of what they look like.

Recovery Screen

 Here is an image I found somewhere in G-land:

That one's for the ZTE but the Peak recovery screen is orange and has a few more options.

Flashboot Screen

Here is one for an Android device. But don't forget, under the skin, we're all androids!

Of course, mine didn't have a cute little Android or some of the extra device information, but it did have some similar stuff. The point is that you don't want to pick options from this screen, you just want to be on this screen with your phone. Once your phone displays this screen, you can run those mysterious fastboot commands from the command prompt on your PC. The instructions on how to do all this from a Mac or Linux are around, but in keeping with my lazy ways, I went with what was close at hand. I have now put Fedora on two spare netbooks and I'll try building my own images at some point. But for now, my Peak works and I'm back to game programming.

Next up, a series of posts on creating your own version of Flappy Bird, maybe some ASCII art games, a text adventure, a cool RPG, some platformers, oh, and maybe I'll pull these posts together and make a book!

HTML5 Audio Followup (Game Programming)

I'm still deep into HTML5 Audio programming as it relates to Firefox OS. I ran into some interesting problems and filed bug 949129 to make sure I'm not crazy. I'll be working on some work-arounds for the problems I'm seeing so you can still use audio in your games.













This post will cover a few things more I've found, in random order.

Audio Codecs

André Jaenisch pointed out that I didn't explain that MP3 and OGG are not lossless. This means that when the audio file is created, some of the bits are removed so that the file size is smaller. A popular format for lossless audio is FLAC. But this blog is all about Firefox OS gaming and right now, FLAC is not supported. As a matter of fact, MP3 is not supported either.

The original non-lossy formats were WAV (Windows) and AIFF (Apple). There might be an original Unix/Linux format (AU?)  but I've not used it. WMA (Windows), AAC (Apple), and MP3 (Fraunhofer) all use compression to make file sizes smaller, but still sound pretty good. Somewhere in the middle is the open-source FLAC, which uses compression but doesn't lose any quality and is considered lossless.

MP3 is an interesting issue for Firefox. For a long time, Firefox didn't support MP3 directly unless your operating system had already set up support. Because of this, when programming audio for the Firefox browser, you had to make two files, one MP3 and the other OGG. And for other browsers, you might have to add in an Apple codec (but we don't speak Apple here). You can read about Firefox support at https://developer.mozilla.org/en-US/docs/HTML/Supported_media_formats, but keep in mind that this is a moving target.

Very recently, Mozilla announced that they will support MP3 and pay the fee. MP3 costs money right now, OGG is free! The good news is that the MP3 patents will expire in a year or two.

Why does all this matter? If you have your music in MP3 and you convert it to OGG, the lossy audio will become more lossy. Right now, the music I download onto my ZTE Open will play even if it is MP3, but if I want to write a program in HTML5, my best bet is OGG. Firefox will let you program a WAV file, but the WAV file size is larger than OGG or MP3, and for a phone, you always want the smallest of everything.

So the point is, if you are making music for the Firefox OS, create your original file in WAV format (or one of the Apple formats), but at some point, convert it to OGG. But save your original file (lossless) so you can convert it later if you want to program with MP3.

My own personal guess is that OGG will be supported in Firefox OS for a long time, so its a safe bet. WAV is supported, but large file sizes will make it a poor option for phones and tablets. MP3 support will be soon, and I wouldn't be surprised to see in the future support for Apple's AAC, which is catching on fast (because it has smaller file sizes and better fidelity than MP3).

And don't forget, OGG is open source and very cool!

So if you think HTML5 audio is confusing, wait until you get to HTML5 video! But the answer is to start working with Web Audio (not the same as HTML5 Audio) which is supported. I'll be poking into that soon, but there's more pressing matters.

Oh, and I misspelled the cool audio workstation Ardour. Sorry, guys. Get it at http://ardour.org/. 

Globals

According to many wise JavaScript gurus, you should avoid globals. However, I find that I need them to make things simple for small game demos. So in the recent HTML5 Audio post at http://firefoxosgaming.blogspot.com/2013/12/html5-audio-game-programming_10.html,  I had this global definition:

      // Global variables
      var myAudio;

I don't assign it anything yet, because I need to wait until the page loads. This variable is used for the audio object and gets created in the audio constructor here, but only after the page loads:

      myAudio = new Audio("oggsong.ogg");

When working with objects and loading things, you always want to make sure that you know something is loaded before you use it. But also, in this case, if you don't make myAudio global, the function processMyAudio won't know where to find it.

And as part of the making sure, processMyAudio doesn't get called until canplaythrough tells us that the audio is now loaded and ready to go!

If you do these things without some of the safeguards, things might work or they might not. But you want to be sure. But if you don't make myAudio global, the music won't play. Using JavaScript functions is cool, but you want to make sure that everything inside the function can be used.

You can rewrite this program to avoid globals and pass things through function calls, but for now, I want to keep everything as simple as possible. If you want to know more about why globals are evil, check out JavaScript, the Good Parts. The book is difficult but worth reading several times, and I don't always agree with the author, but he clearly knows what he's talking about.

Here's a great picture of the two best books on JavaScript:

The thin book on the left is Crockford's JavaScript: The Good Parts. The thick book on the right is called JavaScript: The Definitive Guide by David Flanagan. Read both and you'll know most of what you need to know. Make sure you get the latest edition of Flanagan, because it gets updated every few years. Note the size difference of the two books, but there's lots of good parts in the bigger book also.

Firefox OS Simulator

The Firefox OS simulator (available to your Firefox browser as a plug-in) is really valuable for debugging audio. Something that runs just fine in the desktop browser may not work on the phone. Why do I bring this up?

If you use MP3 in the Firefox desktop browser, all works well. But not on the phone. If you use OGG, your audio works in the simulator. Before audio, I barely looked at the simulator unless there was a sizing issue, but for audio, it's crucial that the sound works at the simulator level.

What Might Not Be Working

I was surprised to see that two of the audio object's properties, duration and currentTime didn't work in Firefox OS when they work just fine in desktop Firefox. I haven't read all the browser source code yet, but I filed a bug 949129. You can check it out at https://bugzilla.mozilla.org/show_bug.cgi?id=949129. You can read my test code there.

By the way, if you find any kind of bug, make sure you can reproduce it, and file it at Bugzilla. Remember, YOU are Mozilla. Make it better and bang on it today. Especially with Firefox OS, which is still young and growing.

I'll keep you posted.

Next

I'm working on a work-around for the lack of currentTime. I'll also do some short code samples for loop and controls. And there's a sample game I want to get on to next, and maybe some game engines, and oh, yes, more game reviews. And vibration and tilt and oh, the list goes on forever!