Diff: MicroBitMpr121.h

Revision:

4:f63476855239

Parent:

3:a91b1bb396ca

Child:

5:4a8384331ca7

--- a/MicroBitMpr121.h	Mon Jan 16 14:31:36 2017 +0000
+++ b/MicroBitMpr121.h	Mon Jan 16 19:19:50 2017 +0000
@@ -1,130 +1,295 @@
+/*
+The MIT License (MIT)
 
-#ifndef MICROBITMPR121_H
-#define MICROBITMPR121_H
-#include "MicroBit.h"
+Copyright (c) 2016 British Broadcasting Corporation.
+This software is provided by Lancaster University by arrangement with the BBC.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-class MicroBitMpr121
-{
-private:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef MICROBIT_MPR121_H
+#define MICROBIT_MPR121_H
+
+#include "mbed.h"
+#include "MicroBitConfig.h"
+#include "MicroBitPin.h"
+#include "MicroBitComponent.h"
+#include "MicroBitI2C.h"
 
-    MicroBitI2C _i2c;
-    PinName     _irq;
-    uint8_t      _i2c_addr;
-    volatile uint16_t _button;
-    volatile uint32_t _button_has_changed;
+/**
+  * Relevant pin assignments
+  */
+#define MPR121_DEFAULT_INT          MICROBIT_PIN_P16
+
+/**
+  * I2C constants
+  */
+#define MPR121_DEFAULT_ADDR    0x1D
+
+
+/**
+  * Status Bits
+  */
+
 
-    /** The interrupt handler for the IRQ pin
-     */
-    void handler(void);
+/**
+  * MPR121 MAGIC ID value
+  * Returned from the MPR121_WHO_AM_I register for ID purposes.
+  */
+//#define MPR121_WHOAMI_VAL 0X9A 
+
+/**
+  * Class definition for MicroBit Mpr121.
+  *
+  * Represents an implementation of the Mpr121.
+  * Also includes ...
+  */
+class MicroBitMpr121 : public MicroBitComponent
+{
+    uint16_t                address;                  // I2C address of the magnetmometer.
+
+    DigitalIn               int1;                     // Data ready interrupt.
+    MicroBitI2C&            i2c;                      // The I2C interface the sensor is connected to.
 
 public:
 
     /**
-     *  @enum MPR121_ADDR
-     *  @brief Possible terminations for the ADDR pin
-     */
-    enum MPR121_ADDR {
-        ADDR_VSS = 0x5A, /*!< ADDR connected to VSS */
-        ADDR_VDD,    /*!< ADDR connected to VDD */
-        ADDR_SCL,    /*!< ADDR connected to SDA */
-        ADDR_SDA     /*!< ADDR connected to SCL */
-    };
+    * Constructor.
+    * Create a software representation of a mpr121.
+    *
+    * @param _i2c an instance of i2c, which the mpr121 is accessible from.
+    *
+    * @param address the address for the mpr121 register on the i2c bus. Defaults to MPR121_DEFAULT_ADDR.
+    *
+    * @param id the ID of the new MicroBitMpr121 object. Defaults to MPR121_DEFAULT_ADDR.
+    *
+    * @code
+    * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
+    *
+    * MicroBitMpr121 mpr121(i2c);
+    * @endcode
+    */
+    MicroBitMpr121(MicroBitI2C& _i2c, uint16_t address = MPR121_DEFAULT_ADDR, uint16_t id = MICROBIT_ID_COMPASS);
+
+    /**
+      * Configures the compass for the sample rate defined in this object.
+      * The nearest values are chosen to those defined that are supported by the hardware.
+      * The instance variables are then updated to reflect reality.
+      *
+      * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be configured.
+      */
+    int configure();
+
+    /**
+      * Attempts to set the sample rate of the compass to the specified value (in ms).
+      *
+      * @param period the requested time between samples, in milliseconds.
+      *
+      * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
+      *
+      * @code
+      * // sample rate is now 20 ms.
+      * compass.setPeriod(20);
+      * @endcode
+      *
+      * @note The requested rate may not be possible on the hardware. In this case, the
+      * nearest lower rate is chosen.
+      */
+    int setPeriod(int period);
+
+    /**
+      * Reads the currently configured sample rate of the compass.
+      *
+      * @return The time between samples, in milliseconds.
+      */
+    int getPeriod();
+
+    /**
+      * Gets the current heading of the device, relative to magnetic north.
+      *
+      * If the compass is not calibrated, it will raise the MICROBIT_COMPASS_EVT_CALIBRATE event.
+      *
+      * Users wishing to implement their own calibration algorithms should listen for this event,
+      * using MESSAGE_BUS_LISTENER_IMMEDIATE model. This ensures that calibration is complete before
+      * the user program continues.
+      *
+      * @return the current heading, in degrees. Or MICROBIT_CALIBRATION_IN_PROGRESS if the compass is calibrating.
+      *
+      * @code
+      * compass.heading();
+      * @endcode
+      */
+    int heading();
+
+    /**
+      * Attempts to read the 8 bit ID from the magnetometer, this can be used for
+      * validation purposes.
+      *
+      * @return the 8 bit ID returned by the magnetometer, or MICROBIT_I2C_ERROR if the request fails.
+      *
+      * @code
+      * compass.whoAmI();
+      * @endcode
+      */
+    int whoAmI();
+
+    /**
+      * Determines the overall magnetic field strength based on the latest update from the magnetometer.
+      *
+      * @return The magnetic force measured across all axis, in nano teslas.
+      *
+      * @code
+      * compass.getFieldStrength();
+      * @endcode
+      */
+    int getFieldStrength();
+
+    /**
+      * Reads the current die temperature of the compass.
+      *
+      * @return the temperature in degrees celsius, or MICROBIT_I2C_ERROR if the temperature reading could not be retreived
+      *         from the accelerometer.
+      */
+    int readTemperature();
 
     /**
-     *  @enum MPR121_REGISTER
-     *  @brief The device register map
-     */
-    enum MPR121_REGISTER {
-        ELE0_7_STAT = 0x00,
-        ELE8_11_STAT, ELE0_7_OOR_STAT, ELE8_11_OOR_STAT, EFD0LB, EFD0HB,
-        EFD1LB, EFD1HB, EFD2LB, EFD2HB, EFD3LB, EFD3HB, EFD4LB, EFD4HB, EFD5LB, EFD5HB,
+      * Perform a calibration of the compass.
+      *
+      * This method will be called automatically if a user attempts to read a compass value when
+      * the compass is uncalibrated. It can also be called at any time by the user.
+      *
+      * The method will only return once the compass has been calibrated.
+      *
+      * @return MICROBIT_OK, MICROBIT_I2C_ERROR if the magnetometer could not be accessed,
+      * or MICROBIT_CALIBRATION_REQUIRED if the calibration algorithm failed to complete successfully.
+      *
+      * @note THIS MUST BE CALLED TO GAIN RELIABLE VALUES FROM THE COMPASS
+      */
+    int calibrate();
 
-        EFD6LB = 0x10,
-        EFD6HB, EFD7LB, EFD7HB, EFD8LB, EFD8HB, EFD9LB, EFD9HB, EFD10LB,
-        EFD10HB, EFD11LB, EFD11HB, EFDPROXLB, EFDPROXHB, E0BV, E1BV,
 
-        E2BV = 0x20,
-        E3BV, E4BV, E5BV, E6BV, E7BV, E8BV, E9BV, E10BV, E11BV, EPROXBV,
-        MHDR, NHDR, NCLR, FDLR, MHDF,
-
-        NHDF = 0x30,
-        NCLF, FDLF, NHDT, NCLT, FDLT, MHDPROXR, NHDPROXR, NCLPROXR,
-        FDLPROXR, MHDPROXF, NHDPROXF, NCLPROXF, FDLPROXF, NHDPROXT, NCLPROXT,
+    /**
+      * Updates the local sample, only if the compass indicates that
+      * data is stale.
+      *
+      * @note Can be used to trigger manual updates, if the device is running without a scheduler.
+      *       Also called internally by all get[X,Y,Z]() member functions.
+      */
+    int updateSample();
 
-        FDLPROXT = 0x40,
-        E0TTH, E0RTH, E1TTH, E1RTH, E2TTH, E2RTH, E3TTH, E3RTH,
-        E4TTH, E4RTH, E5TTH, E5RTH, E6TTH, E6RTH, E7TTH,
+    /**
+      * Periodic callback from MicroBit idle thread.
+      *
+      * Calls updateSample().
+      */
+    virtual void idleTick();
 
-        E7RTH = 0x50,
-        E8TTH, E8RTH, E9TTH, E9RTH, E10TTH, E10RTH, E11TTH, E11RTH,
-        EPROXTTH, EPROXRTH, DT_DR, CDC_CONFIG, CDT_CONFIG, ECR, CDC0,
+    /**
+      * Returns 0 or 1. 1 indicates that the compass is calibrated, zero means the compass requires calibration.
+      */
+    int isCalibrated();
 
-        CDC1 = 0x60,
-        CDC2, CDC3, CDC4, CDC5, CDC6, CDC7, CDC8, CDC9, CDC10, CDC11, CDCPROX, CDT0_CDT1,
-        CDT2_CDT3, CDT4_CDT5, CDT6_CDT7,
+    /**
+      * Returns 0 or 1. 1 indicates that the compass is calibrating, zero means the compass is not currently calibrating.
+      */
+    int isCalibrating();
 
-        CDT8_CDT9 = 0x70,
-        CDT10_CDT11, CDTPROX, GPIO_CTRL0, GPIO_CTRL1, GPIO_DATA, GPIO_DIR, GPIO_EN, GPIO_SET,
-        GPIO_CLR, GPIO_TOGGLE, AUTO_CFG0, AUTO_CFG1, USL, LSL, TL,
+    /**
+      * Clears the calibration held in persistent storage, and sets the calibrated flag to zero.
+      */
+    void clearCalibration();
 
-        SRST = 0x80
-    };
+    /**
+      * Destructor for MicroBitMpr121, where we deregister this instance from the array of fiber components.
+      */
+    ~MicroBitMpr121();
 
-    /** Create the MPR121 object with defaults for microbit, pi-cap and int P16
-    */
-    MicroBitMpr121();
+private:
 
-    /** Create the MPR121 object
-     *  @param sda - PinName for sda
-     *  @param sda - PinName for scl
-     *  @param sda - PinName for irq
-     *  @param addr - Connection of the address line
-     */
+    /**
+      * Issues a standard, 2 byte I2C command write to the accelerometer.
+      *
+      * Blocks the calling thread until complete.
+      *
+      * @param reg The address of the register to write to.
+      *
+      * @param value The value to write.
+      *
+      * @return MICROBIT_OK on success, MICROBIT_I2C_ERROR if the the write request failed.
+      */
+    int writeCommand(uint8_t reg, uint8_t value);
 
-    //MicroBitMpr121(PinName sda, PinName scl, PinName irq, MPR121_ADDR addr);
-    /** Clear state variables and initilize the dependant objects
-     */
-
-    void init(void);
-
-    /** Allow the IC to run and collect user input
-     */
-    void enable(void);
-
-    /** Stop the IC and put into low power mode
-     */
-    void disable(void);
+    /**
+      * Issues a read command, copying data into the specified buffer.
+      *
+      * Blocks the calling thread until complete.
+      *
+      * @param reg The address of the register to access.
+      *
+      * @param buffer Memory area to read the data into.
+      *
+      * @param length The number of bytes to read.
+      *
+      * @return MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER or MICROBIT_I2C_ERROR if the the read request failed.
+      */
+    int readCommand(uint8_t reg, uint8_t* buffer, int length);
 
-    /** Determine if a new button press event occured
-     *  Upon calling the state is cleared until another press is detected
-     *  @return 1 if a press has been detected since the last call, 0 otherwise
-     */
-    uint32_t isPressed(void);
-
-    /** Get the electrode status (ELE12 ... ELE0 -> b15 xxx b11 ... b0
-     *  The buttons are bit mapped. ELE0 = b0 ... ELE11 = b11 b12 ... b15 undefined
-     *  @return The state of all buttons
-     */
-    uint16_t buttonPressed(void);
+    /**
+      * Issues a read of a given address, and returns the value.
+      *
+      * Blocks the calling thread until complete.
+      *
+      * @param reg The address of the 16 bit register to access.
+      *
+      * @return The register value, interpreted as a 16 but signed value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
+      */
+    int read16(uint8_t reg);
 
-    /** print the register map and values to the console
-     */
-    void registerDump() const;
+    /**
+      * Issues a read of a given address, and returns the value.
+      *
+      * Blocks the calling thread until complete.
+      *
+      * @param reg The address of the 16 bit register to access.
+      *
+      * @return The register value, interpreted as a 8 bit unsigned value, or MICROBIT_I2C_ERROR if the magnetometer could not be accessed.
+      */
+    int read8(uint8_t reg);
 
-    /** Write to a register (exposed for debugging reasons)
-     *  Note: most writes are only valid in stop mode
-     *  @param reg - The register to be written
-     *  @param data - The data to be written
-     */
-    void write(MPR121_REGISTER const reg, uint8_t const data) const;
+    /**
+      * Calculates a tilt compensated bearing of the device, using the accelerometer.
+      */
+    int tiltCompensatedBearing();
 
-    /** Read from a register (exposed for debugging reasons)
-     *  @param reg - The register to read from
-     *  @return The register contents
-     */
-    uint8_t read(MPR121_REGISTER const reg) const;
+    /**
+      * Calculates a non-tilt compensated bearing of the device.
+      */
+    int basicBearing();
 
+    /**
+      * An initialisation member function used by the many constructors of MicroBitMpr121.
+      *
+      * @param id the unique identifier for this compass instance.
+      *
+      * @param address the base address of the magnetometer on the i2c bus.
+      */
+    void init(uint16_t id, uint16_t address);
 };
 
-#endif
-
+#endif
\ No newline at end of file