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@9:fcd83b2bd0cd, 2014-10-11 (annotated)

Committer:
WiredHome
Date:
Sat Oct 11 17:27:07 2014 +0000
Revision:
9:fcd83b2bd0cd
Parent:
6:cf96f2787a4e
Child:
17:99f09cc697fb
Documentation updates only.

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 6:cf96f2787a4e 93 const 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 9:fcd83b2bd0cd 127 /// @param[in] 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 5:f3ae5160977e 131 /// for future forecast
WiredHome 5:f3ae5160977e 132 /// http://forecast.weather.gov/MapClick.php?lat=42.47508&lon=-92.36704926700929
WiredHome 5:f3ae5160977e 133 // &unit=0&lg=english&FcstType=dwml
WiredHome 5:f3ae5160977e 134 ///
WiredHome 0:4435c965d95d 135 NWSWeather(const char * baseurl = "http://www.weather.gov/data/current_obs/");
WiredHome 0:4435c965d95d 136
WiredHome 0:4435c965d95d 137 /// Destructor.
WiredHome 0:4435c965d95d 138 ~NWSWeather();
WiredHome 0:4435c965d95d 139
WiredHome 0:4435c965d95d 140 /// set an alternate base url after construction of the NWSWeather object.
WiredHome 0:4435c965d95d 141 ///
WiredHome 9:fcd83b2bd0cd 142 /// @param[in] alternateurl is the new url to replace the baseurl.
WiredHome 9:fcd83b2bd0cd 143 /// @returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 144 ///
WiredHome 0:4435c965d95d 145 NWSReturnCode_T setAlternateURL(const char * alternateurl);
WiredHome 0:4435c965d95d 146
WiredHome 3:41504de1f387 147 /// get the current conditions weather data from the specified site.
WiredHome 0:4435c965d95d 148 ///
WiredHome 0:4435c965d95d 149 /// This does the work to fetch the weather data from the specified site,
WiredHome 1:e077d6502c94 150 /// using the baseurl established when the NWSWeather object was constructed,
WiredHome 1:e077d6502c94 151 /// or when it was modified with the setAlternateURL API.
WiredHome 0:4435c965d95d 152 ///
WiredHome 9:fcd83b2bd0cd 153 /// @param[in] site is the site/location code of the site of interest.
WiredHome 9:fcd83b2bd0cd 154 /// @param[in] responseSize is optional but important. It defaults to 2500
WiredHome 2:eae60b64066e 155 /// and is intended to tell this method the size of a buffer it
WiredHome 1:e077d6502c94 156 /// should temporarily allocate to receive and process the data.
WiredHome 9:fcd83b2bd0cd 157 /// @returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 158 ///
WiredHome 2:eae60b64066e 159 NWSReturnCode_T get(const char * site, int responseSize = 2500);
WiredHome 0:4435c965d95d 160
WiredHome 0:4435c965d95d 161 /// get the count of the number of weather parameters.
WiredHome 0:4435c965d95d 162 ///
WiredHome 0:4435c965d95d 163 /// @returns the count of the number of parameters for which
WiredHome 0:4435c965d95d 164 /// data is expected.
WiredHome 0:4435c965d95d 165 uint16_t count(void);
WiredHome 0:4435c965d95d 166
WiredHome 0:4435c965d95d 167 /// determines if a specific parameter was updated from the last
WiredHome 0:4435c965d95d 168 /// acquisition.
WiredHome 0:4435c965d95d 169 ///
WiredHome 9:fcd83b2bd0cd 170 /// @param[in] i is the item of interest.
WiredHome 1:e077d6502c94 171 /// @returns noerror if the parameter is up to date. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 172 ///
WiredHome 0:4435c965d95d 173 NWSReturnCode_T isUpdated(uint16_t i);
WiredHome 0:4435c965d95d 174
WiredHome 2:eae60b64066e 175 /// determines if a specific parameter was updated from the last
WiredHome 2:eae60b64066e 176 /// acquisition.
WiredHome 2:eae60b64066e 177 ///
WiredHome 9:fcd83b2bd0cd 178 /// @param[in] name is the item of interest.
WiredHome 2:eae60b64066e 179 /// @returns noerror if the parameter is up to date. @see NWSReturnCode_T.
WiredHome 2:eae60b64066e 180 ///
WiredHome 2:eae60b64066e 181 NWSReturnCode_T isUpdated(const char * name);
WiredHome 2:eae60b64066e 182
WiredHome 0:4435c965d95d 183 /// get one of the weather parameters.
WiredHome 0:4435c965d95d 184 ///
WiredHome 1:e077d6502c94 185 /// This fetches one of the available weather parameters by setting
WiredHome 1:e077d6502c94 186 /// user supplied pointers to reference the parameter.
WiredHome 1:e077d6502c94 187 ///
WiredHome 0:4435c965d95d 188 /// @code
WiredHome 0:4435c965d95d 189 /// // Iterate over each of the parameters
WiredHome 0:4435c965d95d 190 /// for (i=0; i<wx.count(); i++) {
WiredHome 0:4435c965d95d 191 /// char * name; TypeOf_T type; char * value;
WiredHome 0:4435c965d95d 192 /// if (wx.getParam(i, name, &type, value)) {
WiredHome 0:4435c965d95d 193 /// // print the values
WiredHome 0:4435c965d95d 194 /// }
WiredHome 0:4435c965d95d 195 /// }
WiredHome 0:4435c965d95d 196 /// @endcode
WiredHome 0:4435c965d95d 197 ///
WiredHome 0:4435c965d95d 198 /// @code
WiredHome 0:4435c965d95d 199 /// // Get the names of the available parameters.
WiredHome 0:4435c965d95d 200 /// for (i=0; i<wx.count(); i++) {
WiredHome 2:eae60b64066e 201 /// char *name;
WiredHome 2:eae60b64066e 202 /// if (wx.getParam(i, name) == noerror) {
WiredHome 0:4435c965d95d 203 /// // print the names of the parameters
WiredHome 0:4435c965d95d 204 /// }
WiredHome 0:4435c965d95d 205 /// }
WiredHome 0:4435c965d95d 206 /// @endcode
WiredHome 0:4435c965d95d 207 ///
WiredHome 9:fcd83b2bd0cd 208 /// @param[in] i is index of the parameter of interest.
WiredHome 9:fcd83b2bd0cd 209 /// @param[in] name is a pointer that is set to point to the name of parameter i.
WiredHome 9:fcd83b2bd0cd 210 /// @param[out] value is an optional pointer that is then set to point to the value of parameter i.
WiredHome 9:fcd83b2bd0cd 211 /// @param[out] typeis is an optional pointer that is set to indicate the type of the value.
WiredHome 9:fcd83b2bd0cd 212 /// @returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 213 ///
WiredHome 2:eae60b64066e 214 NWSReturnCode_T getParam(uint16_t i, char *name, Value_T *value = NULL, TypeOf_T *typeis = NULL);
WiredHome 0:4435c965d95d 215
WiredHome 0:4435c965d95d 216 /// get one of the weather parameters.
WiredHome 0:4435c965d95d 217 ///
WiredHome 1:e077d6502c94 218 /// This searchs the parameter set for the named parameter, and if found
WiredHome 1:e077d6502c94 219 /// it will set the user supplied pointers to the value and type information
WiredHome 1:e077d6502c94 220 /// for that parameter.
WiredHome 1:e077d6502c94 221 ///
WiredHome 0:4435c965d95d 222 /// @code
WiredHome 2:eae60b64066e 223 /// float value; TypeOf_T type;
WiredHome 2:eae60b64066e 224 /// if (wx.getParam("temp_f", &value, &type) == noerror) {
WiredHome 0:4435c965d95d 225 /// // print the values
WiredHome 0:4435c965d95d 226 /// }
WiredHome 0:4435c965d95d 227 /// @endcode
WiredHome 0:4435c965d95d 228 ///
WiredHome 9:fcd83b2bd0cd 229 /// @param[in] name is a const pointer to a string naming the parameter of interest.
WiredHome 9:fcd83b2bd0cd 230 /// @param[out] value is a pointer that is set to point to the value of parameter i.
WiredHome 9:fcd83b2bd0cd 231 /// @param[out] typeis is a pointer that is set to indicate the type of the value.
WiredHome 9:fcd83b2bd0cd 232 /// @returns success/failure code. @see NWSReturnCode_T.
WiredHome 0:4435c965d95d 233 ///
WiredHome 0:4435c965d95d 234 NWSReturnCode_T getParam(const char *name, Value_T *value, TypeOf_T *typeis = NULL);
WiredHome 0:4435c965d95d 235
WiredHome 0:4435c965d95d 236 /// Print to stdout the specified weather record.
WiredHome 0:4435c965d95d 237 ///
WiredHome 1:e077d6502c94 238 /// Prints the specified record as a "Parmeter = value\r\n" string, formatted
WiredHome 1:e077d6502c94 239 /// so that subsequent prints line up at the '=' sign.
WiredHome 0:4435c965d95d 240 ///
WiredHome 9:fcd83b2bd0cd 241 /// @param[in] i specifies the record.
WiredHome 0:4435c965d95d 242 ///
WiredHome 0:4435c965d95d 243 void PrintWeatherRecord(uint16_t i);
WiredHome 0:4435c965d95d 244
WiredHome 9:fcd83b2bd0cd 245 /// Print all the records to stdout.
WiredHome 0:4435c965d95d 246 ///
WiredHome 1:e077d6502c94 247 /// calls PrintWeatherRecord for each available parameter.
WiredHome 0:4435c965d95d 248 ///
WiredHome 0:4435c965d95d 249 void PrintAllWeatherRecords(void);
WiredHome 6:cf96f2787a4e 250
WiredHome 6:cf96f2787a4e 251 /// Clear all the data and free allocated memory.
WiredHome 6:cf96f2787a4e 252 ///
WiredHome 6:cf96f2787a4e 253 void ClearWeatherRecords(void);
WiredHome 6:cf96f2787a4e 254
WiredHome 0:4435c965d95d 255 private:
WiredHome 0:4435c965d95d 256 char * m_baseurl;
WiredHome 0:4435c965d95d 257 NWSReturnCode_T ParseWeatherRecord(char * p);
WiredHome 0:4435c965d95d 258 void ParseWeatherXML(char * message);
WiredHome 0:4435c965d95d 259 };
WiredHome 0:4435c965d95d 260 #endif // NWSWEATHER_H