# HG changeset patch # User Paul Boddie # Date 1381761396 0 # Node ID e037b6ad9b714c4bc0b5d9fe0ff25ec7958091da # Parent 631f88781de8960ffd72a1984ca6a4accc47fe81 Added some documentation. diff -r 631f88781de8 -r e037b6ad9b71 README.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.txt Mon Oct 14 14:36:36 2013 +0000 @@ -0,0 +1,143 @@ +Introduction +------------ + +The ben-pololu-imu distribution provides some programs that run on the Ben +NanoNote and control the Pololu MinIMU-9 board which provides a 3-axis +gyroscope, a 3-axis accelerometer, and a 3-axis magnetometer. To connect the +module to the Ben, the 8:10 port which is typically employed to access microSD +cards is instead used to hold a suitable breakout board that exposes the 8:10 +port's connectors to other circuits. These connectors are in turn connected to +specific connectors on the MinIMU-9 as follows: + +Sniffer UBB MinIMU-9 +------- ---- -------- +DAT2 DAT2 +CD DAT3 SCL +CMD CMD SDA +VCC VDD VIN +CLK CLK (3V) +GND GND GND +DAT0 DAT0 (1V8) +DAT1 DAT1 + +The 3V and 1V8 pins play no role in the communication, but a six pin header +exposing these pins on the IMU can be used to connect the IMU with the +Sniffer/UBB without any complications. + +Building the Software +--------------------- + +Before building the software, it will probably be necessary to edit the +Makefile to specify the locations of the cross-compilation toolchain and of +libubb. Obtaining a toolchain and libubb is currently beyond the scope of this +document. + +The programs are built as follows: + +make + +Running the Software +-------------------- + +On the Ben, the programs can be deployed together with libubb in a particular +directory and invoked as described below. + +As an alternative to deploying libubb and the programs together, the library +search path can be configured properly and the programs installed in such a +way that merely typing the name of the program is enough to run them. + +The calibrate program just prints out readings from a particular component on +the MinIMU-9 board. For the gyroscope, accelerometer and magnetometer, it can +be run with the respective commands as follows: + +LD_LIBRARY_PATH=. ./calibrate -g +LD_LIBRARY_PATH=. ./calibrate -a +LD_LIBRARY_PATH=. ./calibrate -m + +The itest program is a graphical program which should be run when the Ben is +showing a console (and not any graphical environment); it is run as follows: + +LD_LIBRARY_PATH=. ./itest + +(It supports an argument -f which enables the high-pass filter on the +accelerometer, but this is generally useless.) + +The imu program can be run as a textual or graphical program as follows: + +LD_LIBRARY_PATH=. ./imu + +The imu program accepts the following options: + +-g Run in graphical mode. This should be done when the Ben is showing a + console and when other graphical programs are not using the + framebuffer. If omitted, the program will run in text mode. + +-c Calibrate before attempting to interpret readings from the gyroscope + and accelerometer. This is highly recommended because uncalibrated + measurements will produce an inaccurate impression of the device's + rotation and motion. + +Hardware: Pololu MinIMU-9 +------------------------- + +This board provides the L3G4200D 3-axis gyroscope and LSM303DLM 3-axis +accelerometer/magnetometer components from STMicroelectronics and is described +at the following location: + +http://www.pololu.com/catalog/product/1265 + +Note that a different version of the board used the LSM303DLH component and is +described here: + +http://www.pololu.com/catalog/product/1264 + +There are subtle differences between the LSM303DLM and LSM303DLH components, +and it is important to know which one is being used. Both of these boards have +now been superseded by the following MinIMU-9 v2 board which uses other +components: + +http://www.pololu.com/catalog/product/1268 + +No support for the MinIMU-9 v2 board or the LSM303DLH variant of the MinIMU-9 +is present in the software, currently, but other projects do provide support +for these other boards and can be studied to see what the differences are +between the different components involved. + +Hardware: 8:10 Port Breakout Board +---------------------------------- + +To connect the Ben NanoNote to the IMU board, a suitable breakout board is +required to expose the connections inside the 8:10 slot. To achieve this, the +Sparkfun microSD Sniffer has been used: + +https://www.sparkfun.com/products/9419 + +This board is apparently intended for eavesdropping on communications between +a "host" device with a microSD slot and a microSD-based device that can be +inserted into a slot mounted on the board (instead of being inserted directly +into the host device). However, the board-mounted slot can be ignored and the +exposed connections routed to the display board instead. + +Another board that achieves the same purpose is the Universal Breakout Board +(UBB): + +http://en.qi-hardware.com/wiki/UBB + +The UBB is somewhat more difficult to work with as its connectors are very +small and, compared to the microSD Sniffer, awkward to attach things to. The +microSD Sniffer employs connectors situated around holes with 0.1 inch +spacing, meaning that commonly available connection headers can be soldered +onto the board. + +Although the labelling of the connections is different between the microSD +Sniffer and UBB (see above), the layout appears to be identical. + +Contact, Copyright and Licence Information +------------------------------------------ + +The author can be contacted at the following e-mail address: + +paul@boddie.org.uk + +Copyright and licence information can be found in the docs directory - see +docs/COPYING.txt and docs/gpl-3.0.txt for more information.