1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Mon Oct 14 14:36:36 2013 +0000
1.3 @@ -0,0 +1,143 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The ben-pololu-imu distribution provides some programs that run on the Ben
1.8 +NanoNote and control the Pololu MinIMU-9 board which provides a 3-axis
1.9 +gyroscope, a 3-axis accelerometer, and a 3-axis magnetometer. To connect the
1.10 +module to the Ben, the 8:10 port which is typically employed to access microSD
1.11 +cards is instead used to hold a suitable breakout board that exposes the 8:10
1.12 +port's connectors to other circuits. These connectors are in turn connected to
1.13 +specific connectors on the MinIMU-9 as follows:
1.14 +
1.15 +Sniffer UBB MinIMU-9
1.16 +------- ---- --------
1.17 +DAT2 DAT2
1.18 +CD DAT3 SCL
1.19 +CMD CMD SDA
1.20 +VCC VDD VIN
1.21 +CLK CLK (3V)
1.22 +GND GND GND
1.23 +DAT0 DAT0 (1V8)
1.24 +DAT1 DAT1
1.25 +
1.26 +The 3V and 1V8 pins play no role in the communication, but a six pin header
1.27 +exposing these pins on the IMU can be used to connect the IMU with the
1.28 +Sniffer/UBB without any complications.
1.29 +
1.30 +Building the Software
1.31 +---------------------
1.32 +
1.33 +Before building the software, it will probably be necessary to edit the
1.34 +Makefile to specify the locations of the cross-compilation toolchain and of
1.35 +libubb. Obtaining a toolchain and libubb is currently beyond the scope of this
1.36 +document.
1.37 +
1.38 +The programs are built as follows:
1.39 +
1.40 +make
1.41 +
1.42 +Running the Software
1.43 +--------------------
1.44 +
1.45 +On the Ben, the programs can be deployed together with libubb in a particular
1.46 +directory and invoked as described below.
1.47 +
1.48 +As an alternative to deploying libubb and the programs together, the library
1.49 +search path can be configured properly and the programs installed in such a
1.50 +way that merely typing the name of the program is enough to run them.
1.51 +
1.52 +The calibrate program just prints out readings from a particular component on
1.53 +the MinIMU-9 board. For the gyroscope, accelerometer and magnetometer, it can
1.54 +be run with the respective commands as follows:
1.55 +
1.56 +LD_LIBRARY_PATH=. ./calibrate -g
1.57 +LD_LIBRARY_PATH=. ./calibrate -a
1.58 +LD_LIBRARY_PATH=. ./calibrate -m
1.59 +
1.60 +The itest program is a graphical program which should be run when the Ben is
1.61 +showing a console (and not any graphical environment); it is run as follows:
1.62 +
1.63 +LD_LIBRARY_PATH=. ./itest
1.64 +
1.65 +(It supports an argument -f which enables the high-pass filter on the
1.66 +accelerometer, but this is generally useless.)
1.67 +
1.68 +The imu program can be run as a textual or graphical program as follows:
1.69 +
1.70 +LD_LIBRARY_PATH=. ./imu
1.71 +
1.72 +The imu program accepts the following options:
1.73 +
1.74 +-g Run in graphical mode. This should be done when the Ben is showing a
1.75 + console and when other graphical programs are not using the
1.76 + framebuffer. If omitted, the program will run in text mode.
1.77 +
1.78 +-c Calibrate before attempting to interpret readings from the gyroscope
1.79 + and accelerometer. This is highly recommended because uncalibrated
1.80 + measurements will produce an inaccurate impression of the device's
1.81 + rotation and motion.
1.82 +
1.83 +Hardware: Pololu MinIMU-9
1.84 +-------------------------
1.85 +
1.86 +This board provides the L3G4200D 3-axis gyroscope and LSM303DLM 3-axis
1.87 +accelerometer/magnetometer components from STMicroelectronics and is described
1.88 +at the following location:
1.89 +
1.90 +http://www.pololu.com/catalog/product/1265
1.91 +
1.92 +Note that a different version of the board used the LSM303DLH component and is
1.93 +described here:
1.94 +
1.95 +http://www.pololu.com/catalog/product/1264
1.96 +
1.97 +There are subtle differences between the LSM303DLM and LSM303DLH components,
1.98 +and it is important to know which one is being used. Both of these boards have
1.99 +now been superseded by the following MinIMU-9 v2 board which uses other
1.100 +components:
1.101 +
1.102 +http://www.pololu.com/catalog/product/1268
1.103 +
1.104 +No support for the MinIMU-9 v2 board or the LSM303DLH variant of the MinIMU-9
1.105 +is present in the software, currently, but other projects do provide support
1.106 +for these other boards and can be studied to see what the differences are
1.107 +between the different components involved.
1.108 +
1.109 +Hardware: 8:10 Port Breakout Board
1.110 +----------------------------------
1.111 +
1.112 +To connect the Ben NanoNote to the IMU board, a suitable breakout board is
1.113 +required to expose the connections inside the 8:10 slot. To achieve this, the
1.114 +Sparkfun microSD Sniffer has been used:
1.115 +
1.116 +https://www.sparkfun.com/products/9419
1.117 +
1.118 +This board is apparently intended for eavesdropping on communications between
1.119 +a "host" device with a microSD slot and a microSD-based device that can be
1.120 +inserted into a slot mounted on the board (instead of being inserted directly
1.121 +into the host device). However, the board-mounted slot can be ignored and the
1.122 +exposed connections routed to the display board instead.
1.123 +
1.124 +Another board that achieves the same purpose is the Universal Breakout Board
1.125 +(UBB):
1.126 +
1.127 +http://en.qi-hardware.com/wiki/UBB
1.128 +
1.129 +The UBB is somewhat more difficult to work with as its connectors are very
1.130 +small and, compared to the microSD Sniffer, awkward to attach things to. The
1.131 +microSD Sniffer employs connectors situated around holes with 0.1 inch
1.132 +spacing, meaning that commonly available connection headers can be soldered
1.133 +onto the board.
1.134 +
1.135 +Although the labelling of the connections is different between the microSD
1.136 +Sniffer and UBB (see above), the layout appears to be identical.
1.137 +
1.138 +Contact, Copyright and Licence Information
1.139 +------------------------------------------
1.140 +
1.141 +The author can be contacted at the following e-mail address:
1.142 +
1.143 +paul@boddie.org.uk
1.144 +
1.145 +Copyright and licence information can be found in the docs directory - see
1.146 +docs/COPYING.txt and docs/gpl-3.0.txt for more information.
