CS23 Winter'09 - Team project technical information

Information available from here:

• Using Subversion (SVN) to manage your project
• Team websites
• Starting materials
• Compiling your Garcia Robot Controller on Linux
• Communicating with your robot
• Compiling and installing software to execute on the Garcia robot

• Capturing and displaying images from the camera

Please report any errors that you find!

Using Subversion (SVN) to manage your project

The standard reference book Version Control with Subversion (v1.5) has been available online by its authors, or you may like to download your own copy. The book also provides a High-Speed Tutorial.

When reading the documentation, there is no need to focus on material describing how to initially create a repository, and this has been done for you. Instead, you should just focus on the very common commands that you'll require to get started - checkout, import, update, and commit.

Each repository has a URL from which it can be initially checked out; once that's done, the URL is remembered for future operations. Your team's URL will be named something like:

The following is a suggested list of commands to commence. The lines commencing with the '#' symbol are just comments; other lines are commands you'll enter:

# # Create a new directory for CS23 - you probably already have one # mkdir ~/cs23 # # Change into this directory # cd ~/cs23 # # Make your first 'connection' with your team's SVN repository. # Your exact DND name and password provide the authentication. # Note that you may need single quotes to enter any spaces and periods in your name. # svn checkout https://svn.cs.dartmouth.edu/classes/cs23pink --username 'Full D.N.D. Name' # # The above command will create a new directory for you. Change into this directory. # cd cs23pink # # You may now create and edit your project's files in this directory - # but before you commence your team should design the working layout, e.g. : # mkdir, create, edit, copy, .... # # Once you have your directory layout (partially) created, import it into # your repository. Note the -m switch to provide a log message explaining your actions: # svn import . https://svn.cs.dartmouth.edu/classes/cs23pink -m "initial import" # # If all has gone well, your initial files will be copied to the repository. # (Bravely) you may now delete them, and recover an "official" copy of them from svn: # svn checkout https://svn.cs.dartmouth.edu/classes/cs23pink/trunk . # # Throughout the project, after you've made changes to your files, update your # your copy of the project to ensure that your changes don't conflict with those of others: # svn update # # And finally commit your changes (and any merged changes with others) into the repository: # svn commit -m "removed the final bug"

Team websites

Starting materials

Compiling your Garcia Robot Controller on Linux

Communicating with your robot

Compiling and installing software to execute on the Garcia robot

Instead we compile programs for the robots on Pentium-based machines, informing the compiler and linker that the target device uses a different architecture. This activity, term cross-compiling, may be performed in a few different ways. The simplest is use a completely different compiler and linker, running on the Pentium, which has knowledge of the target architecture and has local copies of the necessary library files.

So, to compile a simple program for execution on the robots, we require a command such as:

# Cross-compile a single C file: # /usr/local/arm/3.3.2/bin/arm-linux-gcc -o helloworld helloworld.c # # OK, what did we just produce? # file helloworld helloworld: ELF 32-bit LSB executable, ARM, version 1, dynamically linked (uses shared libs), for GNU/Linux 2.0.0, not stripped

The compilation and linking of programs that will execute on the robot, on our Linux platform, is rather messy. Not only do our C files need to be cross-compiled (as described above), but we to include many Garcia-specific header files and link against many Garcia-specific libraries, that scattered around a number of directories.

To simplify the process, the Makefile in the directory /net/class/cs23/W09project/garcia should be used (at least as a starting point).

The directory /net/class/cs23/W09project/garcia also contains the cs23garcia.h header file, which declares the constants and functions forming the robot's API for our project. The header file should be included by all of your on-robot programs.

Once we have cross-compiled and linked our ARM-based executable, we need to copy it to the robot. As is typical on embedded Linux platforms, only a single user is supported on the robots, that user being the traditional administrator account, or root account. While we work on our workstations and laptops as "ourselves", we work as root on the robots.

We are able to connect to the robots using the ssh command, just as we do to connect between standard Unix machines, and using the related scp command to copy files.

# Copy our executable to the robot # scp helloworld root@ROBOTS-IP-ADDRESS:/tmp enter root's password for the robot # # Login to the robot # ssh root@ROBOTS-IP-ADDRESS enter root's password for the robot cd /tmp ./helloworld output of helloworld appears exit

Of course typing in these repetitive commands becomes tedious, and so we prefer to develop a Makefile so that we may just type make robot and make push (or similiar) to perform common tasks.

When you commence developing on-board programs that make use of the cs23garcia library, you will need a more complicated command on the robots just to run your programs. It is necessary to inform Linux where it can locate additional libraries, at runtime. We can do this with the following shellscript:

#!/bin/sh if [ ! -r garcia.config ] then cat << EOF > garcia.config # Configuration file for Garcia robot # Define the serial port of the Stargate attached to the Stem portname=tts/1 # Define the serial baud rate baudrate = 38400 EOF fi LD_LIBRARY_PATH="/usr/local/acroname/brainstem/aBinary" $@

Copy this shellscript to /root/runit on your robot, make the shellscript executable, and then execute your program with  ./runit ./yourprogram [arguments]

Capturing and displaying images from the camera

    data[0]  is the  blue intensity of pixel[0][0];
    data[1]  is the green intensity of pixel[0][0];
    data[2]  is the   red intensity of pixel[0][0];
    data[3]  is the  blue intensity of pixel[0][1];
      ....

This 24-bit data format cannot be displayed by our Garcia Robot Controller GUI.
Instead, we'll need to convert the representation to either the GIF format or the Portable Pixel Map format with one of these functions:

#include <stdio.h> #include <stdlib.h> #include <stdbool.h> #include <stdint.h> #include <unistd.h> #include <gd.h> bool raw24bit_to_gif(FILE *outfp, uint8_t *raw, int width, int height) { // ENSURE THAT WE RECEIVED REASONABLE PARAMETERS if(outfp == NULL || raw == NULL || width < 1 || height < 1) return false; // CREATE THE IN-MEMORY IMAGE gdImage *im = gdImageCreateTrueColor(width, height); if(im == NULL) return false; int p = 0; for(int h=0 ; h<height ; h++) for(int w=0 ; w<width ; w++, p+=3) gdImageSetPixel(im, w, h, gdImageColorResolve(im, raw[p+2], raw[p+1], raw[p])); // WRITE THE IMAGE TO DISK AS A GIF FILE gdImageGif(im, outfp); // DEALLOCATE SPACE ALLOCATED HERE gdImageDestroy(im); return true; } bool raw24bit_to_ppm(FILE *outfp, uint8_t *raw, int width, int height) { // ENSURE THAT WE RECEIVED REASONABLE PARAMETERS if(outfp == NULL || raw == NULL || width < 1 || height < 1) return false; fprintf(outfp, "P6\n%d %d\n255\n", width, height); for(int p=0 ; p<width*height*3 ; p+=3) fprintf(outfp, "%c%c%c", raw[p+2], raw[p+1], raw[p]); return true; }