David Smart / NWSWeather

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

NWSWeather.h@3:41504de1f387, 2014-03-23 (annotated)

Committer:
WiredHome
Date:
Sun Mar 23 20:42:29 2014 +0000
Revision:
3:41504de1f387
Parent:
2:eae60b64066e
Child:
5:f3ae5160977e
very minor documentation update.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 1:e077d6502c94 1 /// @file NWSWeather.h
WiredHome 1:e077d6502c94 2 /// This file contains the interface for gathering forecast from NWS.
WiredHome 1:e077d6502c94 3 ///
WiredHome 1:e077d6502c94 4 /// @attention This program is copyright (c) 2014 by Smartware Computing, all
WiredHome 1:e077d6502c94 5 /// rights reserved.
WiredHome 1:e077d6502c94 6 ///
WiredHome 1:e077d6502c94 7 /// This software, and/or material is the property of Smartware Computing. All
WiredHome 1:e077d6502c94 8 /// use, disclosure, and/or reproduction not specifically authorized by Smartware
WiredHome 1:e077d6502c94 9 /// Computing is prohibited.
WiredHome 1:e077d6502c94 10 ///
WiredHome 1:e077d6502c94 11 /// This software may be freely used for non-commercial purposes, and any
WiredHome 1:e077d6502c94 12 /// derivative work shall carry the original copyright. The author of
WiredHome 1:e077d6502c94 13 /// a derivative work shall make clear that it is a derivative work.
WiredHome 1:e077d6502c94 14 ///
WiredHome 1:e077d6502c94 15 /// @author David Smart, Smartware Computing
WiredHome 1:e077d6502c94 16 ///
WiredHome 0:4435c965d95d 17 #ifndef NWSWEATHER_H
WiredHome 0:4435c965d95d 18 #define NWSWEATHER_H
WiredHome 0:4435c965d95d 19 #include "mbed.h"
WiredHome 0:4435c965d95d 20 #include "HTTPClient.h"
WiredHome 0:4435c965d95d 21
WiredHome 0:4435c965d95d 22 /// NOAA's National Weather Service handler class.
WiredHome 0:4435c965d95d 23 ///
WiredHome 0:4435c965d95d 24 /// This class will fetch and parse weather data from an XML feed
WiredHome 0:4435c965d95d 25 /// using a URL such as "http://www.weather.gov/data/current_obs/KALO.xml".
WiredHome 0:4435c965d95d 26 ///
WiredHome 1:e077d6502c94 27 /// @attention Proper use of this should follow the NWS guideline,
WiredHome 1:e077d6502c94 28 /// which is to not request this data from the server more often than
WiredHome 1:e077d6502c94 29 /// necessary, and ideally to recognize and use the suggested_pickup
WiredHome 1:e077d6502c94 30 /// parameter for subsequent updates of the weather information. This
WiredHome 1:e077d6502c94 31 /// class does not monitor the RTC so is unaware of the time of day. It
WiredHome 1:e077d6502c94 32 /// is therefore up to the user to manage this recommended practice.
WiredHome 1:e077d6502c94 33 ///
WiredHome 0:4435c965d95d 34 /// Only the essential parameters are gathered, which is generally those
WiredHome 0:4435c965d95d 35 /// from which you can derive others. It turns out this is also most of the
WiredHome 0:4435c965d95d 36 /// parameters.
WiredHome 1:e077d6502c94 37 ///
WiredHome 1:e077d6502c94 38 /// \li observation_time_rfc822 - "Sun, 16 Mar 2014 09:54:00 -0500"
WiredHome 1:e077d6502c94 39 /// \li suggested_pickup - "15 minutes after the hour"
WiredHome 1:e077d6502c94 40 /// \li suggested_pickup_period - 60 (minutes)
WiredHome 0:4435c965d95d 41 /// \li location
WiredHome 0:4435c965d95d 42 /// \li weather
WiredHome 0:4435c965d95d 43 /// \li temp_f
WiredHome 0:4435c965d95d 44 /// \li temp_c
WiredHome 0:4435c965d95d 45 /// \li relative_humidity
WiredHome 0:4435c965d95d 46 /// \li wind_degrees
WiredHome 0:4435c965d95d 47 /// \li wind_mph
WiredHome 0:4435c965d95d 48 /// \li pressure_mb
WiredHome 0:4435c965d95d 49 /// \li pressure_in
WiredHome 0:4435c965d95d 50 /// \li dewpoint_f
WiredHome 0:4435c965d95d 51 /// \li dewpoint_c
WiredHome 0:4435c965d95d 52 /// \li windchill_f
WiredHome 0:4435c965d95d 53 /// \li windchill_c
WiredHome 0:4435c965d95d 54 /// \li visibility_mi
WiredHome 1:e077d6502c94 55 /// \li icon_url_base - http://forecast.weather.gov/images/wtf/small/
WiredHome 1:e077d6502c94 56 /// \li icon_url_name - ovc.png (changes based on forecast)
WiredHome 0:4435c965d95d 57 /// \li latitude
WiredHome 0:4435c965d95d 58 /// \li longitude
WiredHome 0:4435c965d95d 59 ///
WiredHome 0:4435c965d95d 60 class NWSWeather
WiredHome 0:4435c965d95d 61 {
WiredHome 0:4435c965d95d 62 public:
WiredHome 1:e077d6502c94 63 /// Return code interpretation.
WiredHome 1:e077d6502c94 64 typedef enum
WiredHome 1:e077d6502c94 65 {
WiredHome 1:e077d6502c94 66 noerror, ///< no error, or parameter has been updated.
WiredHome 1:e077d6502c94 67 nomemory, ///< insufficient memory to complete operation.
WiredHome 1:e077d6502c94 68 noresponse, ///< no response from server.
WiredHome 1:e077d6502c94 69 badparameter, ///< bad parameter to function (typically out of range value).
WiredHome 1:e077d6502c94 70 noupdate, ///< no update available.
WiredHome 1:e077d6502c94 71 noparamfound ///< no parameter found.
WiredHome 1:e077d6502c94 72 } NWSReturnCode_T;
WiredHome 1:e077d6502c94 73
WiredHome 1:e077d6502c94 74 /// Identifies the type of a parameter.
WiredHome 1:e077d6502c94 75 typedef enum
WiredHome 1:e077d6502c94 76 {
WiredHome 1:e077d6502c94 77 isFloat, ///< this parameter is a floating point value.
WiredHome 1:e077d6502c94 78 isInt, ///< this parameter is an integer.
WiredHome 1:e077d6502c94 79 isString ///< this parameter is a string value.
WiredHome 1:e077d6502c94 80 } TypeOf_T;
WiredHome 1:e077d6502c94 81
WiredHome 1:e077d6502c94 82 /// The union of available types.
WiredHome 1:e077d6502c94 83 typedef union
WiredHome 1:e077d6502c94 84 {
WiredHome 1:e077d6502c94 85 float fValue; ///< the floating point value
WiredHome 1:e077d6502c94 86 int iValue; ///< the integer value
WiredHome 1:e077d6502c94 87 char * sValue; ///< the string value
WiredHome 1:e077d6502c94 88 } Value_T;
WiredHome 1:e077d6502c94 89
WiredHome 1:e077d6502c94 90 /// The internal maintenance structure.
WiredHome 1:e077d6502c94 91 typedef struct
WiredHome 1:e077d6502c94 92 {
WiredHome 1:e077d6502c94 93 char * name;
WiredHome 1:e077d6502c94 94 TypeOf_T typeis;
WiredHome 1:e077d6502c94 95 bool updated;
WiredHome 1:e077d6502c94 96 Value_T value;
WiredHome 1:e077d6502c94 97 } XMLItem_T;
WiredHome 1:e077d6502c94 98
WiredHome 0:4435c965d95d 99
WiredHome 0:4435c965d95d 100 /// Constructor.
WiredHome 0:4435c965d95d 101 ///
WiredHome 0:4435c965d95d 102 /// Create the object to acquire the weather information from NOAA.
WiredHome 0:4435c965d95d 103 /// The full form of a valid url to acquire the data from is:
WiredHome 0:4435c965d95d 104 /// "http://www.weather.gov/data/current_obs/SITE.xml", where SITE
WiredHome 0:4435c965d95d 105 /// is replaced by the proper site location code.
WiredHome 0:4435c965d95d 106 ///
WiredHome 0:4435c965d95d 107 /// location codes are available at http://weather.noaa.gov/data/nsd_bbsss.txt,
WiredHome 0:4435c965d95d 108 /// and you can use the http://forecast.weather.gov/zipcity.php search tool
WiredHome 0:4435c965d95d 109 /// to search based on either zip code or city, state.
WiredHome 0:4435c965d95d 110 ///
WiredHome 0:4435c965d95d 111 /// It is possible to construct the NWSWeather object with an alternate
WiredHome 0:4435c965d95d 112 /// base url, but this is only useful if the alternate site is xml
WiredHome 0:4435c965d95d 113 /// compatible.
WiredHome 0:4435c965d95d 114 ///
WiredHome 0:4435c965d95d 115 /// @code
WiredHome 0:4435c965d95d 116 /// NWSWeather wx;
WiredHome 0:4435c965d95d 117 /// wx.get("KALO"};
WiredHome 0:4435c965d95d 118 /// wx.PrintAllWeatherRecords();
WiredHome 0:4435c965d95d 119 /// @endcode
WiredHome 0:4435c965d95d 120 ///
WiredHome 0:4435c965d95d 121 /// @code
WiredHome 0:4435c965d95d 122 /// NWSWeather wx("http://some.alternate.site/path/");
WiredHome 0:4435c965d95d 123 /// wx.get("KALO"};
WiredHome 0:4435c965d95d 124 /// wx.PrintAllWeatherRecords();
WiredHome 0:4435c965d95d 125 /// @endcode
WiredHome 0:4435c965d95d 126 ///
WiredHome 0:4435c965d95d 127 /// @param baseurl is an optional parameter to set the base url. If this
WiredHome 0:4435c965d95d 128 /// is not set "http://www.weather.gov/data/current_obs/" is used.
WiredHome 0:4435c965d95d 129 /// If it is set, that alternate base url is used.
WiredHome 0:4435c965d95d 130 ///
WiredHome 0:4435c965d95d 131 NWSWeather(const char * baseurl = "http://www.weather.gov/data/current_obs/");
WiredHome 0:4435c965d95d 132
WiredHome 0:4435c965d95d 133 /// Destructor.
WiredHome 0:4435c965d95d 134 ~NWSWeather();
WiredHome 0:4435c965d95d 135
WiredHome 0:4435c965d95d 136 /// set an alternate base url after construction of the NWSWeather object.
WiredHome 0:4435c965d95d 137 ///
WiredHome 0:4435c965d95d 138 /// @param alternateurl is the new url to replace the baseurl.
WiredHome 0:4435c965d95d 139 /// @param returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 140 ///
WiredHome 0:4435c965d95d 141 NWSReturnCode_T setAlternateURL(const char * alternateurl);
WiredHome 0:4435c965d95d 142
WiredHome 3:41504de1f387 143 /// get the current conditions weather data from the specified site.
WiredHome 0:4435c965d95d 144 ///
WiredHome 0:4435c965d95d 145 /// This does the work to fetch the weather data from the specified site,
WiredHome 1:e077d6502c94 146 /// using the baseurl established when the NWSWeather object was constructed,
WiredHome 1:e077d6502c94 147 /// or when it was modified with the setAlternateURL API.
WiredHome 0:4435c965d95d 148 ///
WiredHome 0:4435c965d95d 149 /// @param site is the site/location code of the site of interest.
WiredHome 2:eae60b64066e 150 /// @param responseSize is optional but important. It defaults to 2500
WiredHome 2:eae60b64066e 151 /// and is intended to tell this method the size of a buffer it
WiredHome 1:e077d6502c94 152 /// should temporarily allocate to receive and process the data.
WiredHome 0:4435c965d95d 153 /// @param returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 154 ///
WiredHome 2:eae60b64066e 155 NWSReturnCode_T get(const char * site, int responseSize = 2500);
WiredHome 0:4435c965d95d 156
WiredHome 0:4435c965d95d 157 /// get the count of the number of weather parameters.
WiredHome 0:4435c965d95d 158 ///
WiredHome 0:4435c965d95d 159 /// @returns the count of the number of parameters for which
WiredHome 0:4435c965d95d 160 /// data is expected.
WiredHome 0:4435c965d95d 161 uint16_t count(void);
WiredHome 0:4435c965d95d 162
WiredHome 0:4435c965d95d 163 /// determines if a specific parameter was updated from the last
WiredHome 0:4435c965d95d 164 /// acquisition.
WiredHome 0:4435c965d95d 165 ///
WiredHome 0:4435c965d95d 166 /// @param i is the item of interest.
WiredHome 1:e077d6502c94 167 /// @returns noerror if the parameter is up to date. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 168 ///
WiredHome 0:4435c965d95d 169 NWSReturnCode_T isUpdated(uint16_t i);
WiredHome 0:4435c965d95d 170
WiredHome 2:eae60b64066e 171 /// determines if a specific parameter was updated from the last
WiredHome 2:eae60b64066e 172 /// acquisition.
WiredHome 2:eae60b64066e 173 ///
WiredHome 2:eae60b64066e 174 /// @param name is the item of interest.
WiredHome 2:eae60b64066e 175 /// @returns noerror if the parameter is up to date. @see NWSReturnCode_T.
WiredHome 2:eae60b64066e 176 ///
WiredHome 2:eae60b64066e 177 NWSReturnCode_T isUpdated(const char * name);
WiredHome 2:eae60b64066e 178
WiredHome 0:4435c965d95d 179 /// get one of the weather parameters.
WiredHome 0:4435c965d95d 180 ///
WiredHome 1:e077d6502c94 181 /// This fetches one of the available weather parameters by setting
WiredHome 1:e077d6502c94 182 /// user supplied pointers to reference the parameter.
WiredHome 1:e077d6502c94 183 ///
WiredHome 0:4435c965d95d 184 /// @code
WiredHome 0:4435c965d95d 185 /// // Iterate over each of the parameters
WiredHome 0:4435c965d95d 186 /// for (i=0; i<wx.count(); i++) {
WiredHome 0:4435c965d95d 187 /// char * name; TypeOf_T type; char * value;
WiredHome 0:4435c965d95d 188 /// if (wx.getParam(i, name, &type, value)) {
WiredHome 0:4435c965d95d 189 /// // print the values
WiredHome 0:4435c965d95d 190 /// }
WiredHome 0:4435c965d95d 191 /// }
WiredHome 0:4435c965d95d 192 /// @endcode
WiredHome 0:4435c965d95d 193 ///
WiredHome 0:4435c965d95d 194 /// @code
WiredHome 0:4435c965d95d 195 /// // Get the names of the available parameters.
WiredHome 0:4435c965d95d 196 /// for (i=0; i<wx.count(); i++) {
WiredHome 2:eae60b64066e 197 /// char *name;
WiredHome 2:eae60b64066e 198 /// if (wx.getParam(i, name) == noerror) {
WiredHome 0:4435c965d95d 199 /// // print the names of the parameters
WiredHome 0:4435c965d95d 200 /// }
WiredHome 0:4435c965d95d 201 /// }
WiredHome 0:4435c965d95d 202 /// @endcode
WiredHome 0:4435c965d95d 203 ///
WiredHome 0:4435c965d95d 204 /// @param i is index of the parameter of interest.
WiredHome 0:4435c965d95d 205 /// @param name is a pointer that is set to point to the name of parameter i.
WiredHome 0:4435c965d95d 206 /// @param value is an optional pointer that is then set to point to the value of parameter i.
WiredHome 0:4435c965d95d 207 /// @param typeis is an optional pointer that is set to indicate the type of the value.
WiredHome 0:4435c965d95d 208 /// @param returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 209 ///
WiredHome 2:eae60b64066e 210 NWSReturnCode_T getParam(uint16_t i, char *name, Value_T *value = NULL, TypeOf_T *typeis = NULL);
WiredHome 0:4435c965d95d 211
WiredHome 0:4435c965d95d 212 /// get one of the weather parameters.
WiredHome 0:4435c965d95d 213 ///
WiredHome 1:e077d6502c94 214 /// This searchs the parameter set for the named parameter, and if found
WiredHome 1:e077d6502c94 215 /// it will set the user supplied pointers to the value and type information
WiredHome 1:e077d6502c94 216 /// for that parameter.
WiredHome 1:e077d6502c94 217 ///
WiredHome 0:4435c965d95d 218 /// @code
WiredHome 2:eae60b64066e 219 /// float value; TypeOf_T type;
WiredHome 2:eae60b64066e 220 /// if (wx.getParam("temp_f", &value, &type) == noerror) {
WiredHome 0:4435c965d95d 221 /// // print the values
WiredHome 0:4435c965d95d 222 /// }
WiredHome 0:4435c965d95d 223 /// @endcode
WiredHome 0:4435c965d95d 224 ///
WiredHome 0:4435c965d95d 225 /// @param name is a const pointer to a string naming the parameter of interest.
WiredHome 0:4435c965d95d 226 /// @param value is a pointer that is set to point to the value of parameter i.
WiredHome 0:4435c965d95d 227 /// @param typeis is a pointer that is set to indicate the type of the value.
WiredHome 0:4435c965d95d 228 /// @param returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 229 ///
WiredHome 0:4435c965d95d 230 NWSReturnCode_T getParam(const char *name, Value_T *value, TypeOf_T *typeis = NULL);
WiredHome 0:4435c965d95d 231
WiredHome 0:4435c965d95d 232 /// Print to stdout the specified weather record.
WiredHome 0:4435c965d95d 233 ///
WiredHome 1:e077d6502c94 234 /// Prints the specified record as a "Parmeter = value\r\n" string, formatted
WiredHome 1:e077d6502c94 235 /// so that subsequent prints line up at the '=' sign.
WiredHome 0:4435c965d95d 236 ///
WiredHome 0:4435c965d95d 237 /// @param i specifies the record.
WiredHome 0:4435c965d95d 238 ///
WiredHome 0:4435c965d95d 239 void PrintWeatherRecord(uint16_t i);
WiredHome 0:4435c965d95d 240
WiredHome 0:4435c965d95d 241 /// Printa all the records to stdout.
WiredHome 0:4435c965d95d 242 ///
WiredHome 1:e077d6502c94 243 /// calls PrintWeatherRecord for each available parameter.
WiredHome 0:4435c965d95d 244 ///
WiredHome 0:4435c965d95d 245 void PrintAllWeatherRecords(void);
WiredHome 0:4435c965d95d 246
WiredHome 0:4435c965d95d 247 private:
WiredHome 0:4435c965d95d 248 HTTPClient http;
WiredHome 0:4435c965d95d 249 char * m_baseurl;
WiredHome 0:4435c965d95d 250 NWSReturnCode_T ParseWeatherRecord(char * p);
WiredHome 0:4435c965d95d 251 void ParseWeatherXML(char * message);
WiredHome 0:4435c965d95d 252 void ClearWeatherRecords(void);
WiredHome 0:4435c965d95d 253 };
WiredHome 0:4435c965d95d 254 #endif // NWSWEATHER_H