MicroBitValue.h

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 #ifndef MICROBIT_VALUE_H
00027 #define MICROBIT_VALUE_H
00028 
00029 #include "mbed.h"
00030 #include "MicroBitConfig.h"
00031 #include "MicroBitComponent.h"
00032 #include "MicroBitStorage.h"
00033 
00034 /**
00035   * Value events
00036   */
00037 #define MICROBIT_VALUE_EVT_DATA_UPDATE          1
00038 
00039 struct ValueSample
00040 {
00041     int     v;
00042 
00043     ValueSample()
00044     {
00045         this->v = 0;
00046     }
00047 
00048     ValueSample(int v)
00049     {
00050         this->v = v;
00051     }
00052 
00053     bool operator==(const ValueSample& other) const
00054     {
00055         return v == other.v;
00056     }
00057 
00058     bool operator!=(const ValueSample& other) const
00059     {
00060         return !(v == other.v);
00061     }
00062 };
00063 
00064 /**
00065   * Class definition for MicroBit Value.
00066   *
00067   * Represents an implementation of shared value.
00068   * Also includes basic caching.
00069   */
00070 class MicroBitValue : public MicroBitComponent
00071 {
00072 
00073     ValueSample             sample;                   // The latest sample data recorded.
00074     MicroBitStorage*        storage;                  // An instance of MicroBitStorage used for persistence.
00075 
00076     public:
00077 
00078     /**
00079       * Constructor.
00080       * Create a software representation of an e-value.
00081       *
00082       *
00083       * @param _storage an instance of MicroBitStorage, used to persist calibration data across resets.
00084       *
00085       * @param id the ID of the new MicroBitCompass object. Defaults to MICROBIT_ID_VALUE.
00086       *
00087       * @code
00088       *
00089       * MicroBitStorage storage;
00090       *
00091       * MicroBitValue uBitValue(storage);
00092       * @endcode
00093       */
00094     MicroBitValue(MicroBitStorage& _storage, uint16_t id = MICROBIT_ID_VALUE);
00095 
00096     /**
00097       * Constructor.
00098       * Create a software representation of an e-value.
00099       *
00100       * @param id the ID of the new MicroBitCompass object. Defaults to MICROBIT_ID_VALUE.
00101       *
00102       * @code
00103       * MicroBitI2C i2c(I2C_SDA0, I2C_SCL0);
00104       *
00105       * MicroBitCompass compass(i2c);
00106       * @endcode
00107       */
00108     MicroBitValue(uint16_t id = MICROBIT_ID_VALUE);
00109 
00110     /**
00111       * Reads the value of the V integer.
00112       *
00113       * @return The value V.
00114       *
00115       * @code
00116       * value.getV();
00117       * @endcode
00118       */
00119     int getV();
00120 
00121     /**
00122       * Set the value of the V integer.
00123       *
00124       * @param The value V.
00125       *
00126       * @code
00127       * value.setV(v);
00128       * @endcode
00129       */
00130     void setV(int v);
00131 
00132     /**
00133       * Updates the local sample, only if the compass indicates that
00134       * data is stale.
00135       *
00136       * @note Can be used to trigger manual updates, if the device is running without a scheduler.
00137       *       Also called internally by getV() member functions.
00138       */
00139     int updateSample();
00140 
00141     /**
00142       * Periodic callback from MicroBit idle thread.
00143       *
00144       * Calls updateSample().
00145       */
00146     virtual void idleTick();
00147 
00148 
00149     /**
00150       * Destructor for MicroBitCompass, where we deregister this instance from the array of fiber components.
00151       */
00152     ~MicroBitValue();
00153 
00154     private:
00155 
00156     /**
00157       * An initialisation member function used by the many constructors of MicroBitValue.
00158       *
00159       * @param id the unique identifier for this value instance.
00160       *
00161       */
00162     void init(uint16_t id);
00163 };
00164 
00165 #endif