WaterMeterApi.hpp

00001 /* Water Meter HW driver for Water Meter Demo
00002  * 
00003  * Copyright (C) u-blox Melbourn Ltd
00004  * u-blox Melbourn Ltd, Melbourn, UK
00005  * 
00006  * All rights reserved.
00007  *
00008  * This source file is the sole property of u-blox Melbourn Ltd.
00009  * Reproduction or utilization of this source in whole or part is
00010  * forbidden without the written consent of u-blox Melbourn Ltd.
00011  */
00012 
00013 #ifndef WATER_METER_API_HPP
00014 #define WATER_METER_API_HPP
00015 
00016 /**
00017  * @file water_meter_api.h
00018  * This file defines the API to the water meter HW
00019  * for the MWC demo 2015.
00020  */
00021 
00022 // ----------------------------------------------------------------
00023 // HARDWARE
00024 // The code in this library is setup to expect a FlowIQ2100 water
00025 // meter to be connected through this circuit:
00026 //
00027 // C027N board                                       Water Meter
00028 //
00029 //    5V   o-------------------o-------------o------o Red (pwr/clk)
00030 //                             |             |
00031 //                             |             |
00032 //                             |             |
00033 //                             |             |
00034 //                             |             |
00035 //                             |             |
00036 //                             |             |
00037 //                            | |            |
00038 //                            | | 10k Ohm    |
00039 //                            | |            |
00040 //                             |             | 
00041 //              1k Ohm         o-------------|------o Black (gnd)
00042 //              ____          /              |
00043 //     D4   o--|____|--------| (transistor)  |  
00044 //                           _\/             |
00045 //                             |            | |
00046 //                             |            | | 10k Ohm
00047 //                             |            | |
00048 //                             |             |
00049 //     D2   o--------------------------------o------o Green (data)
00050 //                             |
00051 //                             |
00052 //    Gnd   o------------------o
00053 //                      
00054 // ----------------------------------------------------------------
00055 
00056 // ----------------------------------------------------------------
00057 // GENERAL COMPILE-TIME CONSTANTS
00058 // ----------------------------------------------------------------
00059 
00060 // ----------------------------------------------------------------
00061 // CLASSES
00062 // ----------------------------------------------------------------
00063 
00064 class WaterMeterHandler {
00065 public:
00066     /// Constructor.
00067     WaterMeterHandler (void);
00068     /// Destructor.
00069     ~WaterMeterHandler(void);
00070     /// Initialise the water meter, ensuring that there
00071     // is an electrical connection and that at least
00072     // a single character can be correctly received from
00073     // it (by checking parity).
00074     // \param data  pin to use for receiving data on the
00075     // C027N board.
00076     // \param pwrClk  pin to use to send pwr/clk on the
00077     // C027N board.
00078     // \param clkRateHz  the clock rate to use when
00079     // reading out data bits.
00080     // \return  true if successful, otherwise false.
00081     bool init (PinName dataPin = D2, PinName pwrClkPin = D4, uint32_t clkRateHz = 1000);
00082 
00083     /// Take a water volume reading from the meter.
00084     // \param  a pointer to somewhere to put the reading.
00085     // Only written-to if the outcome is true.  May be NULL,
00086     // in which case the success check is still carried out.
00087     // \\return  success if true, otherwise false.
00088     bool readLitres (uint32_t * pValue);
00089 
00090     /// Read the serial number from the meter.
00091     // \param  a pointer to somewhere to put the serial number.
00092     // Only written-to if the outcome is true.  May be NULL,
00093     // in which case the success check is still carried out.
00094     // \\return  success if true, otherwise false.
00095     bool readSerialNumber (uint32_t * pValue);
00096 
00097     /// Set debug to bool.
00098     // \param onNotOff debug will come out if this is true.
00099     // Default is no debug.
00100     void setDebugOn (bool onNotOff);
00101 
00102 private:
00103     /// Set this to true once initialised.
00104     bool ready;
00105     /// Set this to true for debug.
00106     bool debug;
00107     /// The pin on the C027N board to use for data reception
00108     // from the meter.
00109     DigitalIn *pData;
00110     /// The pin on the C027N board to use for pwr/clock to
00111     // the meter.
00112     DigitalOut *pPwrClk;
00113     /// The length of half a clock period in microseconds to
00114     // use when reading data off the water meter.
00115     uint32_t halfClkPeriodUs;
00116     /// Power on the meter (by toggling the pwrClk line until
00117     // the data line goes low).
00118     // \return  true if successful, otherwise false.
00119     bool pwrOn (void);
00120     /// Power off the meter (by setting the pwrClk line low).
00121     void pwrOff (void);
00122     /// Read a start bit from the meter.
00123     // \return true if successful, otherwise false.
00124     bool readStartBit (void);
00125     /// Read a stop bit from the meter.
00126     // \return true if successful, otherwise false.
00127     bool readStopBit (void);
00128     /// Toggle the pwrClk line to read a data bit from the water
00129     // meter.
00130     // \return true if a 1 is read, false if a 0 is read.
00131     bool readDataBit (void);
00132     /// Check that parity is good
00133     // \return  true if successful, otherwise false.
00134     bool parityIsGood (uint8_t numOnes);
00135     /// Read a character from the meter and check parity.
00136     // \param pChar  a pointer to a location where the received
00137     // character can be stored.  Only filled in if the read is
00138     // successful.  May be NULL, in which case the parity check
00139     // is still carried out.
00140     // \return  true if successful, otherwise false.
00141     bool readChar (char *pChar);
00142     /// Read a whole fixed-length message from the water meter.
00143     // Reading stops when a parity error occurs or when the
00144     // requested number of bytes has been read.
00145     // \param pChars  a pointer to a location where the received
00146     // data bytes can be stored.  Must be at least numBytes big.
00147     // \return  the number of bytes read.
00148     // \param numChars  the number of bytes to read.
00149     uint32_t readFixedLengthMsg (char *pChars, uint32_t numChars);
00150     /// Convert a number of characters representing a decimal
00151     // value into a uint32_t value.
00152     // Characters are assumed to be ASCII, single byte values.
00153     // If a non-numeric character (including a decimal point)
00154     // is found then fail is returned.
00155     // \param pChars  a pointer to the start of the character array.
00156     // \param numChars  the number of characters.
00157     // \param pValue  the uint32_t value, only written-to if
00158     // success is returned.  May be NULL in which case the success
00159     // check is still carried out.
00160     // \return true if successful, otherwise false.
00161     bool decCharsToUint32 (char * pChars, uint32_t numChars, uint32_t * pValue);
00162 };
00163 
00164 #endif
00165 
00166 // End Of File