IotMeterApi.hpp

00001 /* C027N/water-meter interface definition 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 IOT_METER_API_HPP
00014 #define IOT_METER_API_HPP
00015 
00016 /**
00017  * @file iot_meter_api.h
00018  * This file defines the API to the C027N/water-meter device
00019  * for the MWC demo 2015.
00020  */
00021 
00022 #include <IotMeterMsgs.hpp>
00023 
00024 // ----------------------------------------------------------------
00025 // HARDWARE
00026 // The code in this library is setup to expect a Water Pump Relay,
00027 // a Crydom D2425, to be connected through this circuit:
00028 //
00029 // C027N board                     D2425 (Water Pump Relay)
00030 //
00031 //    5V   o------------o 
00032 //                      | 
00033 //                     | |
00034 //                     | |  180 Ohm
00035 //                     | |
00036 //                      |
00037 //                      o--------------o '+3' pin
00038 //            10k Ohm   |
00039 //              ___    / 
00040 //     D7   o--|___|--| (transistor)
00041 //                    _\/
00042 //                      |
00043 //                      |
00044 //                      |
00045 //    Gnd   o-----------o--------------o '4' pin
00046 //                      
00047 // ----------------------------------------------------------------
00048 
00049 // ----------------------------------------------------------------
00050 // GENERAL COMPILE-TIME CONSTANTS
00051 // ----------------------------------------------------------------
00052 
00053 /// The maximum length of a raw datagram in bytes
00054 #define MAX_DATAGRAM_SIZE_RAW 20
00055 
00056 // The GPIO that the water pump is connected to on the C027N board
00057 #define GPIO_WATER_PUMP 7
00058 
00059 // ----------------------------------------------------------------
00060 // CLASSES
00061 // ----------------------------------------------------------------
00062 
00063 class MessageCodec {
00064 public:
00065 
00066     // ----------------------------------------------------------------
00067     // MESSAGE ENCODING FUNCTIONS
00068     // ----------------------------------------------------------------
00069 
00070     /// Encode an uplink message that is sent at power-on of the
00071     // device.  Indicates that the device has been initialised.  After
00072     // transmission of this message meter readings will be returned
00073     // at the indicated rate.
00074     // \param pBuffer  A pointer to the buffer to encode into.  The
00075     // buffer length must be at least MAX_MESSAGE_SIZE long
00076     // \param pMsg  A pointer to the message to send.
00077     // \return  The number of bytes encoded.
00078     uint32_t encodeInitIndUlMsg (char * pBuffer,
00079                                  InitIndUlMsg_t * pMsg);
00080 
00081     /// Encode a downlink message that reboots the device.
00082     // \param pBuffer  A pointer to the buffer to encode into.  The
00083     // buffer length must be at least MAX_MESSAGE_SIZE long
00084     // \param pMsg  A pointer to the message to send.
00085     // \return  The number of bytes encoded.
00086     uint32_t encodeRebootReqDlMsg (char * pBuffer,
00087                                    RebootReqDlMsg_t *pMsg);
00088 
00089     /// Encode an uplink message containing the current meter reading.
00090     // \param pBuffer  A pointer to the buffer to encode into.  The
00091     // buffer length must be at least MAX_MESSAGE_SIZE long
00092     // \param pMsg  A pointer to the message to send.
00093     // \return  The number of bytes encoded.
00094     uint32_t encodeVolumeIndUlMsg (char * pBuffer,
00095                                    VolumeIndUlMsg_t * pMsg);
00096 
00097     /// Encode an uplink message containing the current RSSI reading.
00098     // \param pBuffer  A pointer to the buffer to encode into.  The
00099     // buffer length must be at least MAX_MESSAGE_SIZE long
00100     // \param pMsg  A pointer to the message to send.
00101     // \return  The number of bytes encoded.
00102     uint32_t encodeRssiIndUlMsg (char * pBuffer,
00103                                  RssiIndUlMsg_t * pMsg);
00104 
00105     /// Encode a downlink message that sets the reading interval
00106     // of the water meter.
00107     // \param pBuffer  A pointer to the buffer to encode into.  The
00108     // buffer length must be at least MAX_MESSAGE_SIZE long
00109     // \return  The number of bytes encoded.
00110     uint32_t encodeSerialNumberGetReqDlMsg (char * pBuffer);
00111 
00112     /// Encode an uplink message that is sent as a response to a
00113     // SerialNumberGetReqDlMsg.
00114     // \param pBuffer  A pointer to the buffer to encode into.  The
00115     // buffer length must be at least MAX_MESSAGE_SIZE long
00116     // \param pMsg  A pointer to the message to send.
00117     // \return  The number of bytes encoded.
00118     uint32_t encodeSerialNumberGetCnfUlMsg (char * pBuffer,
00119                                             SerialNumberGetCnfUlMsg_t * pMsg);
00120 
00121     /// Encode an uplink message that is sent at power-on of the
00122     // device and in response to an InitReqDlMsg.  Indicates the
00123     // serial number of the device.
00124     // \param pBuffer  A pointer to the buffer to encode into.  The
00125     // buffer length must be at least MAX_MESSAGE_SIZE long
00126     // \param pMsg  A pointer to the message to send.
00127     // \return  The number of bytes encoded.
00128     uint32_t encodeSerialNumberIndUlMsg (char * pBuffer,
00129                                          SerialNumberIndUlMsg_t * pMsg);
00130 
00131     /// Encode a downlink message that retrieves the reading interval.
00132     // \param pBuffer  A pointer to the buffer to encode into.  The
00133     // buffer length must be at least MAX_MESSAGE_SIZE long
00134     // \param pMsg  A pointer to the message to send.
00135     // \return  The number of bytes encoded.
00136     uint32_t encodeReadingIntervalGetReqDlMsg (char * pBuffer);
00137 
00138     /// Encode an uplink message that is sent as a response to a
00139     // ReadingIntervalGetReqDlMsg.
00140     // \param pBuffer  A pointer to the buffer to encode into.  The
00141     // buffer length must be at least MAX_MESSAGE_SIZE long
00142     // \param pMsg  A pointer to the message to send.
00143     // \return  The number of bytes encoded.
00144     uint32_t encodeReadingIntervalGetCnfUlMsg (char * pBuffer,
00145                                                ReadingIntervalGetCnfUlMsg_t * pMsg);
00146 
00147     /// Encode a downlink message that sets the reading interval.
00148     // \param pBuffer  A pointer to the buffer to encode into.  The
00149     // buffer length must be at least MAX_MESSAGE_SIZE long
00150     // \return  The number of bytes encoded.
00151     uint32_t encodeReadingIntervalSetReqDlMsg (char * pBuffer,
00152                                                ReadingIntervalSetReqDlMsg_t * pMsg);
00153 
00154     /// Encode an uplink message that is sent as a response to a
00155     // ReadingIntervalSetReqDlMsg.
00156     // \param pBuffer  A pointer to the buffer to encode into.  The
00157     // buffer length must be at least MAX_MESSAGE_SIZE long
00158     // \param pMsg  A pointer to the message to send.
00159     // \return  The number of bytes encoded.
00160     uint32_t encodeReadingIntervalSetCnfUlMsg (char * pBuffer,
00161                                                ReadingIntervalSetCnfUlMsg_t * pMsg);
00162 
00163     /// Encode a downlink message that gets the state of a GPIO
00164     // on the C027N board.
00165     // \param pBuffer  A pointer to the buffer to encode into.  The
00166     // buffer length must be at least MAX_MESSAGE_SIZE long
00167     // \return  The number of bytes encoded.
00168     uint32_t encodeGpioGetReqDlMsg (char * pBuffer,
00169                                     GpioGetReqDlMsg_t *pMsg);
00170 
00171     /// Encode an uplink message that is sent as a response to a
00172     // GpioGetReqDlMsg.
00173     // \param pBuffer  A pointer to the buffer to encode into.  The
00174     // buffer length must be at least MAX_MESSAGE_SIZE long
00175     // \param pMsg  A pointer to the message to send.
00176     // \return  The number of bytes encoded.
00177     uint32_t encodeGpioGetCnfUlMsg (char * pBuffer,
00178                                     GpioGetCnfUlMsg_t * pMsg);
00179 
00180     /// Encode a downlink message that sets the state of a GPIO
00181     // on the C027N board.
00182     // \param pBuffer  A pointer to the buffer to encode into.  The
00183     // buffer length must be at least MAX_MESSAGE_SIZE long
00184     // \param pMsg  A pointer to the message to send.
00185     // \return  The number of bytes encoded.
00186     uint32_t encodeGpioSetReqDlMsg (char * pBuffer,
00187                                     GpioSetReqDlMsg_t * pMsg);
00188 
00189     /// Encode an uplink message that is sent as a response to a
00190     // GpioSetReqDlMsg.
00191     // \param pBuffer  A pointer to the buffer to encode into.  The
00192     // buffer length must be at least MAX_MESSAGE_SIZE long
00193     // \param pMsg  A pointer to the message to send.
00194     // \return  The number of bytes encoded.
00195     uint32_t encodeGpioSetCnfUlMsg (char * pBuffer,
00196                                     GpioSetCnfUlMsg_t * pMsg);
00197 
00198     /// Encode a downlink message that gets the steady state of the
00199     // red LED on the C027N board.
00200     // \param pBuffer  A pointer to the buffer to encode into.  The
00201     // buffer length must be at least MAX_MESSAGE_SIZE long
00202     // \return  The number of bytes encoded.
00203     uint32_t encodeLedGetReqDlMsg (char * pBuffer);
00204 
00205     /// Encode an uplink message that is sent as a response to an
00206     // LedGetReqDlMsg.
00207     // \param pBuffer  A pointer to the buffer to encode into.  The
00208     // buffer length must be at least MAX_MESSAGE_SIZE long
00209     // \param pMsg  A pointer to the message to send.
00210     // \return  The number of bytes encoded.
00211     uint32_t encodeLedGetCnfUlMsg (char * pBuffer,
00212                                    LedGetCnfUlMsg_t * pMsg);
00213 
00214     /// Encode a downlink message that sets the steady state of
00215     // the red LED.
00216     // \param pBuffer  A pointer to the buffer to encode into.  The
00217     // buffer length must be at least MAX_MESSAGE_SIZE long
00218     // \param pMsg  A pointer to the message to send.
00219     // \return  The number of bytes encoded.
00220     uint32_t encodeLedSetReqDlMsg (char * pBuffer,
00221                                    LedSetReqDlMsg_t * pMsg);
00222 
00223     /// Encode an uplink message that is sent as a response to an
00224     // LedSetReqDlMsg.
00225     // \param pBuffer  A pointer to the buffer to encode into.  The
00226     // buffer length must be at least MAX_MESSAGE_SIZE long
00227     // \param pMsg  A pointer to the message to send.
00228     // \return  The number of bytes encoded.
00229     uint32_t encodeLedSetCnfUlMsg (char * pBuffer,
00230                                    LedSetCnfUlMsg_t * pMsg);
00231 
00232     /// Encode a downlink message that sets the red LED to flash when
00233     // a message is being sent/received (or not).  If LedSetReqDlMsg
00234     // has set the LED to ON the flash will be 'inverted', i.e. the
00235     // red LED will blink off when a message is being transmitted
00236     // or received instead.
00237     // \param pBuffer  A pointer to the buffer to encode into.  The
00238     // buffer length must be at least MAX_MESSAGE_SIZE long
00239     // \param pMsg  A pointer to the message to send.
00240     // \return  The number of bytes encoded.
00241     uint32_t encodeFlashSetReqDlMsg (char * pBuffer,
00242                                      FlashSetReqDlMsg_t * pMsg);
00243 
00244     /// Encode an uplink message that is sent as a response to a
00245     // FlashSetReqDlMsg.
00246     // \param pBuffer  A pointer to the buffer to encode into.  The
00247     // buffer length must be at least MAX_MESSAGE_SIZE long
00248     // \param pMsg  A pointer to the message to send.
00249     // \return  The number of bytes encoded.
00250     uint32_t encodeFlashSetCnfUlMsg (char * pBuffer,
00251                                      FlashSetCnfUlMsg_t * pMsg);
00252 
00253     /// Encode a downlink message that gets the red LED to flash when
00254     // a message is being sent/received (or not).  If LedSetReqDlMsg
00255     // has set the LED to ON the flash will be 'inverted', i.e. the
00256     // red LED will blink off when a message is being transmitted
00257     // or received instead.
00258     // \param pBuffer  A pointer to the buffer to encode into.  The
00259     // buffer length must be at least MAX_MESSAGE_SIZE long
00260     // \param pMsg  A pointer to the message to send.
00261     // \return  The number of bytes encoded.
00262     uint32_t encodeFlashGetReqDlMsg (char * pBuffer);
00263 
00264     /// Encode an uplink message that is sent as a response to a
00265     // FlashGetReqDlMsg.
00266     // \param pBuffer  A pointer to the buffer to encode into.  The
00267     // buffer length must be at least MAX_MESSAGE_SIZE long
00268     // \param pMsg  A pointer to the message to send.
00269     // \return  The number of bytes encoded.
00270     uint32_t encodeFlashGetCnfUlMsg (char * pBuffer,
00271                                      FlashGetCnfUlMsg_t * pMsg);
00272 
00273     // ----------------------------------------------------------------
00274     // MESSAGE DECODING FUNCTIONS
00275     // ----------------------------------------------------------------
00276 
00277     /// The outcome of message decoding.
00278     //
00279     // !!! When you add anything to the generic of UL sections
00280     // here (but not the DL bits as C# never decodes a DL thing),
00281     // align it with the DLL exported version in the dll wrapper files
00282     // so that the C# application can decode it.
00283     typedef enum DecodeResultTag_t
00284     {
00285       DECODE_RESULT_FAILURE = 0,         //!< Generic failed decode.
00286       DECODE_RESULT_INPUT_TOO_SHORT,     //!< Not enough input bytes.
00287       DECODE_RESULT_OUTPUT_TOO_SHORT,    //!< Not enough room in the
00288                                          //! output.
00289       DECODE_RESULT_UNKNOWN_MSG_ID,      //!< Rogue message ID.
00290       DECODE_RESULT_DL_MSG_BASE = 0x40,  //!< From here on are the
00291                                          //! downlink messages.
00292                                          // !!! If you add one here
00293                                          // update the next line !!!
00294       DECODE_RESULT_REBOOT_REQ_DL_MSG = DECODE_RESULT_DL_MSG_BASE,
00295       DECODE_RESULT_SERIAL_NUMBER_GET_REQ_DL_MSG,
00296       DECODE_RESULT_READING_INTERVAL_SET_REQ_DL_MSG,
00297       DECODE_RESULT_READING_INTERVAL_GET_REQ_DL_MSG,
00298       DECODE_RESULT_GPIO_SET_REQ_DL_MSG,
00299       DECODE_RESULT_GPIO_GET_REQ_DL_MSG,
00300       DECODE_RESULT_LED_SET_REQ_DL_MSG,
00301       DECODE_RESULT_LED_GET_REQ_DL_MSG,
00302       DECODE_RESULT_FLASH_SET_REQ_DL_MSG,
00303       DECODE_RESULT_FLASH_GET_REQ_DL_MSG,  // !!! If you add one here
00304                                            // update the next line !!!
00305       MAX_DL_REQ_MSG = DECODE_RESULT_FLASH_GET_REQ_DL_MSG,
00306       DECODE_RESULT_UL_MSG_BASE = 0x80, //!< From here on are the
00307                                         //! uplink messages.
00308       DECODE_RESULT_INIT_IND_UL_MSG = DECODE_RESULT_UL_MSG_BASE,
00309       DECODE_RESULT_SERIAL_NUMBER_IND_UL_MSG,
00310       DECODE_RESULT_SERIAL_NUMBER_GET_CNF_UL_MSG,
00311       DECODE_RESULT_VOLUME_IND_UL_MSG,
00312       DECODE_RESULT_RSSI_IND_UL_MSG,
00313       DECODE_RESULT_READING_INTERVAL_SET_CNF_UL_MSG,
00314       DECODE_RESULT_READING_INTERVAL_GET_CNF_UL_MSG,
00315       DECODE_RESULT_GPIO_SET_CNF_UL_MSG,
00316       DECODE_RESULT_GPIO_GET_CNF_UL_MSG,
00317       DECODE_RESULT_LED_SET_CNF_UL_MSG,
00318       DECODE_RESULT_LED_GET_CNF_UL_MSG,
00319       DECODE_RESULT_FLASH_SET_CNF_UL_MSG,
00320       DECODE_RESULT_FLASH_GET_CNF_UL_MSG,  // !!! If you add one here update
00321                                              // the next line !!!
00322       MAX_UL_REQ_MSG = DECODE_RESULT_FLASH_GET_CNF_UL_MSG,
00323       MAX_NUM_DECODE_RESULTS             //!< The maximum number of
00324                                          //! decode results.
00325     } DecodeResult_t;
00326 
00327     /// Decode a downlink message. When a datagram has been received
00328     // this function should be called iteratively to decode all the
00329     // messages contained within it.  The result, in pOutputBuffer,
00330     // should be cast by the calling function to DlMsgUnion_t and
00331     // the relevant member selected according to the
00332     // DecodeResult_t code.
00333     // \param ppInBuffer  A pointer to the pointer to decode from.
00334     // On completion this is pointing to the next byte that
00335     // could be decoded, after the currently decoded message,
00336     // in the buffer.
00337     // \param sizeInBuffer  The number of bytes left to decode.
00338     // \param pOutBuffer  A pointer to the buffer to write the
00339     // result into.
00340     // \param pBytesDecoded A pointer to a place to write the number
00341     // of bytes decoded.
00342     // \return  The result of the decoding, which hopefully says
00343     // what message has been decoded.
00344     DecodeResult_t decodeDlMsg (const char ** ppInBuffer,
00345                                 uint32_t sizeInBuffer,
00346                                 DlMsgUnion_t * pOutBuffer);
00347 
00348     /// Decode an uplink message. When a datagram has been received
00349     // this function should be called iteratively to decode all the
00350     // messages contained within it.  The result, in pOutputBuffer,
00351     // should be cast by the calling function to UlMsgUnion_t and
00352     // the relevant member selected according to the
00353     // DecodeResult_t code.
00354     // \param ppInBuffer  A pointer to the pointer to decode from.
00355     // On completion this is pointing to the next byte that
00356     // could be decoded, after the currently decoded message,
00357     // in the buffer.
00358     // \param sizeInBuffer  The number of bytes left to decode.
00359     // \param pOutBuffer  A pointer to the buffer to write the
00360     // result into.
00361     // \return  The result of the decoding, which hopefully says
00362     // what message has been decoded.
00363     DecodeResult_t decodeUlMsg (const char ** ppInBuffer,
00364                                 uint32_t sizeInBuffer,
00365                                 UlMsgUnion_t * pOutBuffer);
00366 
00367     // ----------------------------------------------------------------
00368     // MISC FUNCTIONS
00369     // ----------------------------------------------------------------
00370 
00371     /// Only used in the DLL form, sets up the "printf()" function
00372     // for logging.
00373     // \param guiPrintToConsole  the printf function.
00374     void initDll (void (*guiPrintToConsole) (const char *));
00375 
00376     /// User callback function for "printf()" logging.  
00377     static void (*mp_guiPrintToConsole) (const char *);
00378 
00379 private:
00380     /// Encode a boolean value.
00381     // \param pBuffer  A pointer to where the encoded
00382     // value should be placed.
00383     // \param value The Boolean value.
00384     // \return  The number of bytes encoded.
00385     uint32_t encodeBool (char * pBuffer, bool value);
00386     /// Decode a Boolean value.
00387     // \param ppBuffer  A pointer to the pointer to decode.
00388     // On completion this points to the location after the
00389     // bool in the input buffer.
00390     // \return  The decoded value.
00391     bool decodeBool (const char ** ppBuffer);
00392     /// Encode a uint32_t value.
00393     // \param pBuffer  A pointer to the value to decode.
00394     // \param value The value.
00395     // \return  The number of bytes encoded.
00396     uint32_t encodeUint32 (char * pBuffer, uint32_t value);
00397     /// Decode a uint32_t value.
00398     // \param ppBuffer  A pointer to the pointer to decode.
00399     // On completion this points to the location after the
00400     // uint32 in the input buffer.
00401     uint32_t decodeUint32 (const char ** ppBuffer);
00402     /// Encode GpioState.
00403     // \param pBuffer  A pointer to the value to decode.
00404     // \param gGpioState A pointer to the place to put the
00405     // GPIO Sate.
00406     // \return  The number of bytes encoded.
00407     uint32_t encodeGpioState (char * pBuffer, GpioState_t *pGpioState);
00408     /// Decode Gpio_State_t.
00409     // \param gGpioState_t a pointer to a place to put the
00410     // decoded GPIO state.
00411     // \param ppBuffer  A pointer to the pointer to decode.
00412     // On completion this points to the location after the
00413     // uint32 in the input buffer.
00414     void decodeGpioState (GpioState_t * pGpioState,
00415                           const char ** ppBuffer);
00416     /// Log a message for debugging, "printf()" style.
00417     // \param pFormat The printf() stle parameters.
00418     void logMsg (const char * pFormat, ...);
00419 };
00420 
00421 #endif
00422 
00423 // End Of File