copied the file twice, whoops

[grab_bag.git] / lsm303d_arm_arduino.c

/* 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();
}