MicroBitValue.cpp

00001 /*
00002 The MIT License (MIT)
00003 
00004 Copyright (c) 2016 British Broadcasting Corporation.
00005 This software is provided by Lancaster University by arrangement with the BBC.
00006 
00007 Permission is hereby granted, free of charge, to any person obtaining a
00008 copy of this software and associated documentation files (the "Software"),
00009 to deal in the Software without restriction, including without limitation
00010 the rights to use, copy, modify, merge, publish, distribute, sublicense,
00011 and/or sell copies of the Software, and to permit persons to whom the
00012 Software is furnished to do so, subject to the following conditions:
00013 
00014 The above copyright notice and this permission notice shall be included in
00015 all copies or substantial portions of the Software.
00016 
00017 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00018 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00019 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
00020 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00021 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00022 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
00023 DEALINGS IN THE SOFTWARE.
00024 */
00025 
00026 /**
00027   * Class definition for MicroBit Value.
00028   *
00029   * Represents an implementation of the Freescale MAG3110 I2C Magnetmometer.
00030   * Also includes basic caching.
00031   */
00032 #include "MicroBitConfig.h"
00033 #include "MicroBitValue.h"
00034 #include "MicroBitFiber.h"
00035 #include "ErrorNo.h"
00036 
00037 /**
00038   * An initialisation member function used by the many constructors of MicroBitValue.
00039   *
00040   * @param id the unique identifier for this value instance.
00041   *
00042   */
00043 void MicroBitValue::init(uint16_t id)
00044 {
00045     this->id = id;
00046 
00047     if(this->storage != NULL)
00048     {
00049         /*
00050         KeyValuePair *calibrationData =  storage->get("compassCal");
00051 
00052         if(calibrationData != NULL)
00053         {
00054             CompassSample storedSample = CompassSample();
00055 
00056             memcpy(&storedSample, calibrationData->value, sizeof(CompassSample));
00057 
00058             setCalibration(storedSample);
00059 
00060             delete calibrationData;
00061         }
00062         */
00063     }
00064 
00065     // Indicate that we're up and running.
00066     status |= MICROBIT_COMPONENT_RUNNING;
00067 }
00068 
00069 
00070 
00071 /**
00072   * Constructor.
00073   * Create a software representation of an e-compass.
00074   *
00075   * @param _i2c an instance of i2c, which the compass is accessible from.
00076   *
00077   * @param _storage an instance of MicroBitStorage, used to persist calibration data across resets.
00078   *
00079   * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
00080   *
00081   * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
00082   *
00083   * @code
00084   * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
00085   *
00086   * MicroBitStorage storage;
00087   *
00088   * MicroBitCompass compass(i2c, storage);
00089   * @endcode
00090   */
00091 MicroBitValue::MicroBitValue(MicroBitStorage& _storage, uint16_t id) :
00092     sample(),
00093     storage(&_storage)
00094 {
00095     init(id);
00096 }
00097 
00098 /**
00099   * Constructor.
00100   * Create a software representation of an e-compass.
00101   *
00102   * @param _i2c an instance of i2c, which the compass is accessible from.
00103   *
00104   * @param address the default address for the compass register on the i2c bus. Defaults to MAG3110_DEFAULT_ADDR.
00105   *
00106   * @param id the ID of the new MicroBitCompass object. Defaults to MAG3110_DEFAULT_ADDR.
00107   *
00108   * @code
00109   * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
00110   *
00111   * MicroBitCompass compass(i2c);
00112   * @endcode
00113   */
00114 MicroBitValue::MicroBitValue(uint16_t id) :
00115     sample(),
00116     storage(NULL)
00117 {
00118     init(id);
00119 }
00120 
00121 /**
00122   * Updates the local sample, only if the compass indicates that
00123   * data is stale.
00124   *
00125   * @note Can be used to trigger manual updates, if the device is running without a scheduler.
00126   *       Also called internally by all get[X,Y,Z]() member functions.
00127   */
00128 int MicroBitValue::updateSample()
00129 {
00130     /**
00131       * Adds the compass to idle, if it hasn't been added already.
00132       * This is an optimisation so that the compass is only added on first 'use'.
00133       */
00134     if(!(status & 0x01))
00135     {
00136         fiber_add_idle_component(this);
00137         status |= 0x01;
00138     }
00139 
00140     return MICROBIT_OK;
00141 }
00142 
00143 /**
00144   * Periodic callback from MicroBit idle thread.
00145   *
00146   * Calls updateSample().
00147   */
00148 void MicroBitValue::idleTick()
00149 {
00150     updateSample();
00151 }
00152 
00153 /**
00154   * Attempts to set the sample rate of the compass to the specified value (in ms).
00155   *
00156   * @param period the requested time between samples, in milliseconds.
00157   *
00158   * @return MICROBIT_OK or MICROBIT_I2C_ERROR if the magnetometer could not be updated.
00159   *
00160   * @code
00161   * // sample rate is now 20 ms.
00162   * compass.setPeriod(20);
00163   * @endcode
00164   *
00165   * @note The requested rate may not be possible on the hardware. In this case, the
00166   * nearest lower rate is chosen.
00167   */
00168 void MicroBitValue::setV(int v)
00169 {
00170     this->sample.v = v;
00171 }
00172 
00173 /**
00174   * Reads the currently configured sample rate of the compass.
00175   *
00176   * @return The time between samples, in milliseconds.
00177   */
00178 int MicroBitValue::getV()
00179 {
00180     return (int)sample.v;
00181 }
00182 /**
00183   * Destructor for MicroBitCompass, where we deregister this instance from the array of fiber components.
00184   */
00185 MicroBitValue::~MicroBitValue()
00186 {
00187     fiber_remove_idle_component(this);
00188 }