Wi-Fi Interface

The CompactFlash wi-fi interface used was the Netgear MA701 -- now discontinued --, which is the only one "officially" supported. Nevertheless, it should still be possible to procure them through eBay or similar websites.

Other gumstix customers also reported success with different cards, such as Belkin F5D6060 and AmbiCom WL1100-CF. During the first weeks of this project there were attempts to provide support for the Symbol Spectrum24 card using the Linux ORiNOCO driver, but without success in the amount of time available (more in Feral Robot Buildroot Branch).

GPS Receiver

The choice to use a bluetooth GPS receiver, was based mainly on the fact that two such units were available to the the project at its very outset. These are portable devices with independent battery power, providing NMEA-compliant positioning data over a bluetooth communication interface.

Other types of GPS receiver could be attached to the system via a serial port (e.g. HWUART) and powered from same circuit board. The gpsd software (see Feral Robot Buildroot Branch) used to access GPS positioning data can be configured to support various formats, so non-NMEA receivers can be used too.

Sensor Modules

Two Figaro sensors were used in this prototype:

• Figaro AM-4-4161: an evaluation module (with on-board microprocessor that linearises results) for the TGS-4161 carbon dioxide (CO2) gas sensor. The module's output range is 0.0 to 3.0V corresponding to a gas concentration of 0 to 3,000 ppm. After power-on, this sensor module needs a 2-hour warm-up period (for sensor output calibration).
• Figaro AMS-2100: a precalibrated air quality gas sensor module. The output range is 0.7 to 2.5V, but the datasheet does not provide details on how the results are to be interpreted.

Obviously, the choice of sensors will depend on the type of pollutants to be detected or measured in each case. Up to 8 different inputs can be attached in this prototype's setup.

Main Buildroot Trunk

The main development trunk in the gumstix Subversion repository contains the latest version of the generic default buildroot to generate a GNU/Linux operating system image suitable for installation on gumstix devices. The following command would to check out the latest gumstix buildroot into the gumstix-buildroot/ sub-directory:

svn co http://svn.gumstix.com/gumstix-buildroot/trunk gumstix-buildroot

The next sequence of commands would build the cross-compilation toolchain (basically gcc for the ARM processor architecture), compile the GNU/Linux operating system and applications and, finally, package it into a root filesystem ready to install on the gumstix hardware:

cd gumstix-buildroot
make

If all goes well, gumstix-buildroot/ will contain the following items [2]:

• Builbroot source from the gumstix repository:
  • Makefile: main configuration file for the buildroot system, that defines the procedure to build a suitable cross-compiler toolchain (for ARM) on the host computer, as well as which software packages to compile into the root filesystem for installation on a target gumstix device.
  • make/: contains a sub-makefile (with .mk suffix) for each individual software packages (or projects) available for inclusion in a gumstix root filesystem -- such as the Linux kernel, libraries and other operating system components, utility programs and applications. These sub-makefile define instructions on how to download, configure, compile (usually by invoking the package's own build scripts with the environment correctly set up for cross-compilation) and install these software projects in the root filesystem structure.
  • sources/: contains the skeleton of the directory tree produced by the buildroot (target_skeleton/) with template files for inclusion on the root filesystem (e.g. /etc/ configuration files and scripts), as well as patches for the Linux kernel (in kernel-patches/) and other patch files necessary to make the source code of certain software packages suitable for cross-compilation to the target CPU architecture (ARM in this case).
• Generated by the build process (make command):
  • sources/dl/: source code for individual software packages downloaded from the Internet during the build process (make/*.mk), usually compressed tarball format.
  • toolchain_build_arm_nofpu/: working directory for the build process of the cross-compiler and C library.
  • build_arm_nofpu/: contains the output of the build process of individual software packages, with a working directory for each project being built (other than cross-compiler and C library), as well as two special sub-directories, described below:
    • build_arm_nofpu/root/: contains the directory tree and files (initially seeded from sources/target_skeleton/) used to generate, in the very final step of the build process, the root filesystem image which will eventually be installed on a target gumstix computer. The sub-makefiles of most software projects will install binaries, dynamic libraries, runtime data and configuration files, etc in this directory tree, under pathnames as they will appear on the gumstix (for example, build_arm_nofpu/root/bin/busybox will become /bin/busybox in the gumstix filesystem).
    • build_arm_nofpu/staging_dir/: central repository for build output which is further needed as part of the build process, such as the cross-compiler, binutils, libraries, include files. If a software package generates static or dynamic libraries, they should be placed in this sub-directory along with their relevant headers files; dynamic libraries should obviously also be installed in the build_arm_nofpu/root/ directory as well.
  • root_fs_arm_nofpu: binary image of the target root filesystem, containing the GNU/Linux operating system and applications built during the cross-compilation process. Basically this should contain a copy of everything that the gumstix needs at runtime, but nothing that is only required only at compile-time. The filesystem-building tool (mkfs.jffs2) operates on the build_arm_nofpu/root/ directory tree and picks up everything in it, then applies the details from sources/device_table.txt. This file can be loaded to the gumstix through the U-Boot boot-loader and then written to its flash memory to install the new root filesystem (this process is described in Flashing a New Software Image).
  • u-boot.bin: target binary for the gumstix U-Boot boot-loader.

Feral Robot Buildroot Branch

Besides the main gumstix buildroot development trunk, a structure is defined in the Subversion repository for branching different buildroot configurations to meet or implement a specific project's requirements. Several branches can coexist in the repository and be developed independently in parallel, while changes can be merged back and forth between branches or the main trunk.

For this prototype such a branch was created on the gumstix hosted Subversion, not only to track modifications to the custom buildroot's configuration, but mainly to ease the process importing bug-fixes or new features developed in the main trunk (after the has branching occurred). So to download [3] and build a working copy of this customized "Feral Robot" buildroot branch, including extra software for the robostix board (further described in Robostix ADC), the following sequence of commands must be issued:

mkdir feral-robot
cd feral-robot
svn co http://svn.gumstix.com/gumstix-buildroot/branches/users/ddiall/robostix robostix
svn co http://svn.gumstix.com/gumstix-buildroot/branches/users/ddiall/feral-robot \
        gumstix-buildroot
cd gumstix-buildroot
make

The structure of the buildroot system was described in greater detail in the previous section. The full range of changes to the standard gumstix buildroot can be scrutinized using svn log, but below are summarized the main additions or modifications to produce a root filesystem image tailored for this feral robot prototype:

• Created make/utrobot.mk to download, compile and install the actual feral robot client software (described in Client Application).
• Created make/robostix.mk to download, compile and install software to enable communication between the gumstix and the robostix boards, via their interconnected serial ports.
• Created make/orinoco.mk to download, compile and install Linux ORiNOCO driver on the gumstix to provide support for the Symbol Spectrum24 wi-fi card. The attempt was unsuccessful in the amount of time available [4].
• Tweaked make/gpsd.mk to update the GPS daemon (gpsd) and access library (libgps) to the latest version (2.30) and configure support for NMEA-compliant receivers.
• Defined additional TARGETS in the main Makefile to include programs and libraries required for the feral robot client system (utrobot, robostix, uisp, gpsd and libgps), as well as some extra troubleshooting tools (e.g. tcpdump, etc).
• Changed the default configuration to enable the CompactFlash slot (PCMCIA) at boot time, as well as start the wi-fi interface (wlan0 in /etc/network/interfaces) assuming it is a model supported out-of-the-box.
• Created scripts, to be installed in /etc/init.d/, to run programs required by the feral robot client:
  • s99local: designed to start the GPS daemon (gpsd) and the feral robot client (utrobot) at gumstix boot time.
  • gps: establishes a bluetooth serial connection with specified GPS receiver and launches gpsd.
  • utrobot: sets up the environment to run the feral robot client application with the correct parameters (UT server, MAC address for robot id, robostix ADC serial port, status and data log file locations).
  • ntp: updates the system time from an NTP server. This script is actually triggered when a network interface is brought up (defined in /etc/network/interfaces) to ensure that it is possible to contact the remote NTP server.
• Replaced the Unix "message of the day" (in``/etc/motd``) to display instructions on how to further customize/configure the feral robot gumstix system:

Welcome to Gumstix, implementing the Urban Tapestries FERAL ROBOT!
==========================================================================

Do not forget to change the root password with the 'passwd' command.

Change the hostname in /etc/hostname and update /etc/hosts accordingly.

Set up the ESSID in /etc/pcmcia/wireless.opts to match the wifi network.
If there is no DHCP server, set IP for 'wlan0' in /etc/network/interfaces.

Update NTPSERVER in /etc/init.d/ntp to address of the local time server.

Adjust the /etc/init.d/gps script to set-up the connection to the GPS 
receiver (set receiver's bluetooth MAC address in the variable GPS_BTADDR).

In /etc/init.d/utrobot, set UT_SERVER to the Feral Robot server address
and NET_IF to the interface name to be used as the robot id (MAC address).
Rename the file s99local in /etc/init.d/ to S99local (notice capital 'S').

[This information is stored in /etc/motd, which can be deleted afterwards.]

The current feral robot buildroot configuration produces a root filesystem image of roughly 5MB. Non-mandatory items in the main Makefile are marked with the comment "OPTIONAL", therefore it should be safe to exclude from the root filesystem to conserve space in the gumstix flash memory.

Flashing a New Software Image

A new software image (root filesystem) can be loaded onto a gumstix computer by accessing its boot-loader via the serial console and using the Kermit file transfer protocol.

The sequence below illustrates the commands necessary to transfer a root filesystem image to U-Boot and then commit it to the gumstix flash memory [5]. It is assumed that the host is connected to the console via port /dev/ttyUSB0 and a terminal emulator is used, such as kermit, with the correct parameters (115200,n,8). The symbol $ represents the host's shell prompt, and > the kermit prompt:

$ kermit -l /dev/ttyUSB0
> set carrier-watch off
> set speed 115200
> set reliable
> connect

The above commands should connect to the gumstix console with the right setup. Once connected to the console, the user can interrupt U-Boot by pressing a key during a (default) 2-second delay, before the Linux boot process is started (reset power to gumstix if necessary). The U-Boot prompt, GUM>, should appear:

GUM> loadb a2000000

After entering the above command, U-Boot is waiting from the transfer to begin. Type the sequence "CTRL-\ c" to return to to kermit and then the following (replacing /path/to/ with the correct location of root_fs_arm_nofpu):

> robust
> send /path/to/root_fs_arm_nofpu

This will start the transfer; after it is completed with success, reconnect to U-Boot and enter the commands below to erase everything except U-Boot itself (protected), copy the transferred software image to flash and boot the with the new root filesystem:

> connect
GUM> protect on 1:0-1
GUM> jerase all
GUM> cp.b a2000000 40000 ${filesize}
GUM> boot

Compiling ADC Protocol

Basically, the communication protocol on the robostix side consists of waiting for incoming ASCII characters on UART0, that represent ADC channel numbers (from '0' to '7'), and responding with the current voltage value on that ADC channel, in hexadecimal format encoded as an ASCII string (e.g. "0x03f9"). On the robostix's ATmega128 this function is implemented with an endless loop in a C program, named Read-ADC.

This program and other software for robostix can be downloaded from the gumstix repository [6] as was shown in Feral Robot Buildroot Branch (robostix/ sub-directory of feral-robot/ in the example procedure). To compile Read-ADC for the robostix an appropriate cross-compiler, such as avr-gcc, must be installed on the host computer:

cd feral-robot/robostix/Read-ADC
make

Programming Robostix

After compilation, the resulting Read-ADC.hex file must be programmed (i.e. flashed) to robostix's ATmega128. Several possible methods to program microcontrollers of the AVR family do exist, and the ones applicable to robostix, are described at http://gumstix.org/tikiwiki...

However, in this case the most straightforward way of doing this is to take advantage of the gumstix/robostix serial interconnection setup to perform in-system programming (ISP) of the software image, directly from the GNU/Linux system running on the gumstix. First, the .hex image file must be transferred from the host computer to the gumstix by console (Kermit) or network (SSH), and then (on the gumstix) use the uisp command-line tool:

uisp --wr_fuse_l=0xbf --wr_fuse_h=0xc9 --wr_fuse_e=0xff
uisp --erase --upload if=Read-ADC.hex

Integration with Gumstix

The package, hosted at http://socialtapestries.net/feralrobots/software/utrobot-1.0.tar.gz, is automatically downloaded and cross-compiled as part of the feral robot buildroot (by the make/utrobot.mk sub-makefile, see Feral Robot Buildroot Branch).

This application requires TCP/IP access to an active GPS daemon (gpsd), either running locally (default) or over a network connection. Also the serial port of the robostix may have to be specified to access the sensors. Finally, the robot id (MAC address) and remote UT server address must be specified on the command-line -- on the gumstix this is done by a wrapper script.

For reference, below is presented the application's embedded usage instructions:

Usage: utrobot -i hwaddr -u addr[:port] [-g addr[:port]] [-a serial_port] [-ldvh]

  -i hwaddr        Robot id as MAC address (6 bytes in hex)
  -u addr[:port]   UT server (default port: 1979)
  -g addr[:port]   GPSD server (default: 127.0.0.1:2947)
  -a serial_port   Serial port for ADC access (default: /dev/ttyS2)
  -l               Log sensor data to standard output (stdout)
  -v               Print extra information (on stderr)
  -d               Print debugging information (on stderr)
  -V               Show version, then exit
  -h               Show this help message, then exit

More information on Feral Robots at http://socialtapestries.net/feralrobots/

Source Code

The source code for utrobot relies on GNU's autotools for its build system to enhance portability across platforms. The compilation of this package is similar to that of other common open source projects and, besides a standard Unix environment, only requires the gpsd access libraries and header files:

gunzip -C utrobot-1.0.tar.gz | tar xvf -
cd utrobot-1.0
./configure
make

The main modules of C code in the utrobot application are briefly described below (refer to source code for further information):

• adchw.*: implements the communication protocol with the robostix ADC device (explained in Robostix ADC). If testing on a system (e.g. host computer) that does not have a robostix hooked on a serial port, the make step can be changed to "make CFLAGS=-DDUMMY_ADC", which disables interaction with the ADC component and returns a constant (dummy) value instead.
• sensordef.*: defines a data structure that has the following essential function:
  • specify what type of sensors are connected to which ADC channels, whether they are active or not, and whether their data should be sent to the UT server or not;
  • provide pointers to convenient handler functions, one to convert the digitized voltage value returned by the ADC (integer) to an actual physical unit reported by that sensor (float), and another to process the converted value (triggering possible further actions if necessary, e.g. shutdown if battery voltage is below a certain threshold).
• utrobot.*: application entry point that performs command-line parsing, initializes subsystems (open robostix serial port, establish TCP connection with gpsd, open UDP socket for UT server, etc) and then enters the main control loop. The loop is driven by the sensor_defs structure to sample sensors, acquire GPS position, assemble and timestamp packet to send to server.
• logger.*: implements a lightweight data logging infrastructure that allows filtering the granularity of detail of information printed during program execution (error, warning, info, debug, etc).