IotMeterMsgs.hpp

00001 /* C027N/water-meter message definitions 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_MSGS_HPP
00014 #define IOT_METER_MSGS_HPP
00015 
00016 /**
00017  * @file iot_meter_msgs.h
00018  * This file defines the messages sent between the
00019  * C027N/water-meter device and a PC app for the MWC demo
00020  * 2015.
00021  *
00022  * The message format is as follows:
00023  *
00024  * uint8_t   id
00025  * uint32_t  value
00026  *
00027  * The IDs are defined in an enumerated type and there are
00028  * separately defined ID sets for the downlink and uplink
00029  * directions (i.e. they may overlap).  When transmitted the
00030  * messages are packed such that the 32-bit content byte
00031  * immediately follows the 8-bit ID with no packing, resulting
00032  * in a fixed message length of 5 bytes.  Multiple fixed
00033  * length messages may be packed into a datagram, hence it can
00034  * be assumed that a datagram of length < 10 bytes contains
00035  * one message, a datagram of length < 15 bytes contains two
00036  * messages, etc.
00037  *
00038  * Boolean values are expressed as uint32_t zero (false) or
00039  * uint32_t one (true).  For multibyte values the highest
00040  * value bytes is stored first, so a message with ID 0xa5 and
00041  * value 0x12345678 would be stored in the datagram as:
00042  *
00043  * Location: 0 1 2 3 4
00044  * Contents: a512345678
00045  *
00046  * There are some messages (Gpio setters for instance) which
00047  * encode more than a single value into the value field.  See
00048  * the individual encode/decode functions for how these values
00049  * are packed.
00050  */
00051  
00052 // ----------------------------------------------------------------
00053 // GENERAL COMPILE-TIME CONSTANTS
00054 // ----------------------------------------------------------------
00055 
00056 /// The maximum length of a single messages in bytes
00057 #define MAX_MESSAGE_SIZE 5
00058  
00059 /// The default meter reading interval.
00060 #define DEFAULT_READING_INTERVAL_SECONDS 10
00061 
00062 
00063 // ----------------------------------------------------------------
00064 // TYPES
00065 // ----------------------------------------------------------------
00066 
00067 /// The wake up code sent from the device
00068 typedef enum WakeUpCodeTag_t
00069 {
00070     WAKE_UP_CODE_OK,                   //!< A good wake-up, no problems.
00071     WAKE_UP_CODE_WATER_METER_PROBLEM,  //!< Wake-up after assert due to
00072                                        //! problems reading the water meter.
00073     WAKE_UP_CODE_AT_COMMAND_PROBLEM,   //!< Wake-up after assert due to
00074                                        //! problems with AT commands.
00075     WAKE_UP_CODE_NETWORK_SEND_PROBLEM, //!< Wake-up after assert due to
00076                                        //! problems sending to the network.
00077     WAKE_UP_CODE_MEMORY_ALLOC_PROBLEM, //!< Wake-up after assert due to
00078                                        //! memory allocation issues.
00079     WAKE_UP_CODE_PROTOCOL_PROBLEM,     //!< Wake-up after assert due to
00080                                        //! a protocol problem.
00081     WAKE_UP_CODE_GENERIC_FAILURE,      //!< Wake-up after a generic failure.
00082     WAKE_UP_CODE_REBOOT,               //!< Waking up after a commanded reboot.
00083     MAX_NUM_WAKE_UP_CODES              //!< The maximum number of
00084                                        //! decode results.
00085 } WakeUpCode_t;
00086 
00087 // ----------------------------------------------------------------
00088 // MESSAGE BODIES
00089 // ----------------------------------------------------------------
00090  
00091 /// InitIndUlMsg_t. Sent at power-on of the device. Indicates that the
00092 // device has been initialised.
00093 // After transmission of this message meter readings will be returned
00094 // at the requested rate (or DEFAULT_READING_INTERVAL_SECONDS if no
00095 // InitReqDlMsg_t has been received by the device).
00096 typedef struct InitIndUlMsgTag_t
00097 {
00098     WakeUpCode_t wakeUpCode; //!< A wake-up code from the device.
00099 } InitIndUlMsg_t;
00100 
00101 /// RebootReqDlMsg_t. Sent to reboot the device and set the development
00102 // mode on or off.  By default development mode is OFF.
00103 typedef struct RebootReqDlMsgTag_t
00104 {
00105     bool devModeOnNotOff; //!< If true development mode is on, else it is off.
00106 } RebootReqDlMsg_t;
00107 
00108 /// SerialNumberGetCnfUlMsg_t. Sent in response to a SerialNumberGetReqDlMsg_t (which
00109 // is empty and so not represented here).
00110 typedef struct SerialNumberGetCnfUlMsgTag_t
00111 {
00112   uint32_t serialNumber; //!< The serial number of the meter.
00113 } SerialNumberGetCnfUlMsg_t;
00114 
00115 /// SerialNumberIndUlMsg_t. Sent at power-on of the device and in response to
00116 // an InitReqDlMsg_t. Indicates the serial number of the device.
00117 typedef struct SerialNumberIndUlMsgTag_t
00118 {
00119   uint32_t serialNumber; //!< The serial number of the meter.
00120 } SerialNumberIndUlMsg_t;
00121 
00122 /// VolumeIndUlMsg_t. The current meter reading.
00123 typedef struct VolumeIndUlMsgTag_t
00124 {
00125   uint32_t volumeLitres;
00126 } VolumeIndUlMsg_t;
00127 
00128 /// RssiIndUlMsg_t. The current RSSI reading.
00129 typedef struct RssiIndUlMsgTag_t
00130 {
00131   uint32_t rssi; //!< The RSSI reading in arbitrary units, range 0 to 255.
00132 } RssiIndUlMsg_t;
00133 
00134 /// ReadingIntervalSetReqDlMsg_t. Set the meter reading interval.
00135 typedef struct ReadingIntervalSetReqDlMsgTag_t
00136 {
00137   uint32_t readingIntervalSeconds; //!< The interval at which the device
00138                                    //! should send readings.
00139 } ReadingIntervalSetReqDlMsg_t;
00140 
00141 /// ReadingIntervalSetCnfUlMsg_t. Sent in response to a
00142 // ReadingIntervalSetReqDlMsg_t.
00143 // After transmission of this message meter readings will be returned
00144 // at the requested rate (or DEFAULT_READING_INTERVAL_SECONDS if no
00145 // command setting it otherwise has been received by the device).
00146 typedef struct ReadingIntervalSetCnfUlMsgTag_t
00147 {
00148   uint32_t readingIntervalSeconds; //!< The interval at which readings are sent.
00149 } ReadingIntervalSetCnfUlMsg_t;
00150 
00151 /// ReadingIntervalGetCnfUlMsg_t. Sent in response to a
00152 // ReadingIntervalGetReqDlMsg_t (which is empty and so not represented
00153 // here).
00154 // After transmission of this message meter readings will be returned
00155 // at the requested rate (or DEFAULT_READING_INTERVAL_SECONDS if no
00156 // command setting it otherwise has been received by the device).
00157 typedef struct ReadingIntervalGetCnfUlMsgTag_t
00158 {
00159     uint32_t readingIntervalSeconds; //!< The interval at which readings are sent.
00160 } ReadingIntervalGetCnfUlMsg_t;
00161 
00162 /// GpioState_t.  Data concerning how a GPIO is set up.
00163 typedef struct GpioStateTag_t
00164 {
00165     uint8_t gpio;        //!< The GPIO in question: 0 for D0, 1 for D1, etc.
00166     bool inputNotOutput; //!< true if this is an input, else it is an output.
00167     bool onNotOff;       //!< If the GPIO is an output then this gives its state.
00168                          //! If the GPIO is an input this is not set.
00169 } GpioState_t;
00170 
00171 /// GpioSetReqDlMsg_t. Set the state of a GPIO on the C027N board.
00172 typedef struct GpioSetReqDlMsgTag_t
00173 {
00174     GpioState_t gpioState; //!< The state of the GPIO.
00175 } GpioSetReqDlMsg_t;
00176 
00177 /// GpioSetCnfUlMsg_t.  Response to GpioSetReqDlMsg_t.
00178 typedef struct GpioSetCnfUlMsgTag_t
00179 {
00180     GpioState_t gpioState; //!< The state of the GPIO.
00181 } GpioSetCnfUlMsg_t;
00182 
00183 /// GpioGetReqDlMsg_t. Gets the state of a GPIO on the C027N board.
00184 typedef struct GpioGetReqDlMsgTag_t
00185 {
00186     uint8_t gpio;        //!< The GPIO to get.
00187 } GpioGetReqDlMsg_t;
00188 
00189 /// GpioGetCnfUlMsg_t. Sent in response to a GpioGetReqDlMsg.
00190 typedef struct GpioGetCnfUlMsgTag_t
00191 {
00192     GpioState_t gpioState; //!< The state of the GPIO.
00193 } GpioGetCnfUlMsg_t;
00194 
00195 /// LedSetReqDlMsg_t. Set the steady state of the red LED on
00196 // the C027N board.
00197 typedef struct LedSetReqDlMsgTag_t
00198 {
00199     bool onNotOff; //!< Make the steady state ON if true, otherwise OFF.
00200                    //! OFF is the default state.
00201 } LedSetReqDlMsg_t;
00202 
00203 /// LedSetCnfUlMsg_t.  Response to LedSetReqDlMsg_t.
00204 typedef struct LedSetCnfUlMsgTag_t
00205 {
00206     bool onNotOff; //!< The LED is steady-state ON if true, otherwise
00207                    //! OFF.
00208 } LedSetCnfUlMsg_t;
00209 
00210 /// LedGetCnfUlMsg_t. Sent in response to an LedGetReqDlMsg
00211 // (which is an empty ID and so not represented here).
00212 typedef struct LedGetCnfUlMsgTag_t
00213 {
00214     bool onNotOff; //!< The steady state is ON if true, otherwise OFF.
00215 } LedGetCnfUlMsg_t;
00216 
00217 /// FlashSetReqDlMsg_t. Set the red LED to flash when a reading is
00218 // being sent (or not).  If LedSetReqDlMsg_t has been set to ON the
00219 // flash will be 'inverted', i.e. the red LED will blink off when a
00220 // reading is being transmitted instead.
00221 typedef struct FlashSetReqDlMsgTag_t
00222 {
00223     bool onNotOff; //!< If true then the red LED will flash when a
00224                    //! reading is being sent, else it will remain in
00225                    //! steady state. The default is to flash when a
00226                    //! reading is being sent.
00227 } FlashSetReqDlMsg_t;
00228 
00229 /**
00230  * FlashSetCnfUlMsg_t. Response to FlashSetReqDlMsg_t.
00231  */
00232 typedef struct FlashSetCnfUlMsgTag_t
00233 {
00234     bool onNotOff; //!< If true then the red LED flashes when a
00235                    //! reading is being sent, else it will remain in
00236                    //! steady state.
00237 } FlashSetCnfUlMsg_t;
00238 
00239 /// FlashGetCnfUlMsg_t. Sent in response to a FlashGetReqDlMsg
00240 // (which is an empty ID and so not represented here).
00241 typedef struct FlashGetCnfUlMsgTag_t
00242 {
00243     bool onNotOff; //!< The steady state is ON if true, otherwise OFF.
00244 } FlashGetCnfUlMsg_t;
00245 
00246 // ----------------------------------------------------------------
00247 // MESSAGE UNIONS
00248 // ----------------------------------------------------------------
00249 
00250 /// Union of all downlink messages.
00251 typedef union DlMsgUnionTag_t
00252 {
00253     RebootReqDlMsg_t rebootReqDlMsg;
00254     ReadingIntervalSetReqDlMsg_t readingIntervalSetReqDlMsg;
00255     GpioSetReqDlMsg_t gpioSetReqDlMsg;
00256     GpioGetReqDlMsg_t gpioGetReqDlMsg;
00257     LedSetReqDlMsg_t ledSetReqDlMsg;
00258     FlashSetReqDlMsg_t flashSetReqDlMsg;
00259 } DlMsgUnion_t;
00260 
00261 /// Union of all uplink messages.
00262 typedef union UlMsgUnionTag_t
00263 {
00264     InitIndUlMsg_t initIndUlMsg;
00265     VolumeIndUlMsg_t volumeIndUlMsg;
00266     RssiIndUlMsg_t rssiIndUlMsg;
00267     SerialNumberIndUlMsg_t serialNumberIndUlMsg;
00268     SerialNumberGetCnfUlMsg_t serialNumberCnfUlMsg;
00269     ReadingIntervalSetCnfUlMsg_t readingIntervalSetCnfUlMsg;
00270     ReadingIntervalGetCnfUlMsg_t readingIntervalGetCnfUlMsg;
00271     uint32_t gpioSetCnfUlMsg; // These are left packed inside a uint32_t so that
00272     uint32_t gpioGetCnfUlMsg; // they can be passed to C# without a struct.
00273     LedSetCnfUlMsg_t ledSetCnfUlMsg;
00274     LedGetCnfUlMsg_t ledGetCnfUlMsg;
00275     FlashSetCnfUlMsg_t flashSetCnfUlMsg;
00276     FlashGetCnfUlMsg_t flashGetCnfUlMsg;
00277 } UlMsgUnion_t;
00278 
00279 #endif
00280 
00281 // End Of File