--- /dev/null
+/* Copyright (c) 2015, Ian Sutton <ian@kremlin.cc>
+
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
+
+ /* this is a library for the arduino due that controls the LSM303D accelerometer
+ * & magnometer. it will not work on other arduino models, it uses API calls
+ * exclusive to newer ARM-based arduinos.
+ *
+ * steps to recreate:
+ *
+ * !! be especially careful of the 5V output in on the due's SPI header. it is a high !!
+ * !! current output & will cook anything nearby. refer to this diagram before making !!
+ * !! any connections: http://uglyman.kremlin.cc/quick/due-pinout-web.png !!
+ *
+ * - wire SPI ports on the LSM to their respective pins on the due's SPI header (not
+ * ICSP!)
+ *
+ * - wire INT2 to digital pin 53 and the LSM's chip select/slave select port to
+ * pin 10 above the pwm module.
+ *
+ * - ground the SPI module, arduino, and LSM together, preferably alone. i had to use
+ * an audio isolation amplifier to provide a quiet enough ground to support the
+ * unusually high SPI baud rate i use here, discussed later.
+ *
+ * - wire LSM's Vin to the arduino's 3.3V supply. leave Vdd floating */
+
+#include <SPI.h>
+
+/* slave select pin */
+#define LSM_CS 10
+
+/* wire to INT2 which latches to a magnometer-read-ready signal */
+#define MAGNO_RDY_PIN 53
+
+/* SPI clock divider (84MHz divided by this equals SPI frequency) */
+#define SPI_CLK_DIV 3
+
+/* frequency of temperature sensor in Hz, set in lsm_config() */
+#define TEMP_FREQ 100
+
+/* struct representing magnometer values at shared instant of time */
+struct magno_point {
+
+ signed short x;
+ signed short y;
+ signed short z;
+};
+
+/* hands off */
+const byte BAD_REGS[8] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x0E, 0x10, 0x11 };
+
+/* these are set on successful completion of their respective funcs */
+bool SERIAL_CONFIGURED = 0;
+bool SPI_CONFIGURED = 0;
+bool SPI_OK = 0;
+bool LSM_CONFIGURED = 0;
+
+/* don't brick the LSM */
+bool matches_badreg(byte addr) {
+
+ short i;
+ i = 0;
+
+ for (; i < 8; i++)
+ if (addr == BAD_REGS[i])
+ return true;
+
+ return false;
+}
+
+/* fired when critical exception encountered, doesn't return */
+void killspin(String msg) {
+
+ Serial.println(msg);
+ Serial.println("exception occurred or assertion failed. no-operation until reset");
+ while (1);
+}
+
+/* reads n sequential bytes starting @ addr returns byte array of size n
+ * returned array must be free()'d manually! */
+byte *spi_multiread(byte addr, short n) {
+
+ byte *ret, first;
+ short cnt;
+
+ if (matches_badreg(addr))
+ killspin("tried to read from a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to read over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("invalid lsm register address");
+
+ /* set msb to read, 2nd msb for multibyte op, and append 6 bit address field */
+ first = 128 + 64 + addr;
+ cnt = 0;
+
+ /* free this! */
+ ret = (byte *) calloc(n, 1);
+
+ /* kickoff read operation */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+
+ for (; cnt < n - 1; cnt++)
+ ret[cnt] = SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+
+ ret[n - 1] = SPI.transfer(LSM_CS, first, SPI_LAST);
+
+ return ret;
+}
+
+/* reads & returns 1 byte @ addr */
+byte spi_read(byte addr) {
+
+ byte first, ret;
+
+ if (matches_badreg(addr))
+ killspin("tried to read from a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to read over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("invalid lsm register address");
+
+ /* set msb to read and append 6 bit address field */
+ first = 128 + addr;
+
+ /* perform 16 bit SPI exchange as per LSM datasheet's specification */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+ ret = SPI.transfer(LSM_CS, 0x00, SPI_LAST);
+
+ return ret;
+}
+
+/* write single byte @ addr */
+void spi_write(byte addr, byte data) {
+
+ byte first;
+
+ if (matches_badreg(addr))
+ killspin("tried to write to a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to write over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("INVALID ADDRESS");
+
+ /* set 6 bit address field */
+ first = addr;
+
+ /* perform 16 bit SPI exchange as per LSM datasheet's specification */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+ SPI.transfer(LSM_CS, data, SPI_LAST);
+}
+
+void spi_config() {
+
+ SPI.begin(LSM_CS);
+
+ /* my arduino due has a 84 MHz cpu which is divided here to provide the
+ * SPI baud rate. the LSM's data sheet purports the maximum SPI frequency
+ * is 10MHz, however i've found that it works fine up to 28MHz, which is
+ * the frequency set below (84 MHz / 3 = 28 MHz) */
+ SPI.setClockDivider(LSM_CS, SPI_CLK_DIV);
+
+ /* LSM is big endian */
+ SPI.setBitOrder(LSM_CS, MSBFIRST);
+
+ /* clock is active-low, exchange occurs on clock's first falling edge
+ * CPOL = 1, CKE = 0 */
+ SPI.setDataMode(LSM_CS, SPI_MODE3);
+
+ SPI_CONFIGURED = 1;
+}
+
+/* read & check immutable device ID reg a number of times to guarantee LSM
+ * slave is responding and capable of handling master's SPI clock freq.
+ * then, write reg & read back to test writing */
+boolean spi_test() {
+
+ bool read_ok, write_ok;
+ byte i;
+
+ i = 0;
+ read_ok = true;
+ write_ok = true;
+
+ if (!SPI_CONFIGURED)
+ killspin("tried to test SPI before it was configured!");
+
+ /* cheat a little here */
+ SPI_OK = 1;
+
+ /* test reading */
+ Serial.print(" [READ: ");
+
+ for (; i < 100; i++)
+ if (spi_read(0x0F) != 0x49)
+ read_ok = false;
+
+ if (read_ok)
+ Serial.print("OK, WRITE: ");
+ else
+ Serial.print("FAIL, WRITE: ");
+
+ /* test writing with */
+ i = 0;
+ for (; i < 100; i++) {
+
+ spi_write(0x17, i);
+
+ /* uncomment for write debugging
+ Serial.print("WROTE ");
+ Serial.print(i);
+ Serial.print(" GOT ");
+ Serial.println(spi_read(0x17));*/
+
+ if (spi_read(0x17) != i)
+ write_ok = false;
+ }
+
+ /* write back datasheet-defined default value to test
+ * register we used (OFFSET_X_L_M) */
+ if (write_ok)
+ spi_write(0x17, 0x00);
+
+ /* finish up */
+ if (write_ok)
+ Serial.print("OK] ");
+ else
+ Serial.print("FAIL] ");
+
+ if (read_ok && write_ok) {
+
+ SPI_OK = 1;
+ return true;
+
+ } else {
+
+ SPI_OK = 0;
+ Serial.println(":: failed!");
+ return false;
+ }
+}
+
+void lsm_config() {
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to configure lsm before spi was configured & tested");
+
+ /* set 16 bit 2's comp. magnetic field offset values for x, y, z.
+ * these default to zero as correct offset values depend on your geographical
+ * location. you can find the current magnetic field strength at your coords
+ * using NOAA's database: http://www.ngdc.noaa.gov/geomag-web/#igrfwmm
+ *
+ * in the WMM model, the significant values are north comp (z offset), east comp
+ * (x offset), and vertical comp (y offset). you can ignore the 'change/year' and
+ * 'uncertainty' values
+ *
+ * you must translate the given tesla values into corresponding gauss equivalents
+ * and scale them according to the range specified later in this function. you will
+ * usually use the +2:-2 gauss scale. here is an example conversion for
+ * latitude 43° 2' 14" N, longitude 76° 7' 36" W (near syracuse university in
+ * syracuse, NY 13210), 0 meters above sea level, taken on february 16th, 2015 at 07:32 UTC:
+ *
+ * [x] :: -4,129.9 nanoteslas :: -0.041299 gauss
+ * [y] :: 49,817.8 nanoteslas :: 0.498178 gauss
+ * [z] :: 18,755.9 nanoteslas :: 0.187559 gauss
+ *
+ * next, we need to fit these values into our 4-gauss scale (spanning from +2 gauss
+ * to -2 gauss) in the context of a 16-bit signed number. to do this, take the gauss value
+ * and divide it by 2. take this number, and multiply it by 2^15 - 1. round to closest integer.
+ * finally, multiply this value by -1 as the offset value combined with the sensed value should
+ * result in zero. negatives should be expressed as two's complement. here are the offsets derived
+ * from the previous values:
+ *
+ * [x] :: 677 :: 0x02A5
+ * [y] :: -16,324 :: 0xC03C
+ * [z] :: -6,146 :: 0xE7FE
+ */
+ const byte x_lo_offset = 0xA5;
+ const byte x_hi_offset = 0x02;
+
+ const byte y_lo_offset = 0x3C;
+ const byte y_hi_offset = 0xC0;
+
+ const byte z_lo_offset = 0xFE;
+ const byte z_hi_offset = 0xE7;
+
+ spi_write(0x16, x_lo_offset);
+ spi_write(0x17, x_hi_offset);
+
+ spi_write(0x18, y_lo_offset);
+ spi_write(0x19, y_hi_offset);
+
+ spi_write(0x1A, z_lo_offset);
+ spi_write(0x1B, z_hi_offset);
+
+ /* latch magnometer-ready to INT2 output pin */
+ spi_write(0x23, 0x04);
+
+ /* enable temperature sensor,
+ * select high magnetic resolution,
+ * select 100Hz sensor rate */
+ spi_write(0x24, 0xF4);
+
+ /* set full scale of magnetometer to +2:-2 gauss as
+ * earth's field is usually between +0.65:-0.65 G */
+ spi_write(0x25, 0x00);
+
+ /* switch on magnometer, to continuous conversion mode */
+ spi_write(0x26, 0x00);
+
+ LSM_CONFIGURED = 1;
+}
+
+/* returns a size-n array of readings from temperature sensor. function waits
+ * between reads for a time equal to the period length of the sensor as to avoid
+ * multiple reads of an un-updated value. this is a hack to get around the fact
+ * this chip does not have a TEMP_READY bit in a status register like the magnometer
+ * or accelerometer do.
+ * caller must free() returned pointer */
+signed short *pull_temp_values(int n) {
+
+ signed short *ret;
+ int sensor_period, i;
+ byte *temp_pair, *sync_pair_i, *sync_pair_f;
+
+ /* period length in milliseconds of temperature sensor refresh */
+ sensor_period = 1000 / TEMP_FREQ;
+
+ i = 0;
+ ret = (signed short *) calloc(n, 2);
+
+ sync_pair_i = sync_pair_f = spi_multiread(0x05, 2);
+
+ /* spin until sensor cranks */
+ while (sync_pair_i == sync_pair_f)
+ sync_pair_f = spi_multiread(0x05, 2);
+
+ /* wait until mid-period to read as to avoid edge-case duplicates */
+ delay(sensor_period / 2);
+
+ for (; i < n; i++) {
+ temp_pair = spi_multiread(0x05, 2);
+ ret[i] = word(temp_pair[1], temp_pair[0]);
+ free(temp_pair);
+ delay(sensor_period);
+ }
+
+ free(sync_pair_i);
+ free(sync_pair_f);
+
+ return ret;
+}
+
+/* returns a magno_point struct from passed 48 bit input taken from magno sensors */
+struct magno_point parse_raw_magno_data(byte *in) {
+
+ struct magno_point ret;
+
+ ret.x = word(in[1], in[0]);
+ ret.y = word(in[3], in[2]);
+ ret.z = word(in[5], in[4]);
+
+ return ret;
+}
+
+/* returns a size-n array of readings from magnometer. result contains 3 words
+ * describing felt magnetic field strengths x, y, z directions. function polls INT2
+ * (latched to magnometer-ready signal) until it goes high before reading from sensor.
+ * this guarantees each member in returned array is a genuine, non-repeat value from a
+ * single magnometer sensor cycle
+ * caller must free() returned pointer */
+struct magno_point *pull_magno_values(int n) {
+
+ struct magno_point *ret;
+ int i;
+
+ i = 0;
+ ret = (struct magno_point *) calloc(n, sizeof(struct magno_point));
+
+ for(; i < n; i++) {
+
+ /* spin until sensors are fresh */
+ while(digitalRead(MAGNO_RDY_PIN) != 1);
+
+ ret[i] = parse_raw_magno_data(spi_multiread(0x08, 6));
+ }
+
+ return ret;
+}
+
+void setup() {
+
+ /* set up magno. read ready signal */
+ pinMode(MAGNO_RDY_PIN, INPUT);
+
+ /* this is about as fast as you can get on the serial console */
+ Serial.begin(115200);
+ SERIAL_CONFIGURED = 1;
+
+ /* spi init */
+ Serial.print("configuring spi..");
+ spi_config();
+ Serial.println("done");
+
+ /* spi check */
+ Serial.print("testing spi..");
+ if (spi_test())
+ Serial.println("done");
+ else
+ killspin("SPI test failed. perhaps the device is not wired correctly or your frequency is too high");
+
+ /* lsm init */
+ Serial.print("configuring lsm..");
+ lsm_config();
+ Serial.println("done");
+}
+
+/* demonstration of realtime temperature stream. does not return */
+void stream_temp() {
+
+ for(;;) {
+ signed short *temp_vals;
+ temp_vals = pull_temp_values(100);
+
+ for (int i = 0; i < 100; i++) {
+ if(!(i % 20) && i)
+ Serial.print('\n');
+ else if(i)
+ Serial.print(" ");
+
+ Serial.print(temp_vals[i], DEC);
+ }
+
+ Serial.println("\n--------------------------------------------------------------------------------");
+
+ free(temp_vals);
+ }
+}
+
+/* demonstration of realtime magnometer stream. does not return */
+void stream_magno() {
+
+ struct magno_point *read_buf;
+
+ read_buf = pull_magno_values(100);
+
+ for(int i = 0; i < 100; i++) {
+
+ Serial.print("X: ");
+ Serial.println(read_buf[i].x, DEC);
+ Serial.print("Y: ");
+ Serial.println(read_buf[i].y, DEC);
+ Serial.print("Z: ");
+ Serial.println(read_buf[i].z, DEC);
+ Serial.println("---------");
+ }
+
+ free(read_buf);
+}
+
+void loop() {
+
+ stream_temp();
+ //stream_magno();
+}
+/* Copyright (c) 2015, Ian Sutton <ian@kremlin.cc>
+
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */
+
+ /* this is a library for the arduino due that controls the LSM303D accelerometer
+ * & magnometer. it will not work on other arduino models, it uses API calls
+ * exclusive to newer ARM-based arduinos.
+ *
+ * steps to recreate:
+ *
+ * !! be especially careful of the 5V output in on the due's SPI header. it is a high !!
+ * !! current output & will cook anything nearby. refer to this diagram before making !!
+ * !! any connections: http://uglyman.kremlin.cc/quick/due-pinout-web.png !!
+ *
+ * - wire SPI ports on the LSM to their respective pins on the due's SPI header (not
+ * ICSP!)
+ *
+ * - wire INT2 to digital pin 53 and the LSM's chip select/slave select port to
+ * pin 10 above the pwm module.
+ *
+ * - ground the SPI module, arduino, and LSM together, preferably alone. i had to use
+ * an audio isolation amplifier to provide a quiet enough ground to support the
+ * unusually high SPI baud rate i use here, discussed later.
+ *
+ * - wire LSM's Vin to the arduino's 3.3V supply. leave Vdd floating */
+
+#include <SPI.h>
+
+/* slave select pin */
+#define LSM_CS 10
+
+/* wire to INT2 which latches to a magnometer-read-ready signal */
+#define MAGNO_RDY_PIN 53
+
+/* SPI clock divider (84MHz divided by this equals SPI frequency) */
+#define SPI_CLK_DIV 3
+
+/* frequency of temperature sensor in Hz, set in lsm_config() */
+#define TEMP_FREQ 100
+
+/* struct representing magnometer values at shared instant of time */
+struct magno_point {
+
+ signed short x;
+ signed short y;
+ signed short z;
+};
+
+/* hands off */
+const byte BAD_REGS[8] = { 0x00, 0x01, 0x02, 0x03, 0x04, 0x0E, 0x10, 0x11 };
+
+/* these are set on successful completion of their respective funcs */
+bool SERIAL_CONFIGURED = 0;
+bool SPI_CONFIGURED = 0;
+bool SPI_OK = 0;
+bool LSM_CONFIGURED = 0;
+
+/* don't brick the LSM */
+bool matches_badreg(byte addr) {
+
+ short i;
+ i = 0;
+
+ for (; i < 8; i++)
+ if (addr == BAD_REGS[i])
+ return true;
+
+ return false;
+}
+
+/* fired when critical exception encountered, doesn't return */
+void killspin(String msg) {
+
+ Serial.println(msg);
+ Serial.println("exception occurred or assertion failed. no-operation until reset");
+ while (1);
+}
+
+/* reads n sequential bytes starting @ addr returns byte array of size n
+ * returned array must be free()'d manually! */
+byte *spi_multiread(byte addr, short n) {
+
+ byte *ret, first;
+ short cnt;
+
+ if (matches_badreg(addr))
+ killspin("tried to read from a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to read over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("invalid lsm register address");
+
+ /* set msb to read, 2nd msb for multibyte op, and append 6 bit address field */
+ first = 128 + 64 + addr;
+ cnt = 0;
+
+ /* free this! */
+ ret = (byte *) calloc(n, 1);
+
+ /* kickoff read operation */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+
+ for (; cnt < n - 1; cnt++)
+ ret[cnt] = SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+
+ ret[n - 1] = SPI.transfer(LSM_CS, first, SPI_LAST);
+
+ return ret;
+}
+
+/* reads & returns 1 byte @ addr */
+byte spi_read(byte addr) {
+
+ byte first, ret;
+
+ if (matches_badreg(addr))
+ killspin("tried to read from a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to read over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("invalid lsm register address");
+
+ /* set msb to read and append 6 bit address field */
+ first = 128 + addr;
+
+ /* perform 16 bit SPI exchange as per LSM datasheet's specification */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+ ret = SPI.transfer(LSM_CS, 0x00, SPI_LAST);
+
+ return ret;
+}
+
+/* write single byte @ addr */
+void spi_write(byte addr, byte data) {
+
+ byte first;
+
+ if (matches_badreg(addr))
+ killspin("tried to write to a reserved, internal register!");
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to write over SPI before it was configured or tested!");
+
+ /* addresses are 6 bits wide */
+ if (addr > 63)
+ killspin("INVALID ADDRESS");
+
+ /* set 6 bit address field */
+ first = addr;
+
+ /* perform 16 bit SPI exchange as per LSM datasheet's specification */
+ SPI.transfer(LSM_CS, first, SPI_CONTINUE);
+ SPI.transfer(LSM_CS, data, SPI_LAST);
+}
+
+void spi_config() {
+
+ SPI.begin(LSM_CS);
+
+ /* my arduino due has a 84 MHz cpu which is divided here to provide the
+ * SPI baud rate. the LSM's data sheet purports the maximum SPI frequency
+ * is 10MHz, however i've found that it works fine up to 28MHz, which is
+ * the frequency set below (84 MHz / 3 = 28 MHz) */
+ SPI.setClockDivider(LSM_CS, SPI_CLK_DIV);
+
+ /* LSM is big endian */
+ SPI.setBitOrder(LSM_CS, MSBFIRST);
+
+ /* clock is active-low, exchange occurs on clock's first falling edge
+ * CPOL = 1, CKE = 0 */
+ SPI.setDataMode(LSM_CS, SPI_MODE3);
+
+ SPI_CONFIGURED = 1;
+}
+
+/* read & check immutable device ID reg a number of times to guarantee LSM
+ * slave is responding and capable of handling master's SPI clock freq.
+ * then, write reg & read back to test writing */
+boolean spi_test() {
+
+ bool read_ok, write_ok;
+ byte i;
+
+ i = 0;
+ read_ok = true;
+ write_ok = true;
+
+ if (!SPI_CONFIGURED)
+ killspin("tried to test SPI before it was configured!");
+
+ /* cheat a little here */
+ SPI_OK = 1;
+
+ /* test reading */
+ Serial.print(" [READ: ");
+
+ for (; i < 100; i++)
+ if (spi_read(0x0F) != 0x49)
+ read_ok = false;
+
+ if (read_ok)
+ Serial.print("OK, WRITE: ");
+ else
+ Serial.print("FAIL, WRITE: ");
+
+ /* test writing with */
+ i = 0;
+ for (; i < 100; i++) {
+
+ spi_write(0x17, i);
+
+ /* uncomment for write debugging
+ Serial.print("WROTE ");
+ Serial.print(i);
+ Serial.print(" GOT ");
+ Serial.println(spi_read(0x17));*/
+
+ if (spi_read(0x17) != i)
+ write_ok = false;
+ }
+
+ /* write back datasheet-defined default value to test
+ * register we used (OFFSET_X_L_M) */
+ if (write_ok)
+ spi_write(0x17, 0x00);
+
+ /* finish up */
+ if (write_ok)
+ Serial.print("OK] ");
+ else
+ Serial.print("FAIL] ");
+
+ if (read_ok && write_ok) {
+
+ SPI_OK = 1;
+ return true;
+
+ } else {
+
+ SPI_OK = 0;
+ Serial.println(":: failed!");
+ return false;
+ }
+}
+
+void lsm_config() {
+
+ if (!SPI_CONFIGURED || !SPI_OK)
+ killspin("tried to configure lsm before spi was configured & tested");
+
+ /* set 16 bit 2's comp. magnetic field offset values for x, y, z.
+ * these default to zero as correct offset values depend on your geographical
+ * location. you can find the current magnetic field strength at your coords
+ * using NOAA's database: http://www.ngdc.noaa.gov/geomag-web/#igrfwmm
+ *
+ * in the WMM model, the significant values are north comp (z offset), east comp
+ * (x offset), and vertical comp (y offset). you can ignore the 'change/year' and
+ * 'uncertainty' values
+ *
+ * you must translate the given tesla values into corresponding gauss equivalents
+ * and scale them according to the range specified later in this function. you will
+ * usually use the +2:-2 gauss scale. here is an example conversion for
+ * latitude 43° 2' 14" N, longitude 76° 7' 36" W (near syracuse university in
+ * syracuse, NY 13210), 0 meters above sea level, taken on february 16th, 2015 at 07:32 UTC:
+ *
+ * [x] :: -4,129.9 nanoteslas :: -0.041299 gauss
+ * [y] :: 49,817.8 nanoteslas :: 0.498178 gauss
+ * [z] :: 18,755.9 nanoteslas :: 0.187559 gauss
+ *
+ * next, we need to fit these values into our 4-gauss scale (spanning from +2 gauss
+ * to -2 gauss) in the context of a 16-bit signed number. to do this, take the gauss value
+ * and divide it by 2. take this number, and multiply it by 2^15 - 1. round to closest integer.
+ * finally, multiply this value by -1 as the offset value combined with the sensed value should
+ * result in zero. negatives should be expressed as two's complement. here are the offsets derived
+ * from the previous values:
+ *
+ * [x] :: 677 :: 0x02A5
+ * [y] :: -16,324 :: 0xC03C
+ * [z] :: -6,146 :: 0xE7FE
+ */
+ const byte x_lo_offset = 0xA5;
+ const byte x_hi_offset = 0x02;
+
+ const byte y_lo_offset = 0x3C;
+ const byte y_hi_offset = 0xC0;
+
+ const byte z_lo_offset = 0xFE;
+ const byte z_hi_offset = 0xE7;
+
+ spi_write(0x16, x_lo_offset);
+ spi_write(0x17, x_hi_offset);
+
+ spi_write(0x18, y_lo_offset);
+ spi_write(0x19, y_hi_offset);
+
+ spi_write(0x1A, z_lo_offset);
+ spi_write(0x1B, z_hi_offset);
+
+ /* latch magnometer-ready to INT2 output pin */
+ spi_write(0x23, 0x04);
+
+ /* enable temperature sensor,
+ * select high magnetic resolution,
+ * select 100Hz sensor rate */
+ spi_write(0x24, 0xF4);
+
+ /* set full scale of magnetometer to +2:-2 gauss as
+ * earth's field is usually between +0.65:-0.65 G */
+ spi_write(0x25, 0x00);
+
+ /* switch on magnometer, to continuous conversion mode */
+ spi_write(0x26, 0x00);
+
+ LSM_CONFIGURED = 1;
+}
+
+/* returns a size-n array of readings from temperature sensor. function waits
+ * between reads for a time equal to the period length of the sensor as to avoid
+ * multiple reads of an un-updated value. this is a hack to get around the fact
+ * this chip does not have a TEMP_READY bit in a status register like the magnometer
+ * or accelerometer do.
+ * caller must free() returned pointer */
+signed short *pull_temp_values(int n) {
+
+ signed short *ret;
+ int sensor_period, i;
+ byte *temp_pair, *sync_pair_i, *sync_pair_f;
+
+ /* period length in milliseconds of temperature sensor refresh */
+ sensor_period = 1000 / TEMP_FREQ;
+
+ i = 0;
+ ret = (signed short *) calloc(n, 2);
+
+ sync_pair_i = sync_pair_f = spi_multiread(0x05, 2);
+
+ /* spin until sensor cranks */
+ while (sync_pair_i == sync_pair_f)
+ sync_pair_f = spi_multiread(0x05, 2);
+
+ /* wait until mid-period to read as to avoid edge-case duplicates */
+ delay(sensor_period / 2);
+
+ for (; i < n; i++) {
+ temp_pair = spi_multiread(0x05, 2);
+ ret[i] = word(temp_pair[1], temp_pair[0]);
+ free(temp_pair);
+ delay(sensor_period);
+ }
+
+ free(sync_pair_i);
+ free(sync_pair_f);
+
+ return ret;
+}
+
+/* returns a magno_point struct from passed 48 bit input taken from magno sensors */
+struct magno_point parse_raw_magno_data(byte *in) {
+
+ struct magno_point ret;
+
+ ret.x = word(in[1], in[0]);
+ ret.y = word(in[3], in[2]);
+ ret.z = word(in[5], in[4]);
+
+ return ret;
+}
+
+/* returns a size-n array of readings from magnometer. result contains 3 words
+ * describing felt magnetic field strengths x, y, z directions. function polls INT2
+ * (latched to magnometer-ready signal) until it goes high before reading from sensor.
+ * this guarantees each member in returned array is a genuine, non-repeat value from a
+ * single magnometer sensor cycle
+ * caller must free() returned pointer */
+struct magno_point *pull_magno_values(int n) {
+
+ struct magno_point *ret;
+ int i;
+
+ i = 0;
+ ret = (struct magno_point *) calloc(n, sizeof(struct magno_point));
+
+ for(; i < n; i++) {
+
+ /* spin until sensors are fresh */
+ while(digitalRead(MAGNO_RDY_PIN) != 1);
+
+ ret[i] = parse_raw_magno_data(spi_multiread(0x08, 6));
+ }
+
+ return ret;
+}
+
+void setup() {
+
+ /* set up magno. read ready signal */
+ pinMode(MAGNO_RDY_PIN, INPUT);
+
+ /* this is about as fast as you can get on the serial console */
+ Serial.begin(115200);
+ SERIAL_CONFIGURED = 1;
+
+ /* spi init */
+ Serial.print("configuring spi..");
+ spi_config();
+ Serial.println("done");
+
+ /* spi check */
+ Serial.print("testing spi..");
+ if (spi_test())
+ Serial.println("done");
+ else
+ killspin("SPI test failed. perhaps the device is not wired correctly or your frequency is too high");
+
+ /* lsm init */
+ Serial.print("configuring lsm..");
+ lsm_config();
+ Serial.println("done");
+}
+
+/* demonstration of realtime temperature stream. does not return */
+void stream_temp() {
+
+ for(;;) {
+ signed short *temp_vals;
+ temp_vals = pull_temp_values(100);
+
+ for (int i = 0; i < 100; i++) {
+ if(!(i % 20) && i)
+ Serial.print('\n');
+ else if(i)
+ Serial.print(" ");
+
+ Serial.print(temp_vals[i], DEC);
+ }
+
+ Serial.println("\n--------------------------------------------------------------------------------");
+
+ free(temp_vals);
+ }
+}
+
+/* demonstration of realtime magnometer stream. does not return */
+void stream_magno() {
+
+ struct magno_point *read_buf;
+
+ read_buf = pull_magno_values(100);
+
+ for(int i = 0; i < 100; i++) {
+
+ Serial.print("X: ");
+ Serial.println(read_buf[i].x, DEC);
+ Serial.print("Y: ");
+ Serial.println(read_buf[i].y, DEC);
+ Serial.print("Z: ");
+ Serial.println(read_buf[i].z, DEC);
+ Serial.println("---------");
+ }
+
+ free(read_buf);
+}
+
+void loop() {
+
+ stream_temp();
+ //stream_magno();
+}
+