I2Cdevlib

I2C device library collection for AVR/Arduino or other C++-based MCUs

_Stub/_Stub.h
00001 // I2Cdev library collection - MYDEVSTUB I2C device class header file
00002 // Based on [Manufacturer Name] MYDEVSTUB datasheet, [datasheet date]
00003 // [current release date] by [Author Name] <[Author Email]>
00004 // Updates should (hopefully) always be available at https://github.com/jrowberg/i2cdevlib
00005 //
00006 // Changelog:
00007 //     [YYYY-mm-dd] - updated some broken thing
00008 //     [YYYY-mm-dd] - initial release
00009 
00010 /* ============================================
00011 I2Cdev device library code is placed under the MIT license
00012 Copyright (c) 2011 [Author Name], Jeff Rowberg
00013 
00014 Permission is hereby granted, free of charge, to any person obtaining a copy
00015 of this software and associated documentation files (the "Software"), to deal
00016 in the Software without restriction, including without limitation the rights
00017 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00018 copies of the Software, and to permit persons to whom the Software is
00019 furnished to do so, subject to the following conditions:
00020 
00021 The above copyright notice and this permission notice shall be included in
00022 all copies or substantial portions of the Software.
00023 
00024 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00025 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00026 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00027 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00028 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00029 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00030 THE SOFTWARE.
00031 ===============================================
00032 */
00033 
00034 #ifndef _MYDEVSTUB_H_
00035 #define _MYDEVSTUB_H_
00036 
00037 #include "I2Cdev.h"
00038 
00039 // ============================================================================
00040 // DEVICE LIBRARY CONVENTIONS:
00041 //
00042 // 1. The class name should be the same as the device model if at all possible.
00043 //    No spaces or hyphens, and ideally no underlines unless they're absolutely
00044 //    necessary for clarity. ALL CAPS for model numbers, or FirstInitial caps
00045 //    for full names. For example:
00046 //      - ADXL345
00047 //      - MPU6050
00048 //      - TCA6424A
00049 //      - PanelPilot
00050 //
00051 // 2. All #defines should use a device-specific prefix that is the same as the
00052 //    all-caps version of the class name ("MYDEVSTUB_" in this example).
00053 //
00054 // 3. All #defines should be ALL CAPS, no matter what. This makes them clearly
00055 //    distinctive from variables, classes, and functions.
00056 //
00057 // 4. Class methods and member variables should be named using camelCaps.
00058 //
00059 // 5. Every device class should contain an "initialize()" method which takes
00060 //    no parameters and resets any important settings back to a known state,
00061 //    ideally the defaults outlined in the datasheet. Some devices have a
00062 //    RESET command available, which may be suitable. Some devices may not
00063 //    require any specific initialization, but an empty method should be
00064 //    created for consistency anyway.
00065 //
00066 // 6. Every device class should contain a "testConnection()" method which
00067 //    returns TRUE if the device appears to be connected, or FALSE otherwise.
00068 //    If a known ID register or device code is available, check for that. Since
00069 //    such an ID register is not always available, at least check to make sure
00070 //    that an I2C read may be performed on a specific register and that data
00071 //    does actually come back (the I2Cdev class returns a "bytes read" value
00072 //    for all read operations).
00073 //
00074 // 7. All class methods should be documented with useful information in Doxygen
00075 //    format. You can take the info right out of the datasheet if you want to,
00076 //    since that's likely to be helpful. Writing your own info is fine as well.
00077 //    The goal is to have enough clear documentation right in the code that
00078 //    someone can determine how the device works by studying the code alone.
00079 //
00080 // ============================================================================
00081 
00082 // ----------------------------------------------------------------------------
00083 // STUB TODO:
00084 // List all possible device I2C addresses here, if they are predefined. Some
00085 // devices only have one possible address, in which case that one should be
00086 // defined as both [MYDEVSTUB]_ADDRESS and [MYDEVSTUB]_DEFAULT_ADDRESS for
00087 // consistency. The *_DEFAULT address will be used if a device object is
00088 // created without an address provided in the constructor. Note that I2C
00089 // devices conventionally use 7-bit addresses, so these will generally be
00090 // between 0x00 and 0x7F.
00091 // ----------------------------------------------------------------------------
00092 #define MYDEVSTUB_ADDRESS_AD0_LOW   0x20
00093 #define MYDEVSTUB_ADDRESS_AD0_HIGH  0x21
00094 #define MYDEVSTUB_DEFAULT_ADDRESS   0x20
00095 
00096 // ----------------------------------------------------------------------------
00097 // STUB TODO:
00098 // List all registers that this device has. The goal for all device libraries
00099 // is to have complete coverage of all possible functions, so be sure to add
00100 // everything in the datasheet. Register address constants should use the extra
00101 // prefix "RA_", followed by the datasheet's given name for each register.
00102 // ----------------------------------------------------------------------------
00103 #define MYDEVSTUB_RA_MEASURE1       0x00
00104 #define MYDEVSTUB_RA_MEASURE2       0x01
00105 #define MYDEVSTUB_RA_MEASURE3       0x02
00106 #define MYDEVSTUB_RA_CONFIG1        0x03
00107 #define MYDEVSTUB_RA_CONFIG2        0x04
00108 #define MYDEVSTUB_RA_DATA_H         0x05
00109 #define MYDEVSTUB_RA_DATA_L         0x06
00110 #define MYDEVSTUB_RA_WHO_AM_I       0x07
00111 
00112 // ----------------------------------------------------------------------------
00113 // STUB TODO:
00114 // List register structures wherever necessary. Bit position constants should
00115 // end in "_BIT", and are defined from 7 to 0, with 7 being the left/MSB and
00116 // 0 being the right/LSB. If the device uses 16-bit registers instead of the
00117 // more common 8-bit registers, the range is 15 to 0. Field length constants
00118 // should end in "_LENGTH", but otherwise match the name of bit position
00119 // constant that it complements. Fields that are a single bit in length don't
00120 // need a separate field length constant.
00121 // ----------------------------------------------------------------------------
00122 #define MYDEVSTUB_MEASURE1_RATE_BIT     4
00123 #define MYDEVSTUB_MEASURE1_RATE_LENGTH  3
00124 
00125 #define MYDEVSTUB_CONFIG1_FIFO_BIT      1
00126 #define MYDEVSTUB_CONFIG1_RESET_BIT     0
00127 
00128 // ----------------------------------------------------------------------------
00129 // STUB TODO:
00130 // List any special predefined values for each register according to the
00131 // datasheet. For example, MEMS devices often provide different options for
00132 // measurement rates, say 25Hz, 50Hz, 100Hz, and 200Hz. These are typically
00133 // represented by arbitrary bit values, say 0b00, 0b01, 0b10, and 0b11 (or 0x0,
00134 // 0x1, 0x2, and 0x3). Defining them here makes it easy to know which options
00135 // are available.
00136 // ----------------------------------------------------------------------------
00137 #define MYDEVSTUB_RATE_10           0x00
00138 #define MYDEVSTUB_RATE_20           0x01
00139 #define MYDEVSTUB_RATE_40           0x02
00140 #define MYDEVSTUB_RATE_80           0x03
00141 #define MYDEVSTUB_RATE_160          0x04
00142 
00143 class MYDEVSTUB {
00144     public:
00145         MYDEVSTUB();
00146         MYDEVSTUB(uint8_t address);
00147 
00148         void initialize();
00149         bool testConnection();
00150 
00151 // ----------------------------------------------------------------------------
00152 // STUB TODO:
00153 // Declare methods to fully cover all available functionality provided by the
00154 // device, according to the datasheet and/or register map. Unless there is very
00155 // clear reason not to, try to follow the get/set naming convention for all
00156 // values, for instance:
00157 //   - uint8_t getThreshold()
00158 //   - void setThreshold(uint8_t threshold)
00159 //   - uint8_t getRate()
00160 //   - void setRate(uint8_t rate)
00161 //
00162 // Some methods may be named differently if it makes sense. As long as all
00163 // functionality is covered, that's the important part. The methods here are
00164 // only examples and should not be kept for your real device.
00165 // ----------------------------------------------------------------------------
00166 
00167         // MEASURE1 register, read-only
00168         uint8_t getMeasurement1();
00169 
00170         // MEASURE2 register, read-only
00171         uint8_t getMeasurement2();
00172 
00173         // MEASURE3 register, read-only
00174         uint8_t getMeasurement3();
00175 
00176         // CONFIG1 register, r/w
00177         void reset();               // <-- special method that resets entire device
00178         bool getFIFOEnabled();
00179         void setFIFOEnabled(bool enabled);
00180 
00181         // CONFIG2 register, r/w
00182         uint8_t getInterruptMode();
00183         void setInterruptMode(uint8_t mode);
00184         uint8_t getRate();
00185         void setRate(uint8_t rate);
00186 
00187         // DATA_* registers, r/w
00188         uint16_t getData();
00189         void setData(uint16_t value);
00190 
00191         // WHO_AM_I register, read-only
00192         uint8_t getDeviceID();
00193 
00194 // ----------------------------------------------------------------------------
00195 // STUB TODO:
00196 // Declare private object helper variables or local storage for particular
00197 // device settings, if required. All devices need a "devAddr" variable to store
00198 // the I2C slave address for easy access. Most devices also need a buffer for
00199 // reads (the I2Cdev class' read methods use a pointer for the storage location
00200 // of any read data). The buffer should be of type "uint8_t" if the device uses
00201 // 8-bit registers, or type "uint16_t" if the device uses 16-bit registers.
00202 // Many devices will not require more member variables than this.
00203 // ----------------------------------------------------------------------------
00204     private:
00205         uint8_t devAddr;
00206         uint8_t buffer[6];
00207 };
00208 
00209 #endif /* _MYDEVSTUB_H_ */
 All Data Structures Functions Variables