Developing for the Iliad (2): Software environment and API libraries

Disclaimer: The following information was largely obtained experimentally by trial and error. In the absence of official developer documentation from iRex on these topics, it may no tbe correct in all circumstances or for all versions of the Iliad. Check it for your device before you rely on it.

Word sizes and endianness

The Iliad's processor is little-endian. The sizes of C types are the same as 32-bit i386 processors, differing from 64-bit x86_64 processors in the size of long and pointers:

Auxiliary processes and inter-process communication

The Iliad runs a number of programs handling specific parts of its hardware. Application programs communicate with some of them via an inter-process communication API library, while some have a library of their own.

Auxiliary processes

The following lists the Iliad's auxiliary programs, their executable and the library used to communicate with them (if applicable). The library links go straight to the documentation of the relevant header file on Hans Pelbers' Iliad doxygen pages.

Content lister: /usr/bin/contentLister, liberipc

The content lister can hardly be called an "auxiliary" program. It serves as the high-level operating system of the Iliad. It is one of the last programs to be started by /home/root/start.sh, and the Iliad shuts down when it terminates. It starts, keeps track of and can interrupt applications. Two of its threads poll the Iliad's buttons and generate key events for them, respectively. Applications typically need not communicate with it directly.

Power manager: /usr/bin/powerMgr, liberipc

Watches battery level and alerts the content manager when the battery is low. (The content manager will then warn the user and possibly shut down the device.) Applications need not care about it.

Display manager: /usr/bin/displayMgr, liberdm

Handles redrawing and erasing the physical electronic paper display. This has to be triggered whenever the screen content has changed.

Busy LED daemon: /usr/bin/erbusyd, liberipc

Handles the multi-colour LED in the upper left corner of the Iliad.

Page bar: /usr/bin/pageBar, liberipc

Draws the page number bar at the bottom. Functions include setting the number of pages and the current page and redrawing the page bar. Notifies the application of clicks on a page number via inter-process communication.

Toolbar: /usr/bin/matchbox-panel & /usr/bin/mb-applet-icon-container, liberipc

Manages the icons between the page bar and the display area. It allows to select the set of icons to display in the left part of the icon bar and notifies the application of clicks on the icons.

The many kinds of application IDs

Inter-process communication (IPC) requires IDs for the processes concerned in order to direct messages to their recipients. In addition to the two really needed ones (at the top, in bold), the following table displays other application IDs used elsewhere in the sources or registry.xml.

Identifier	Data type	Used in	Comments
IPC channel	numerical	liberipc	For sending and receiving IPC messages
uaID	numerical	liberipc	For toolbar and pagebar functions
uaID	string	liberreg; content lister	Used to create list of applications
ipcChannel tag	numerical	application section of registry.xml	Different from IPC channel in liberipc; unused?
xResourceName tag	string	application section of registry.xml; content lister	Used to manage list of running applications
type attribute of application tag	string	application section of registry.xml; manifest.xml for setup and network profile applications	Allows running non-viewer applications from manifest.xml

The IPC channel and the uaID are related one-to-one by the macro erIpcGetChannel hard-coded in eripc.h. Neither of them offers ways of adding new IDs for new applications — their ranges are hard-coded in the eripc library. I have used the channel and uaID of the PDF viewer for my own programs without apparent problems.

Screen output and user input

Graphics output

There are multiple possible ways of drawing on the Iliad's screen, and most viewer programs seem to use several of them.

GTK

The GTK GUI toolkit is used by programs presenting dialog boxes, such as the setup application, the network profile manager and also the content lister. The content lister seems not to generate button and pen events for non-GTK applications, so all applications will need to initialise GTK.

The frame buffer device /dev/fb0

Applications can also write directly to the frame buffer device. This makes sense especially for pixel graphics and line art. The frame buffer stores one byte per pixel (of which the display can only represent the upper four bits) in row-major order. The most convenient way to access the frame buffer is to map it into memory, which allows random access by pointer.

X11 libraries

X functions could also be used for screen output. The X display and window IDs can be obtained from GTK.

Applications should avoid drawing over the screen regions of the toolbar and the page bar unless they do not use them. Constants of their coordinates are defined in display.h of the erdm library.

Screen update

The Iliad differs from Linux PCs in that the display is not updated regularly automatically. Updating an electronic paper display takes a certain amount of power, so this is something to avoid unless necessary.

The erdm library contains functions for communicating with the display manager, which will perform screen updates on request. Updates can be performed with different priorities (speeds) and qualities. Only the highest quality uses the full 4 bits the display can represent. The others use 2 bits or one bit, respectively. I have always used 2-bit quality for displaying text.

The different update speeds / priorities are something that one can only speculate about. It may be that the faster update modes require more power and that slower updates can therefore help preserve energy. (Otherwise, why support the slower modes at all?) Possibly the higher-quality updates are not compatible with high speed. (This could be found out by experimentation.) I have used the 0.1-second updates exclusively so far.

Lastly, it seems to be possible to update only part of the display. The content lister uses this to move its cursor, and the toolbar to switch icons on and off. According to a comment in erdm.h, this is not implemented in the display manager. So you will have to consult the sources of the content lister and toolbar if you want to try it.

Key events for the Iliad's buttons

The content lister polls the Iliad's buttons using ioctl calls and generates X key events which GTK translates to GDK events. The events are generated only when an application has been started by the content manager. It seems that the application has to have initialised GTK, as I have not managed to receive button events with X-only programs. So the following table gives the GDK keycodes only. The ioctl codes are given for completeness, but you are not going to need them unless you want to poll the button devices yourself.

The other six buttons (Main menu, Connect, Books, News, Docs, Notes) are handled by the content lister itself, and no key events are generated for them, so they cannot be used by applications. The sense of the page bar (left forward or right forward) is inverted by the content lister depending on the user settings. The busy LED is set to busy state when the key events are generated, and depending on user settings button events may be blocked until the application has reset the LED state.

Stylus events

Stylus input is reported as mouse events. Putting it down generates a button press event (with associated coordinates), dragging it a mouse movement event, lifting it a button release event.

TOS / Impressum