Pixecutor is a hardware hack by JasonHarper that allows arbitrary code to be run on a JuiceBox from a SD or MMC card. I believe that it is the simplest possible method for doing so, assuming that you already have a SD/MMC adapter of some sort. Pixecutor consists of a small microcontroller connected to the JuiceBox's JTAG port. It uses the debug features built into the ARM7 CPU to detect when a specially-formatted picture has been loaded in the picture viewer, and causes it to be executed rather than just displayed - see /PixecutorTheory for more details. The code it runs can either make full use of the uClinux kernel contained in the JuiceBox, or ignore it and work directly with the hardware. However, there are a few limitations:
- It's completely incompatible with JTAG debugging.
- There isn't a whole lot of memory available, if you're going to run under uClinux - perhaps as much as 500K if you kill every possible task, but it's badly fragmented.
It appears to work on 8MB JuiceBoxes (based on a single sample so far), however there's no more available memory than on a 2MB unit - the rest appears to be simply ignored.
- There is no persistent storage available - the SD card is read-only, apparently an intentional limitation of the driver.
The only way to have a Pixecutor program automatically launch on boot is to hold down (or short out) the Play button. The "JuiceBox" sound clip will still play every time you turn the unit on, at least until you violently rip the speaker out of the case.
INSTALLATION
Here is the Pixecutor code (MPLAB 7.5 assembler source and .hex object), intended to be programmed into a PIC12F508-I/SN: pixecutor.zip . This is a SOIC-8 chip, chosen because it fits directly over the pads it needs to be soldered to, and is small enough that the case can still be closed without modification. See http://www.instructables.com/id/E1MF1CGOQLEXCFFOXD/ for step-by-step illustrations of how to install this chip.
If you'd prefer to use a DIP-8 chip (PIC12F508-I/P), for which programming hardware is much more readily available, that will work just fine. However, it will take a lot more room - you'll either need to leave the case open, or cut a big hole in the battery compartment and use an AC adapter exclusively.
Either of the chips mentioned above can be substituted with a 12F509 (which just has more memory), if you can't get a '508. The "-I" in the part numbers can also be changed to "-E", indicating an extended temperature range part (but those are likely to cost more and be less available). The code can be easily ported to any other baseline or midrange PIC, you'd just need to change the pin definitions, and add any needed chip-specific initialization. If you'd like to port the code to an entirely different microcontroller, you're on your own - but it shouldn't be too difficult, most of the functionality is expressed via macros rather than raw PIC code.
DEMO SOFTWARE
Download PixecutorDemos1.zip and unzip into the root directory of your SD or MMC card. The files must not be inside a folder, as the JuiceBox's picture viewer cannot find them there. You may also be interested in shelly_serin_source.zip, the source code to two of these programs.
serin
This is a simple little program that works around the fact that the receive side of the JuiceBox's serial port driver has been disabled. It reads characters directly from the serial port hardware, echoes them, and performs basic line editing (Ctrl-H or DELETE to delete the last character, Ctrl-X or Ctrl-U to delete the entire line). When you press ENTER, the edited line is sent to standard output, which can be piped to another program (such as /bin/sh, to get a working shell).
TODO: rewrite serin to use a pseudo-TTY instead of a pipe, so that it becomes a complete replacement for the half-disabled serial driver.
shelly.jbp
This is a basic Pixecutor program that uses serin and /bin/sh to give you a command prompt on the serial port. Obviously, you need to add a serial port to your JuiceBox for this to be of any use. Note that no job control is available, due to the way serin is currently implemented: if you run a program that doesn't quit on its own, you can't hit Ctrl-C to stop it. Any such program should be run in the background (by adding a "&" to the end of the command line), in which case you can use the "kill" command on it.
The actual command that shelly executes is:
cd /ram; cp /mnt/serin .; serin | sh -i
serin is copied to the ramdisk and executed from there, so that it's possible to unmount the SD card - that wouldn't work if a program was running from it. The "-i" parameter is needed to convince sh that it's actually receiving input from an interactive user - that's something else that would be fixed by a rewrite of serin.
It is intended that you can make copies of shelly.jbp, and modify the command it executes in a hex editor. Just search for the text "command" to find the existing command, and type over it. Make sure that your hex editor is in overwrite mode - you don't want to do anything that inserts or deletes bytes in the file, just change them.
scripty.jbp
This is a copy of shelly, modified (as described above) to execute the command:
. script.txt
In other words, it just executes shell commands from the file script.txt on the SD card. The supplied script.txt contains commands to display a warning icon that's in the romdisk, but is never actually used by the JuiceBox software as far as I've seen. You can edit it to do whatever you want.
NANO-X DEMOS
The JuiceBox contains version 0.89pre7 of the nano-X graphics system, with some modifications. It's used by the picture viewer/MP3 player application, and is running when a Pixecutor program starts - so why not make use of it? Most of the nano-X demo programs are useless on a JuiceBox, due mainly to the small screen size and lack of a mouse, but some are interesting.
nanowm
This is the nano-X window manager, which adds a nice border, a draggable title bar, a close box, etc. to all nano-X windows. None of those features are actually useful without a mouse, however it makes nano-X programs look much nicer. The JuiceBox version of nano-X was modified to never erase the background of the root window, thus allowing the JuiceBox splash screen to remain visible while nanox and the music/picture player application are loading. This means that any window that's smaller than the full screen would appear on a background of garbage. With nanowm running, you get a solid blue background instead.
nanowm never exits, so it must be invoked via nanowm &.
TODO: modify nanowm so that its window manipulation features can be used via the JuiceBox's buttons. Unfortunately, many nano-X features that would make this easier weren't added until after 0.89pre7.
nxclock
This is a basic analog clock that uses nano-X. It's not terribly useful, since the JuiceBox doesn't have the hardware necessary to maintain the time while turned off.
nsaver
This is a multi-function screensaver, although some of the individual savers don't seem to work very well on the JuiceBox. It takes a single numeric parameter, specifying which saver to run. Note that a missing parameter, or a parameter of "1", just blanks the screen, which isn't too interesting.
Lightning&Clock.jbp
This is a Pixecutor program that launches nanowm, then nsaver showing a nifty lightning bolt simulation, and then nxclock on top. This is usable without a serial port mod. The actual command executed is:
nanowm & sleep 1; killall pvplayer; sleep 2; nsaver 6 & sleep 2 ; exec nxclock
Those 'sleep's are needed to give the prior command time to fully take effect - there seem to be memory problems otherwise.
TINYGL DEMOS
TinyGL is a subset of OpenGL capable of running under nano-X. Its performance isn't really impressive on the JuiceBox due to lack of a floating-point coprocessor, but it does work, with the main limitation being available memory. Only two of the four demos that come with the TinyGL distribution will actually run on a 2MB unit:
spin
This is a simple wireframe box that spins on its axes. The STOP button exits this program.
gears
This is a more complex demo, showing three rotating meshed gears. STOP exits, and the other four buttons rotate the scene around different axes. However, due to the fact that this demo only runs at about 1 frame per second, there is a tremendous amount of lag in the response to the buttons. Holding down any button for more than a second will lock up the program, perhaps due to an event buffer being filled.
TinyGL_spin.jbp, TinyGL_gears.jbp
These are Pixecutor programs that launch the two demos above, along with nanowm. There is no possibility of the demos themselves being compiled as Pixecutor programs, which have a size limit of 56K.
WRITING YOUR OWN SOFTWARE
See /PixecutorDevelopment for info on writing software to be run via the Pixecutor.