archos-helper

A simple utility for power, display, wifi, and audio management for Archos devices running alternative Linux distributions.

Please note this is work in progress -- there will be bugs.

What is this?

archos-helper is a simple utility that groups together a number of hardware related functions that normally have to be integrated into a Linux distribution in various different places. This utility is not a substitute for proper integration, but might make a Linux distribution more useful pending full integration.

Archos-helper has three parts, not all of which will necessarily be needed.

  • A server daemon. This is expected to be launched by an X session, and persist for the duration of the session
  • A client library and API. This is what other apps will use to interact with the daemon
  • A GUI application, which makes use of the library

The archos-helper daemon

The archos-helper daemon does the following:

  • Takes actions when the unit appears to be idle. These actions are configurable, and might including screen blanking, shutting down wifi, or suspending to RAM
  • Collects and makes available battery charge level
  • Takes actions when battery charge appears to be critical -- warns the user and eventually puts the unit to sleep
  • Controls the suspend-to-RAM process, including preparing the hardware (A5 has neither ACPI nor APM).
  • Provides a way for other applications to
    • Control audio volume, EQ, 3D effect, and speaker
    • Control screen backlight, brightness, contrast, and gamma
    • Pop up messages on the screen without additional software
    • Suspend or shut down the unit, with or without prompt
  • Monitors the hardware buttons, and makes the volume buttons control the volume as they should. The 'power' button raises the GUI (this is the only place where the daemon has a dependency on the GUI, and this could easily be made configurable)
  • Monitors wifi status
  • Allows applications to raise and lower the wifi connection (actually, this is mostly done with scripts -- the daemon just provides an abstraction of those scripts for other apps)
  • Provides an interface to the USB control scripts, so that applications can control the sharing of files over USB
  • Provides a way for the an application (particular the archos-helper GUI) to raise the desktop, in case a recalcitrant application gets on top of it and won't respond
  • Maintains a sleep timer, so that the unit can shut down after a specific time even it does not appear to be idle (e.g., when streaming audio)

The archos-helper daemon uses only Xlib and should run on any X-based Linux distribution for the Archos unit. It should be modestly useful even without the associated libraries and GUI.

Daemon installation

It is impossible to give detailed installation instructions, because this will depend on the X setup. At the most basic, you could copy binaries to any convenient directory, and then run in the background like this: 

% DISPLAY=0:0 ./archos-helper

For debugging, you may need 

% DISPLAY=0:0 ./archos-helper -d 3 -n

It is important that archos-helper and archos-helper-gui (if used) are in the same directory: The daemon process will use its own pathname to work out how to invoke the user interface. /usr/bin is probably a reasonable choice for installation.

In general, archos-helper needs to be invoked by whatever starts an X session. The X server should be running and the DISPLAY environment variable saying something sensible (probably 0:0). archos-helper will continue to attempt to connect to the X server at two-second intervals, idefinitely. Closing the X server will automatically cause archos-helper to exit, ready for the next session.

In Angstrom Linux, the locations to configure archos-helper are 

/etc/X11/gpe-login.setup

For the login session and 

/etc/X11/Xsession.d/69ipaq-sleep

for the user session. These both contain a reference to ipaq-sleep, which should be changed to archos-helper. Note that the program daemonize itself unless invoked with the -n switch.

=== archos-helper daemon caveats ==

  • If you want to use the volume and power keys, you'll need to ensure that no other X application (window maanger, keylaunch) has bound those keys. See also the section on key mappings below.
  • The daemon is not intended to be run as root. Where it does not root permissions it can be configured to use sudo and this is, in fact, the default. Consequently, a working sudo is more or less essential to use archos-helper.
  • The previous point notwithstanding, most like archos-helper will run as root if invoked from an X login session (rather than a user session). You can maintain separate configuration files for root and normal users (see below), but it's probably easier to make the defaults work correctly for both kinds of user. Typically that means allowing sudo to be run by root (perhaps oddly, this is not the default).
  • archos-helper attempts to disable the X screensaver whilst it is running. This is because the screensaver can't turn off the backlight, so you get a white, lit screen. Worse, it wakes up' X for the purposes of archos-helper`, so you can't completely overcoming the problem by making the screen blanking timings shorter than the X screensaver timing. However, the version of X in Angstrom does not respond correctly to the API call that is supposed to shut off the screensaver, so you still get ten seconds or so of white screen every ten minutes or so whilst the unit is idle.

In use

In most circumstances archos-helper is invisible. If your key bindings make sense (see below), you should be able to bring up the user interface by pressing the power button. From there you can adjust the backlight and audio properties, see the battery charge level, or suspend/shut down the unit. You should be able to adjust the audio volume using the volume keys. The daemon will pop up low battery and other warning messages; it doesn't need any additional software to do this.

Because there are problems getting the power button recognized by X, you can also invoke the UI by `rocking' the volume buttons, that is, pressing one straight after the other. I've found that sliding my finger along the switches is the best way to do that.

Archos-helper daemon configuration files

archos-helper and the archos-helper-uui user interface both look for a configuration file at $HOME/.archos-helper.rc. If there is no configuration file, defaults will be used. It may be easier, in some circumstances, to make the defaults work than provide all users with a sound configuration file -- this is particularly true when running in a login session, where the user will probably be root.

The format of the config file and its defaults are as follows. 

# percentage increase/decrease in volume per button click
volumeStep=5
# idle time before blanking screen on battery power
blankTimeoutBattery=10
# idle time before blanking screen on external power
blankTimeoutMains=30
# idle time before suspending on battery power
suspendTimeoutBattery=180
# idle time before suspending on mains power
suspendTimeoutMains=600
# enable speaker on startup
speakerEnable=0
# blanking mode: 0=none, 1=battery, 2=mains&battery
blankMode=2
# suspend mode: 0=none, 1=battery, 2=mains&battery 
suspendMode=1
# battery level at which user will get low-battery warning
batteryPercentWarn=8
# battery level at which user will be prompted for suspend
batteryPercentSleep=2
# command to power off
powerOffCommand=sudo /sbin/poweroff
# command to suspend
suspendCommand=sudo /usr/bin/suspend.sh

Note that the suspend script should shut down wifi, remove modules and then 

echo standy > /sys/power/state

archos-helper will take care of shutting down the actual hardware and then waking it up again. Please note that at this time there are still some problems with suspend-to-RAM on at least some units.

Key binding issues

X uses two ways to identify keypresses: hardware keycodes and virtual keysyms. In general, a keyboard map in the X server links these two forms of representation together, so that applications can use keysyms without being aware of the hardware keyboard layout.

archos-helper uses keycodes, not keysyms, because there are only three hardware buttons and their codes are unlikely to change. It should not, in theory, be necessary to map these keycodes to keysyms. Howewver, I've noticed that X can be fussy about applications grabbing keys that are not mapped onto keysyms. In that case, you'll need to map them anyway, if your default keymap does not. In fact, the codes used by Archos (122-124) are pretty common on UK/US keyboard for volume and power anyway, and the X server might map them. But if it doesn't, you might need to do so explicitly before launching archos-helper: 

xmodmap -e 'keycode 123 = XF86AudioRaiseVolume'
xmodmap -e 'keycode 122 = XF86AudioLowerVolume'
xmodmap -e 'keycode 124 = XF86PowerOff'

An additional complication is that in Angstrom Linux at least, the power button does not generate an X event at all. HAL does not recognize it as an X input device. Add the following section to /usr/share/hal/fdi/policy/10osvendor/10-x11-input.fd to fix this problem: 

   <match key="input.product" string="atmega-key">
      <!-- If we're using Linux, we use evdev by default (falling back to
        keyboard otherwise). -->
      <merge key="input.x11_driver" type="string">keyboard</merge>
      <match key="/org/freedesktop/Hal/devices/computer:system.kernel.name"
             string="Linux">
        <merge key="input.x11_driver" type="string">evdev</merge>
      </match>
    </match>

If you're not using HAL to configure X, you might need to edit Xorg.conf and specify `/dev/input/event0' specifically as a keyboard device.

Power management modes

In general, the power management daemon controls the power and screen according to settings in the configuration file. The is referred to as 'normal' mode. However, other applications can temporarily overridethis behaviour according to need. The power manager recognizes two other modes 'audio' and 'video'. In 'audio' mode the screen will blank, but the unit will not suspend even if there is no user activity. In 'video' mode additionally the screen will remain active.

Client-daemon protocol

[ Please note -- new features are being added all the time. The following section is unlikely to be exhaustive. Please refer to the source code :) ]

archos-helper listens for client requests on a unix socket at /tmp/archos-helper-socket. The server is single-threaded and clients do not need to be concerned about concurrency issues.

The protocol is text based, each interaction consists of a single line of data sent by the client, and a single line sent back from the server. Because the server is single-threaded, it will close the connection after sending the response, whether the client closes its session or not.

The data sent by the client consists of a one-word command, followed by some data. In practice, most of the commands take a single integer argument.

The response from the server will be an error code, followed by some data. In practice, most of the commands result in no data, or a single integer. The error code is zero for a successful action, and non-zero otherwise. The error code will typically not be followed by a textual description of the error -- see archos-helper-client.h for a full list of error codes and their meanings

The following is a [ partial! ] list of commands and responses currently implemented.

getBatteryPercent, getCharge -- Returns the percentage charge

getDisplayEnabled -- Returns 0 or 1 according to whether the display is enabled

getExternalPower -- Return 1 if the unit is externally powered, 0 otherwise

getPMMode -- Returns the current power management mode

getPowerSource -- Returns 1 if the unit is power by USB, 2 if powered by a dock, 0 otherwise

getSpeakerEnabled -- Returns 0 or 1 according to whether the speaker is enabled

getVolume -- Returns the audio master volume, in the range 0-100

getBatteryMinutes -- Returns an estimate of the amount of time remaining before the battery is exhausted (the unit might suspend before that point)

getBacklightBrightness -- Returns the battery brightness (1-100)

setSpeakerEnabled 0|1 -- Enable/disable the speaker

setDisplayEnabled 0|1 -- Enable/disable the display hardware and backlight

setPMMode 0|1|2 -- Set power management mode: 0 (normal), 1 (audio), 2 (video)

suspendnow -- suspend right now; don't prompt user

shutdown -- shuts down the server (_not_ the unit -- see poweroff)

reReadConfig -- tells the server to re-read the configuration file and respond to changes

[ I hope to get around to documenting the other 50 commands some day :) ]

Archos helper client API

The client API is implemented in libarchoshelper.so, and defined in archos-helper-client.h. Because unix socket overheads are generally low, there is no concept of a session -- clients just call whatever functions are required, and each function internally establishes communication with the server and passes the relevant information. The server is single-threaded, so there are no issues with concurrency between clients, but clients have to be prepared to wait for a response because the server will only service on client function call at a time.

Since there is a one-to-one correspondence between client protocol commands and API calls, and they have essentially the same names, I'm not going to document them separately. :)

The GUI

The GUI application archos-helper-gui is based on GTK+. It is quite resource-intensive, and is not intended to be persistent.

The GUI is intended to provide access to all the features of archos-helper. Currently these include:

  • Changing the power management mode (e.g., disabling screen blanking if you're using an app that isn't integrated with the daemn)
  • Changing audio EQ and effect settings
  • Setting screen brightness, contrast, gamma, and backlight
  • Starting and stopping wifi services, and monitoring the connection state

Legal issues

This code is (c)2009 Kevin Boone, distributed under the terms of the GPL.

Getting the code

The code attached to this page is likely to be out of date. The latest version can always be obtained by checking out the OpenAOS OpenEmbedded overlay.

Attachments