Overo Extension

From GCtronic wiki
Jump to navigation Jump to search

This is a mini how-to of the e-puck extension board for the Gumstix Overo COM.

Minimal getting started

  1. upload the standard firmware to the e-puck robot and put selector in position 10
  2. connect the USB cable: mini-USB to the extension module and the other side to the PC
  3. execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
  4. switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
  5. login with user=root, password=root

Anyway you're encouraged to read all the documentation since you'll find more detailed explanations.

Introduction


This introductory section explains the minimal procedures needed to work with the Gumstix Overo computer-on-module (COM) mounted on the e-puck extension board and gives a general overview of the available demos and scripts shipped with the micro sd. You can also refer to extension-instructions that is a document containing the most important information in order to start working with the extension. The extension is mostly an interface between the e-puck robot and the Gumstix Overo COM.

Gumstix Overo COM: product information and programming information,

Full package

The full package content is:

  • e-puck extension with Gumstix Overo COM and micro sd card already inserted
  • USB adapter for the micro sd
  • A to mini-B USB cable
  • USB wifi dongle
  • external power adapter
  • USB host adapter

The standard COM mounted on the e-puck extension is the Gumstix Overo EarthSTORM COM. Some extensions were delivered with the Gumstix Overo SandSTORM COM, don't worry, the main difference between the two COMs is that the SandSTORM has no flash memory, but the flash isn't necessary since the system is booted from the micro sd.

Requirements

In order to connect to the extension through the mini USB the FTDI driver need to be installed. If a serial port is automatically created when connecting the robot to the computer you're done otherwise visit the following site and download the drivers for your architecture (32 or 64 bits) FTDI drivers.

General procedure

The e-puck extension board for the Gumstix Overo COM comes with a pre-configured system ready to run without any additional configuration. The whole system is installed on a micro sd and is composed of:

It's important to note that the flash isn't reprogrammed, so it will contain the factory system.

In order to access the system from a PC (console mode), the following steps must be performed:

  1. connect the USB cable: mini-USB to the extension module and the other side to the PC
  2. execute a terminal program (e.g. minicom) and configure the connection with 115200-8N1. The serial device path should be typically something like "/dev/ttyUSB0". Make sure that the flow control parameter of minicom called "Hardware" is set to "No".
  3. switch on the robot; now the terminal should display the Gumstix Overo booting information (booting time 25-30 seconds)
  4. login with user=root, password=root

Wireless setup

Before proceding with the following configurations be sure that the WiFi dongle is well recognized, refer to section WiFi_dongle.

Wireless configuration using a script

The script setupWifi placed under /home/root/scripts is used to configure easily the wireless network (managed mode) and need to be adapted to your specific situation. The script is shown below:

#!/bin/bash
ifconfig wlan0 up
iwconfig wlan0 essid SSID key HEX_KEY
iwconfig wlan0 ap MAC_ADDRESS
iwconfig wlan0 rate 54M
ifconfig wlan0 LOCAL_IP netmask SUBNET_MASK
route add default gw GATEWAY_IP

To know the available wifi networks and related information such as mac address of the access point, you can issue the command iwlist scanning wlan0.

On some platforms, udev may rename the network interface wlan0. In this event, the 'setupWifi' script will return several errors, some of which will say "No Such Device." To identify your network interfaces, use the commands ifconfig or iwconfig. These will provide a listing of your devices, and their current states. Identify the appropriate interface (typically wlan# where "#" is a number) and replace wlan0 in the above script with this.

If you're using dhcp, you can instead adapt the script setupWifiDhcp found under /home/root/scripts:

#!/bin/bash
ifconfig wlan0 up
iwconfig wlan0 essid SSID key HEX_KEY
iwconfig wlan0 ap MAC_ADDRESS
iwconfig wlan0 rate 54M
dhclient wlan0

The parameters that must be customized are shown in capitals; after that you can execute the script typing ./setupWifi (or ./setupWifiDhcp) and after a while a message should be displayed indicating that the wireless is ready. You can test the network configuration using ping.

It may be necessary to create a directory if you get the error "can't create /var/lib/dhcp/dhclient.leases: No such file or directory." Use the mkdir command

mkdir /var/lib/dhcp

Usually, when the Wifi dongle is connected to the AP, a message is written in the message buffer of the kernel. The following bash code snippet can be used to make sure that the connection is well established when the program returns:

#!/bin/bash
echo Wait until the Wifi is connected to the AP
while true
do
  #the text "link becomes ready" can vary according the Wifi dongle
  a=$(dmesg | grep wlan0 | grep "link becomes ready")
  if [ -n "$a" ]
  then
    echo Wifi enabled!
    exit
  fi
  sleep 1
done

In order for the setupWifi or setupWifiDhcp scripts to be run during boot, copy the appropriate script into the init.d directory with the other start/stop scripts.

cp -i ~/scripts/setupWifi /etc/init.d/setupWifi

Then determine which run level the system is using with the command:

runlevel

This should return "N #" where # is the run level number. Create a link to your script in the init.d directory within the directory /etc/rc#.d Name the link S##setupWifi. The number ## (customarily 2 digits, which you choose) determines where in the startup sequence your script will be run. It is good advice to choose a number just smaller than the largest in the rc#.d directory, this way the script is not called before lower-level ones. The creation of this link can be done with the following command (where # and ## must be changed to their appropriate values).

ln -i -s /etc/init.d/setupWifi /etc/rc#.d/S##setupWifi

Wireless configuration using a wpa_supplicant

Alternativerly, the Wifi connection can be set up by using both wpa_supplicant and the native wifi setup. This has the advantage to be more robust against failure. In order to do that, the Wifi interface can be added to /etc/network/interfaces, this way:

auto wlan0
iface wlan0 inet static
	address 192.168.1.2
	netmask 255.255.255.0
	wpa-conf /path/to/wifi.conf #this should be replaced by the absolute location of wifi.conf

And the related wifi.conf

ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=0
ap_scan=1
network={
  ssid="myssid" #this should be replaced by your ssid
  scan_ssid=1
  key_mgmt=NONE
  wep_key0=1234567890 #this should be replaced by your WEP key
  wep_tx_keyidx=0
}

In this example, static IPs and WEP encryption have been used. DHCP and other encryption can be obviously used by following the documentation both of the linux native network setup and of wpa_supplicant.

Network performance

To test the network performance you could use the iperf tool installed on the system. In the server side you must issue the following command (either for TCP or UDP testing), after which the server machine is listening for incoming data:

iperf -s      [TCP]
iperf -s -u   [UDP]

In the client side you must type:

iperf -c SERVER-IP                   [TCP]
iperf -c SERBER-IP -u -b 50000000    [UDP]

Where SERVER-IP must be changed accordingly to the network configuration.

Package manager

If you have an internet connection up and running you can update and install easily new packages with opkg. Some of the useful operations you could do are:

  • update repositories: opkg update
  • update installed packages and kernel; pay attention that the camera driver is based on the provided kernel and upgrading it will prevent the use of the camera: opkg upgrade
  • list of software currently installed on the machine: opkg list_installed
  • install a new package (perl in the example): opkg install perl
  • remove a pacakge (perl in the example): opkg remove perl
  • list of all packages available to be installed: opkg list

opkg update failed

If you get errors on reaching the default repo sources you can try changing them by following these steps:

  1. make a copy of the current repo: mv /etc/opkg/base-feed.conf /dest-dir
  2. add the new repo: echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base' > /etc/opkg/base-feed.conf
  3. opkg update

The procedure shows how to change the base repo, the same need to be done for all others repos.

USB ports

The e-puck extension board for the Gumstix Overo COM comes with two USB interfaces called USB host and USB otg. If you try inserting devices that require more energy than the one permitted on the otg, the device will not be enabled automatically. In these cases you can use the three scripts usbup, usbdown and usbenable to respectively power up, power down and enable the USB device; they're placed under /home/root/scripts. These scripts are intended for primary use with the USB otg port, even if they're suitable for both ports (otg and host).

  • ./usbup otg (or ./usbup host): power on the usb device
  • ./usbdown otg (or ./usbdown host): power off the usb device
  • ./usbenable otg (or ./usbenable host): activate the usb device (now is in the usb device list)

Demos

A specific firmware must be charged on the e-puck to run the Gumstix Overo linked demos, refer to section E-puck firmware.

Serial test on the Gumstix Overo COM

This small program read and write from a serial port (non-canonical mode). For more information on the usage refers to sertest (sertest sources). It's placed under /home/root/demos/gumstix-common, and it's called sertest.

Advanced sercom

Once the new firmware is running on the e-puck, the selector must be set in position 10 to run the advanced sercom for the Gumstix Overo.
Now you can type (after being in /home/root/demos/gumstix-common) ./sertest -p /dev/ttyS0 -b 230400 (or simply ./ser+ENTER) to enter the e-puck menu in console mode; for a list of all available commands type h+ENTER. After stopping the sertest program (CTRL+C), the display may not respond correctly; to reset the display run the script r by simply typing ./r+ENTER. Now the display should behave normally.
For more information about the advanced sercom refer to the page Advanced sercom protocol.

Images grabbing (camera driver)

A small application called v4l2grab (v4l2grab.zip) based on http://github.com/twam/v4l2grab was used for grabbing JPEGs from V4L2 devices. In order to get an image from the e-puck camera you need to run the program typing (after being in /home/root/demos/gumstix-common/) ./v4l2grab -o image.jpg. The application communicates also with the robot through the serial line to know the camera orientation and rotates the image automatically in case the camera is rotated (refer to section e-puck camera for more information on camera orientation). For more information on the options available refer to the help by typing./v4l2grab -h.

Images transfer (camera driver)

This demo is divided in two parts: one running on the e-puck extension board for the Gumstix Overo COM that continuously request images to the e-puck camera and transfers them over UDP, and the other running on a PC that acts as a server and is listening for the images visualizing them as soon as they are available. A network link must be established between the two in order to run this demo; for more information on how to configure the network refer to the section Wireless setup.

First of all you need to start the server (Receiver QT project). The application is a Qt project, so the compilation may be handled easily with Qt Creator; alternatively qmake can be used. The usage is very simple: the server listening port and the protocol (only UDP available at the moment) must be selected first, then click on the button Connect; at this moment the application is waiting images.
On the e-puck extension board side, you need to run the program typing (after being in /home/root/demos) ./v4l2grab-send -o image.jpg -i SERVER_IP -p SERVER_PORT -f 0 -t 0. SERVER_IP is the address of the PC and SERVER_PORT should be the same as configured when the receiver was started. The f option indicates the format (in this case RGB) and t indicates the transfer mode (0=UDP, 1=TCP). For more information on the options available refer to ./v4l2grab-send -h.
The sources for the sender, that is an extension of the v4l2grab application, could be found in the following link v4l2grab-send.zip; in order to compile the application the Makefile must be modified specifying the path to the cross-compiler (for more information on cross-compilation for the OMAP3530 processor refers to http://focus.ti.com/docs/prod/folders/print/omap3503.html).

Music player

This isn't really a demo, it's only one of the possible way on how to listen something from the extension module. The system comes with a tool called mplayer that supports many multimedia formats. You can use it to play for example an mp3 file in this way:

mplayer file.mp3

You can then adjust the volume with either the alsamixer graphical tool (adjusting DAC2 control) or using the command line tool amixer; the following command can be used for instance to set the volume to 80%:

amixer set 'DAC2 Analog' 80%

File transfer

ssh

The e-puck extension board for the Gumstix Overo COM supports ssh connections through dropbear (small SSH 2 server and client) that is installed on the system.
To exchange file between the module and the PC, the scp tool (secure copy) will be used; the general command is the following:

scp user@ip:path-to-file file-name

As an example of transfer a file from the PC to the extension, let the PC user be stefano and its IP be 192.168.1.10, then the command will be:

scp stefano@192.168.1.10:/home/stefano/file-to-send prova

The file file-to-send will be renamed in prova and placed in the current directory.

If you are working in Windows you can use WinSCP to exchange data between the robot and the computer.

zmodem

The following instructions to exchange data between the extension and the computer refer to minicom as the terminal.
If you want to receive a file, that is transfer a file from the PC to the e-puck extension board for the Gumstix Overo COM, you need to follow these steps:

  1. open a terminal window with minicom; now you access the linux system in console mode
  2. type lrz
  3. press CTRL+A and then S
  4. select zmodem and navigate to find the file you want to tranfer
  5. select the file with the SPACEBAR and then press ENTER to start the transfer
  6. when transfer is complete press ENTER once more to come back to the command line

For more information type lrz -h.

If you want to send a file, that is transfer a file from the e-puck extension board to the PC, you need to follow these steps:

  1. open a terminal window with minicom; now you access the linux system in console mode
  2. type lsz file-name, where file-name is the file you want to transfer
  3. when transfer is complete press ENTER to return to the command line

The file will be placed in the directory where minicom is started. For more information type lsz -h.

Extension LEDs

The e-puck extension board for the Gumstix Overo COM comprises 8 new small leds that can be turned on/off easily from the file system in this way:

echo 1 > /sys/class/gpio/gpio7x/value   [turn on]
echo 0 > /sys/class/gpio/gpio7x/value   [turn off]

where x ranges from 0 to 7. For more information on gpio refer to the section GPIO - pins mode.

File system image

You can download the entire system running on the micro sd released with the e-puck extension board from the following links: file system and FAT (with camera driver 1.3).
In order to prepare the micro sd you can use a script (prepareMicroSD.sh), in which you need only to specify where to find the two previously downloaded files and run it (./prepareMicroSD.sh /path/to/dev) to have your micro sd ready to be used. Alternatively you can have a look the gumstix documentation on how to create a bootable microsd card.
If you experience problems in booting from mmc enter u-boot and issue the following command:

nand erase 240000 20000
reset

Moreover if you need you can find pre-built images for the Gumstix Overo in the following link: http://gumstix.org/download-prebuilt-images.html.

Sources

The complete kernel sources (comprising the camera driver) can be downloaded from the following link gctronic-ti-psp-omap-2.6.32-12.08.14.zip if you want to try to build it your own (anyway you don't need to do it because the released micro SD is ready to run with this system). The system is based on:

Camera driver

The driver of the camera is open-source, you can download the code in the section kernel source. The driver is located in /ti-psp-omap/drivers/media/video/po6030cam.c; related ISP code is located in /ti-psp-omap/drivers/media/video/isp.

Release notes

1.0
  • support for PO6030 camera (front e-puck camera or camera of omnicam module version 1)
  • support for RGB565 output format
  • only 640x480 resolution images
1.1
  • added support for PO3030 camera
  • added support for YUV422 output format
  • brightness, contrast, saturation, auto-white balance, red gain, blue gain controls available
1.2
  • exposure control available
  • support for 480x480 color and greyscale images
1.3
  • added support for PO8030 camera

System update

In order to update the system released in the micro sd with the new driver you need to download the kernel modules from linux-2.6.32.tar.gz and the kernel image from uImage. Then:

  1. insert the micro sd in the computer; two partitions will be recognized
  2. copy the kernel image (uImage) in the FAT partition
  3. extract the kernel modules in the second partition:
    1. cd path/to/partition
    2. sudo tar zxvf path/to/kernel-modules
  4. unmount the micro sd from the computer and insert it in the extension; at first boot type depmod -a and reboot

Daemon

It can be useful to start a daemon at the end of the boot process in order to run your own program at the start up of the e-puck (when the console mode won't be accessible). This can be done by placing your program executable into /etc/init.d and then:

cp /path/to/your/executable /usr/sbin/mainProgram
cd /etc/init.d
update-rc.d mainProgram defaults 99

The daemon can be removed by removing these files:

rm /etc/rc*/*mainProgram*

Remember to give execution permission to the program by typing chmod +x mainProgram.

Hardware

The following figure shows the main components offered by the e-puck extension for the Gumstix Overo COM and their interconnection with the e-puck robot and the Gumstix Overo COM.

In particular there are:

  • a Gumstix Overo COMs: compatible with all Gumstix Overo COM models. The communication between the Gumstix Overo COM (OMAP 35xx) and the e-puck (dsPIC) is handled with a serial line at 230400 baud
  • a mini-usb connector (console) used to enter the linux system through a terminal
  • one usb otg and one usb host: these two connectors are really useful to connect whatever peripheral you need, like a WiFi dongle or simply a pen drive to extend the memory
  • a speaker (speaker specification): with Linux running on the Gumstix Overo COM, it's really easy play any audio format you need or implement a speech synthesizer. If the user prefer to have the speaker on the extension linked to the e-puck processor, it can simply be done changing two small resistors
  • 8 LEDs: have you ever seen a board without leds?! Anyway they are completely controllable through GPIO lines (gpio70-gpio77), for detailed information refer to section GPIO - pins mode
  • an I2C connector (@5 V)
  • a rotary selector: one could choose what program is running on the e-puck based on the selector position
  • 2 long range infrared proximity sensors (long range specification)
  • the PixelPlus PO6030 camera remains mounted on the robot, but you could receive image from it by using the OMAP ISP (Camera Interface Subsystem); this way we can receive up to 18 frames per second (VGA color images)

The following figure illustrates where the components are physically placed on the e-puck extension board for the Gumstix Overo COM.

Electrical schema

The circuit diagram of the e-puck extension for Gumstix Overo COM is available to the community on the following link electrical schema.

Long range proximity sensors

The following chart illustrates the long range proximity sensors response towards a white surface. These results should be considered indicative.

A zoom in the bigger distances shows that the values returned from the sensors are still usable to react to obstacles.

WiFi dongle

Zyxel

The WiFi dongle shipped with the extension board for the Gumstix Overo COM is a ZyXEL NWD271N USB adapter, 802.11n compatible. It's based on an Atheros chipset, for more infromation about the linux driver visit the following site http://linuxwireless.org/en/users/Drivers/ar9170.
The measured throughput with the e-puck extension and provided wifi dongle is 20 Mb/s.
The consumption of the wifi dongle is 100 mA in standby and 300 mA when active.

Edimax

A new WiFi dongle is shipped starting from January 2012, it is the Edimax EW-7811Un, based on a Realtek chipset (RTL8192cu). The device isn't recognized automatically at boot, so you need to follow these steps in order to enable and use it:

  1. turn on the robot and login with user=root, password=root
  2. only needed if the wifi dongle is connected to the USB OTG: type ./scripts/gumstix-common/usbenable otg. Don't worry about the warning usb 1-1: new config #1 exceeds power limit by 400mA
  3. type insmod 8192cu.ko (the kernel module is located in /home/root); the wifi dongle should be recognized and a wlanX device created
  4. type ifconfig wlanX up (where X is a number) to turn on the device; now the wifi can be configured and used normally

The following figures show how the device is mounted on the extension: on the left the WiFi dongle is connected to the USB HOST connector (pay attention to the position on the connector), on the right the WiFi dongle is connected to the USB OTG (this is needed when using an omnivsion extension):

Consumption

The consumption of the robot and extension is 300 mA; with the Zyxel wifi dongle inserted (standby) the consumption goes up to 400 mA; when the wifi dongle becomes active, the consumption reaches 700 mA. If the wifi isn't used it can be turned off completely using the usb scripts http://www.gctronic.com/doc/index.php/Overo_Extension#USB_ports.

Two different tests were performed to provide an estimation of the duration of the battery:

  1. e-puck and gumstix active (gumstix sends commands via serial to robot; movement every 3s lasting 1s at 30% of maximum speed): 3h and 30 minutes
  2. e-puck, gumstix and wifi active (same as above, moreover wifi active all the time with continuous ping): 1h and 25 minutes

External power

In the package you'll find also an external power adapter that will be useful during development of your applications. As power supply you could use the one of the e-puck battery charger. The following figure shows the power supply cable, the external power cable and the extension.

You need to simply attach the power supply in one side, and the other side of the external power cable on top of the extension (near the USB plug). Once the cable is connected a green led should turn on indicating that the extension is running.

The external power cable could also be plugged in when the extension is mounted on the e-puck, but pay attention to not turn on the robot when the external cable supplies the energy, otherwise there could be serious damages of the devices and the battery.

3.3V and 5V source

The 3.3 V comes from the e-puck robot and the 5V comes from the gumstix extension. The gumstix extension can be used alone (without the robot attached to it) but some things are related to the 3.3 V thus without the robot connected they will not work; an example are the RGB leds of the omnivion module, that need the robot to be connected to the extension in order to be used.

Software

E-puck firmware

Refers to the section E-Puck Standard firmware for the firmware that need to be uploaded to the robot. Essentially in this firmware a new version of the advanced sercom is included (selector position 10) in which the bluetooth communication is replaced by the serial line communication, running at 230400 between robot and gumstix. Moreover the I2C is disabled temporary from the dsPIC side (the dsPIC cannot communicate through I2C) in order to avoid conflicts. As a last note, the body led and front led aren't anymore usable with the extension due to the two extra long range proximity sensors and for power saving purposes the motors are configured to the minimum energy consumption during movement.
The values of the two extra proximity sensors can be retrieved with the command N in the advanced sercom (selector position 10); the last two values returned by the command refer to these proximity sensors (the others values refer to the proximity sensors mounted on the e-puck as usual).

Project building

Refer to section Project building for information on how to build the project for the e-puck firmware.

Cross compilation

If you want to develop some applications that will run on the gumstix you need to firstly download the toolchain.

If you're using Ubuntu you can simply type sudo apt-get install gcc-arm-linux-gnueabi g++-arm-linux-gnueabi to install the required toolchain (have a look at http://www.gumstix.org/basic-cross-compilation.html and http://wiki.gumstix.org/index.php?title=Toolchain for more information).

Alternatively when you need to handle external dependencies is better using the toolchain integrated in OpenEmbedded (${OVEROTOP}/tmp/cross or ${OVEROTOP}/tmp/sysroots/i686-linux/usr/armv7a/bin/ with recent version) if you have it in your system. For more information refers to the gumstix wiki.

For other linux systems you can find a toolchain in the following link http://www.mentor.com/embedded-software/sourcery-tools/sourcery-codebench/editions/lite-edition/ (30 days trial); this toolchain is useful for small programs:

  1. download the Lite Edition, you'll have a file named something like arm-2009q3-67-arm-none-linux-gnueabi.bin
  2. open a terminal, go to the directory of the file, type chmod +x arm-2009q3-67-arm-none-linux-gnueabi.bin, after execute the file ./arm-2009q3-67-arm-none-linux-gnueabi.bin to start the installation
  3. follow the installation steps; you have to choose where to install the toolchain, this is the path you will specify in the makefile

Once a toolchain is installed in the system the process will be simply something like this:

  1. develop your application as you do normally in your developing machine
  2. cross-compile in your developing machine using the tools previously downloaded
  3. copy the executable in the extension's micro SD and run it

You can download the hello world example containing a makefile in which you have to specify the path to the toolchain you previously installed in order to build the program; you can use it for others programs.
Refer to section http://www.gctronic.com/doc/index.php/Overo_Extension#Demos for some application examples.

Of course you can also install the compiler directly on the embedded system and build the applications from it, but the process will take longer due to limited computational power compared to a developing machine.

External dependencies

Some applications may require external libraries not contained within the standard toolchain package. For instance if your application depends on libjpeg then you need to tell the cross-compiler where to look to find this library (compiled for the target machine) otherwise your application will not be compiled. If you have OpenEmbedded installed in your system you could simply bitbake the external dependencies (in our example bitbake jpeg) and then compile your application. Instead if you rely on the CodeSourcery toolchain you need to follow these steps:

  1. download the sources of the library
  2. cross-compile the library
  3. install the library (and include files) in the right places
  4. compile your application

Ground sensor

It's possible to use contemporaneously both the e-puck extension for gumstix overo and the ground sensor; in this case the camera and the ground sensor will share the same I2C bus and like the camera, also the ground sensor will not be anymore reachable from the e-puck side, but only from the overo side.
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo, thus we need to change the bus speed to 100 KHz in order to communicate with the ground sensor module; the simplest way is to set a kernel parameter in u-boot:

  1. enter u-boot by pressing any key at boot start
  2. type the command setenv i2cspeed 3,100; this init the I2C bus 3 to 100 KHz
  3. type the command setenv mmcargs setenv bootargs console=${console} i2c_bus=${i2cspeed} ${optargs} mpurate=${mpurate} vram=${vram} omapfb.mode=dvi:${dvimode} omapdss.def_disp=${defaultdisplay} root=${mmcroot} rootfstype=${mmcrootfstype} ; basically we pass an additional parameter to the kernel that is the i2c_bus=${i2cspeed}
  4. type the command saveenv to save the environment changes
  5. type boot to start booting

Pay attention that all the peripherals connected to the bus will now work at 100 KHz, thus also the e-puck camera and the LSM330 (accelerometer + gyroscope) present with e-puck HwRev 1.3.
If you want to set back the bus speed to 400 KHz you need to follow steps 2-4, by setting the i2cspeed u-boot environment variable with setenv i2cspeed 3,400.
Communicating with the ground sensor is as easy as open a device and reading from it; a source code example can be found in the following link http://projects.gctronic.com/Gumstix/groundsensor.c. You will find this application example in the /home/root/demos/gumstix-common directory; start it by executing ./i2c_groundsensors and the sensors values will be displayed in the terminal.
Make sure that you have installed the last system update otherwise you'll encounter some problems.
You can find more information about the I2C and gumstix in the following links:

OpenCV

The Open Computer Vision Library has more than 500 algorithms, documentation and sample code for real time computer vision; you can download it from http://sourceforge.net/projects/opencvlibrary/, and find information about it from the official wiki http://docs.opencv.org/index.html.
The released system comes with OpenCV version 2.0.0 pre-installed and a demo that shows an example of what can be performed with this library. The demo let the robot follow a black filled circle placed in front of it; if the circle is moved right or left the robot turns consequently. The following figure shows an example of the circle detected by the robot:

In order to start the demo follows these steps:

  1. turn on the robot with the gumstix extension and login as root with password root
  2. go to the directory /home/root/demos/gumstix-common and execute ./v4l2grab-opencv -o image.jpg
  3. the demo should return the number of circles detected and save a resulting image showing the circles detected if any

Alternatively you can use the following script, that launches the demo and send it through serial (using zmodem) iteratively:

#!/bin/bash
while true; do
./v4l2grab-opencv -o image.jpg -q 50
lsz img1.jpg
done

The source code can be downloaded from the following link v4l2grab-opencv.zip.


Accelerometer and gyroscope (e-puck HWRev 1.3)

When the e-puck extension for gumstix overo is mounted on the e-puck hardware revision 1.3 the same I2C bus is shared by all the devices (camera, accelerometer, gyroscope) and the overo; since there is only one master (the overo) these devices will not be anymore reachable from the e-puck side.
The I2C bus is configured to work at 400 KHz in the system running on the gumstix overo and this is fine to work with the accelerometer and gyroscope.
Communicating with the accelerometer and gyroscope is as easy as open a device and reading from it; a source code example can be found in the following link i2c_lsm330.c. You will find this application example in the /home/root/demos/gumstix-common directory; start it by executing ./i2c_lsm330, type 0 to get the accelerometer values or 1 to get the gyroscope values printed on the terminal.
The values of the accelerometer and gyroscope read from the gumstix through the I2C are 16 bits (1g = 16384); beware that regarding the accelerometer values there is a mismatch between the values read from the gumstix through I2C and the values read from the advanced sercom protocol through Bluetooth, the latter are converted in the firmware to maintain compatibility with older e-puck hardware revisions.
The orientation of the accelerometer for the values read from the gumstix through the I2C is also different from the one used in the e-puck firmware; the orientation is shown below, the x axis points forward, the y axis points left and the z axis points upward:

Python

An example in python is available from the following link i2c_lsm330.py. In order to run the script, some additional dependencies need to be installed in the system, follow these steps:

  1. configure the network in order to have internet access
  2. update the package manager repos:
    1. echo 'src/gz base http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/base/' > /etc/opkg/base-feed.conf
    2. echo 'src/gz python http://feeds.angstrom-distribution.org/feeds/v2012.12/ipk/eglibc/armv7a-vfp-neon/python/' > /etc/opkg/python-feed.conf
  3. add arch armv7a-vfp-neon 45 to the file /etc/opkg/arch.conf
  4. opkg update
  5. opkg -force-overwrite install python-smbus
  6. optionally you can also remove some warnings related to the update by running the following script remove-warnings.sh

Once the system is configured you can start the script by executing python i2c_lsm330.py, type 0 to get the accelerometer values or 1 to get the gyroscope values printed on the terminal.

ROS

We tested ROS on the gumstix extension with the Yocto system. Follow these steps to get ROS running on the e-puck extension:

1. prepare a micro sd following the instructions from http://gumstix.org/create-a-bootable-microsd-card.html
2. download the file system and fat from the following links: yocto-ros-3.5.7-FAT.tar.gz, yocto-ros-3.5.7-rootfs.tar.gz
3. login with user=root and empty password
4. issue the following commands to enable the WiFi dongle:
echo host > /sys/bus/platform/devices/musb-hdrc/mode
echo -n 1 > /sys/bus/usb/devices/2-1/bConfigurationValue
5. follow the instructions from https://github.com/gumstix/yocto-manifest/wiki/ROS-on-Gumstix#the-fun-part to run a demo

Python

In order to install python 2.6 on the e-puck extension for Gumstix follow these steps:

  1. download the package python-gumstix.tar.gz
  2. extract the package: tar -zxvf python-gumstix.tar.gz
  3. remove the micro sd from the robot and connect it to your computer; two partitions will be opened, one called FAT and the other called overo containing the file system (the partitions name could be a little different)
  4. copy the content of the decompressed file to the same position in the overo partition:
    1. sudo cp -R /python-gumstix/usr/lib/* /overo/usr/lib
    2. sudo cp /python-gumstix/usr/bin/* /overo/usr/bin

Alternatively if you have access to internet you can use the package manager:

  1. opkg install python
  2. opkg install python-modules
  3. opkg install python-pyserial

In order to test your python installation you can download the following script printhelp.py; execute it by typing python printhelp.py. This is a minimal example of serial communication in python that let the gumstix communicate with the robot; basically it opens a serial connection with the robot and ask the available commands that you can use to get sensors data and change actuators state.
Another example is available here getprox.py; in this script the values of the proximities are requested to the robot and printed to the console. The data are requested in binary format, for more information about the communication protocol refer to the section advanced sercom.

e-puck2

When the gumstix extension is mounted on the e-puck2 robot, the same I2C bus is shared by all the devices (camera, IMU, distance sensor, others extensions), the main microcontroller and the overo; since there is only one master (the overo), these devices will not be anymore reachable directly from the e-puck2 main microcontroller that will act instead as I2C slave.

Firmware

A special firmware must be uploaded to the e-puck2 robot in order to let the main processor act as I2C slave.
In this firmware the main processor receive commands from the gumstix extension to actuate the motors and leds and give back the sensors values (proximity, microphones, selector, motors steps, tv remote) to the gumstix. When using this firmware the body led and front led aren't usable; the two extra long range proximity sensors mounted on the gumstix extension are also not available with e-puck2.
The selector on the robot must be in position 10.

The pre-compiled firmware can be downloaded from e-puck2_main-processor_gumstix.elf.
If you want to have a look a the source code, you can clone the git repository by issueing the command git clone -b gumstix --recursive https://github.com/e-puck2/e-puck2_main-processor.git.

An example showing how to exchange data between the robot and the gumstix extension is called i2c_e-puck2 and can be found in the directory /home/root/demos/e-puck2/.
Simply run the program by issueing ./i2c_e-puck2; this demo will print the sensors data on the terminal and send some commands to the robot at 2 Hz.
The code is available from i2c_e-puck2.zip.

Protocol

I2C devices

Ground sensor

Refer to section Ground_sensor.

IMU

The pre-compiled firmware can be downloaded from e-puck2_main-processor_gumstix.elf.

Distance sensor

Configuration

Graphic mode

The resolution of the monitor can be modified in the u-boot command line, that can be entered at booting. In the u-boot command line type:

setenv dvimode "1280x720MR-16@60"
saveenv
boot

Now the configuration is saved in the flash; if your monitor doesn't support the current resolution, repeat the procedure with a different configuration (change the resolution numbers).

Note that the DVI Controller (TFP410) mounted on Summit and Tobi supports resolutions from VGA (640x480) to UXGA (1600x1200).

Useful files to look at:

  • linux_source_home/drivers/video/modedb.c: explains what's the mean of the dvimode names
  • linux_source_home/Documentation/fb/viafb.modes: list of available modes usable with the fbset tool

GPIO - pins mode

There are three different ways to read GPIO lines:

1. Kernel space: GPIO lines handled through an API
2. User space:
2.1. standard filesystem commands like cat and echo (static configuration)
2.2 direct physical memory access using devmem2 or with a C application (dynamic configuration)

Afterward will be explained how to handle the GPIO lines on the Gumstix Overo COM in all different methods; information about this topic were found from various sites, but especially from the mailing list. Moreover for a general howto on GPIO refers to the linux documentation "KernelSrc/Documentation/gpio.txt".

Kernel space

User space

Static configuration

Each of the microprocessor IO pins can be configured to work in different ways for different purposes; in case we desire a certain pin to be configured as a gpio line, we must modify the function assigned to that pin (mux configuration) in the U-Boot board configuration file, that for the Gumstix Overo COM is located at "U-BootSrc/board/overo/overo.h".

To know which modes are available for the pins consult the chapter 7-System Control Module (more specifically 7.4.4-Pad Functional Multiplexing and Configuration) in the OMAP35x TRM.

Assume we want to have the possibility to switch on and off a led attached to the line gpio70; in order to accomplish this task, we need to follow these steps:

1. Modify the board configuration file "overo.h" specifying that the pin has to behave as a gpio line:
MUX_VAL(CP(DSS_DATA0),		(IDIS | PTU | DIS | M4)) /*DSS_DATA0 => GPIO70*/\
  • IDIS = input disable, namely output pin
  • PTU = pull type up, but could be also PTD (pull type down) because of the third parameter
  • DIS = disable pull type up/down
  • M4 = mode 4 (gpio)
This give us a GPIO pin that is output and not pulled up or down.
2. Build U-Boot and place the generated u-boot.bin image in the flash (Writing images to onboard nand) or in a micro sd card (Creating a bootable microSD card)
3. After login, we can see all the GPIO pins that have been exported by the kernel to userspace in the /sys/class/gpio/ directory. In order to access the gpio70 line, we should export it first, by typing:
echo "70" > /sys/class/gpio/export
Now the following line is active /sys/class/gpio/gpio70.
4. At this point we must configure the direction of the exported line and set a logical value (1 or 0) to that line, we can do that by typing:
echo "high" > /sys/class/gpio/gpio70/direction
This command set the pin in output and give it a value of 1.
5. Finally we can switch on or off the led, by setting the value of the gpio line:
echo "value" > /sys/class/gpio/gpio70/value
Where value=1 means switch on, and value=0 means switch off.


In order to automate the process of creating a gpio line accessible through "/sys/class/gpio/", we must modify the board configuration file in the kernel source; this file can be found in "KernelSrc/arch/arm/mach-omap2/board-overo.c" (and related definitions in "KernelSrc/arch/arm/plat-omap/include/mach/board-overo.h"). These files must contain instructions to initialize the gpio line that we want to export in user space and set their direction and initial value.
Consider the previous example in which we would like to control a led with the gpio70 pin; for this purpose the following instructions must be added in the board configuration file board.overo.c within the overo_init function:

if ((gpio_request(70, "OVERO_GPIO_DD00") == 0) && (gpio_direction_output(70, 1) == 0)) {
	gpio_export(70, 0);
	gpio_set_value(70, 1); //not really needed, the initial output value is set with gpio_direction_output
} else {
	printk(KERN_ERR "could not obtain gpio for OVERO_GPIO_DD00\n");
}

After this modification we need to build the kernel and copy it to the flash or micro sd card, and after login we will have the /sys/class/gpio/gpio70 line automatically active.
For more information on the previous snippet code refers to "KernelSrc/Documentation/gpio.txt".


Dynamic configuration

If you aren't familiar with modifying and building U-Boot and kernel, you would probably choose to modify the pin configuration at runtime, without the need to touch any board configuration file. The only way to change the configuration of the pins is to access directly the physical memory of the microprocessor, in particular its configuration registers.
The utility devmem2 allows for easy reading and writing of the memory; after building and installing this utility on the Gumstix Overo COM, you are ready to change the ports functionality. Consider the previous example of the led on gpio70, to change the pin mode to gpio you must issue the following command:

devmem2 0x480020DC b 0x14

0x480020DC is the address of the register we want to write to and can be found observing the table 7-4 on chapter 7.4.4.3 of the OMAP35x TRM; b means we want to write a byte to that register and finally 0x14 is the value we want to write. The pin mode depends on the last three bits, in this case the mode is set to 4, namely the pin is a gpio. From now on we can follow steps from 3 to 5 of the previous chapter to switch on and off the led.

An example on modifying the pins configuration through the C programming language can be found in the following link gpregs.c.

Useful links/resources

For more information on GPIO usage, have a look at the following links:


Webots interface

Nikola Velickovic developed an interface with the Webots simulator during his MSc Thesis in 2012. His report is available here. His files are available here.

FAQ

1. Why the serial communication between Gumstix Overo COM and the robot doesn't work?
There could be three possible reasons for the communication problem:

  • selector position incorrect: you need to be sure that the robot selector is in position 10 in order to start the right software on the robot side
  • wrong device: the serial device is identified as /dev/ttyS0 in the linux machine, be sure to use it when you're using for example the sertest demo ("./sertest -p /dev/ttyS0 -b 230400")
  • battery discharged: somebody could be deceived from the fact that the linux console is still usable, but if the orange led on the robot indicating the low battery level is turned on, then the robot will not be able anymore to respond, even if you are working on the linux console; either change or charge your battery and try again.

2. I am able to communicate with the robot through the serial line, but seems that I receive only garbage, why?
Probably the baudrate isn't correct; with the robot selector in position 10 you need to configure the baudrate at 230400 (e.g "./sertest -p /dev/ttyS0 -b 230400").

3. Can I use bluetooth to connect to the robot? Can I use the monitor?
Yes, you can connect to the robot with bluetooth and play with the monitor interface placing the selector in position 3. You'll experience some errors on the values displayed on the monitor due to the additional two long IR sensors that aren't considered when the interface was developed; moreover you will not be able to receive images from the robot.

4. Why I cannot connect to the robot through SSH?

  • first of all be sure that the network is well configured (you can i.e. ping the robot sucessfully)
  • check the SSH daemon is running typing: ps -ef | grep sshd; if it is not running then setup the SSH daemon to run automatically at boot; for this purpose you can type update-rc.d sshd defaults 99. This command will install the links to sshd into rc*.d dirs. See the man page for more informations.
  • if the SSH server is running, but you get an error like "ssh: connect to host 192.168.1.2 port 22: Connection refused" when trying to connect, you can check whether a user and group sshd are created. If not, add the following entries in the system:
 /etc/group:sshd:*:27:
 /etc/passwd:sshd:*:27:27:sshd privsep:/var/empty:/sbin/nologin

5. How to auto-login and execute applications automatically at startup?
Refers to the instructions explained here https://wiki.gumstix.com/index.php/AutoLogin.

6. Are micro SDHC supported?
Yes they are supported.

Videos


Comments: This e-puck is on an exploration, his camera sends continuous image to the computer with a wifi connection.

Useful links

http://www.gumstix.org/
http://wiki.gumstix.org/index.php?title=Main_Page
http://docwiki.gumstix.org/index.php/Gumstix_Buildroot_Support_Wiki
http://docwiki.gumstix.org/index.php?title=U-Boot
http://www.openembedded.org/wiki/Main_Page
http://www.e-puck.org/
http://www.jumpnowtek.com/