Rob Meades
A simple CIoT message protocol, used in the Water Meter Demos.
Embed:
(wiki syntax)
Show/hide line numbers
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
Generated on Sun Jul 17 2022 00:13:12 by
1.7.2