The Wikireader is a small, inexpensive device intended for browsing an offline snapshot of Wikipedia. It has four hardware buttons, a touchscreen, a 240x208 monochrome LCD display, a MicroSD card slot, a fairly powerful Epson S1C33E07 32-bit SoC and best of all it runs Forth! The device was designed to use Forth for factory tests, but with very simple alterations to the included software it can be made to run custom applications from source files stored on the MicroSD card.
On two occasions I have written personalized "desk accessories" for this platform. This archive is intended to gather together the materials for those projects as well as some of the reasoning behind their creation. Perhaps some day you might have a useful application idea for this or a similar device?
Technically all you need to write Wikireader applications in Forth is a microSD reader, a computer, a Wikireader and nerves of steel. Thankfully, you can mitigate the pain of trial-and-error testing by taking advantage of the Wikireader Simulator. Windows-specific source code is included, but I have found that it works just fine in Wine on a 32-bit Linux VM. If you have a serial interface available you can access some pins in the Wikireader battery compartment to enjoy wondrous "println debugging" facilities on the device itself. The Wikireader Github Wiki (phew) provides the bootstrap source (archive) for the onboard Forth interpreter, which is the best reference to the vocabularies available for accessing built-in hardware.
The simulator uses a slightly different configuration of Ficl than that on the device and some subtleties of the hardware simulation are likewise inaccurate, but it can get your code a long way toward working correctly on the device. A few "gotchas" I have encountered:
\t) characters. Make sure you configure your text editor appropriately.move in its startup file. The Wikireader does not define this word- I recommend instead making your programs rely on the `cmove` primitive. The simulator doesn't define cmove, so you might want to add : cmove move ; to its startup file.open-file in w/o mode to create and open a file that does not already exist, this operation will fail on the Wikireader. Calling create-file first works correctly on both the simulator and the device. There are probably more wrinkles and minor differences here, but this is the difference that actually bit me.s" to be used in immediate mode; it must be used from within a word definition.
This program was written over the course of about two weeks. Some aspects of the design are rather crude and cobbled together. The lack of a real-time clock in the Wikireader seriously limits the utility of a program like this- while the device can remember what date was last viewed via a timestamp stored in a file called DATE.TXT, the user still needs to manually advance the page each day.
The calendar logic is also implemented fairly crudely- when you step forward to a date it advances a series of registers one day at a time until it reaches the desired date. To move back, it resets to epoch (January 1st, 2014) and steps forward. Time moves slower the further you get from the epoch, and years take noticeably longer than months or days. Writing the code this way was fairly easy to verify, though, and while perhaps this is just validating my laziness I couldn't help but feel it produced a kind of poetic symbolism in its action. When I made the device I figured it would have a lifespan of a few years at most, and the algorithms employed are fast enough within that time range. Better than it ultimately needed to be.
The word-wrapping routines for text display do a fairly good job, and I would later tweak and generalize them for my next project:
The Wikiwriter turns a Wikireader into a desktop writing prompt generator, capable of creating inspiring ideas for overall works, characters and settings.
To generate random ideas, this application loads a series of text files with "chunks" and assembles them together much like a madlib. The rtable defining word handles this data loading process and tracks how many of each chunk type exists in the provided text files. The word any can then pick one of these elements and leave a Forth string on the stack.
Random numbers are generated by a crude but sufficiently effective linear-congruential generator. The seed is written to the MicroSD card after every random number is picked, ensuring that if the device is powered off it will not repeat earlier selections. These constant writes to the MicroSD card may ultimately limit the lifespan of the device, but with casual use it shouldn't pose problems.
This program makes use of several full-screen bitmaps. Rather than write a decoder for a complex image format like PNG or even BMP, I made a Java program (ImageConverter.java) which prepares monochrome images in any common format in the raw format used by the Wikireader's memory-mapped display. The word blit-image can then very easily load a file from disk directly into this framebuffer. The framebuffer is padded to 32 bytes per scanline, and this is taken into account by the utility. I was pleasantly surprised at the speed of this routine with no particular effort to optimize its performance- it may well be possible to use a modified form of this technique to produce smooth animation.