Metadata-Version: 2.3
Name: volttron-weather-dot-gov
Version: 2.0.0rc0
Summary: A weather agent using the weather.gov API to collect weather data for the VOLTTRON platform.
License: Apache-2.0
Author: VOLTTRON Team
Author-email: volttron@pnnl.gov
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: grequests (==0.7.0)
Requires-Dist: volttron-lib-base-weather (>=2.0.0rc0)
Project-URL: Homepage, https://github.com/eclipse-volttron/volttron-lib-base-weather
Project-URL: Repository, https://github.com/eclipse-volttron/volttron-lib-base-weather
Description-Content-Type: text/markdown

# WeatherDotgov Agent
  
This agent provides the ability to query for current and forecast
weather data from NOAA. The agent extends BaseWeatherAgent that provides
caching of recently requested data, as well as mapping of weather point
names from NOAA\'s naming scheme to the standardized CF-conventions
scheme.

## Configuration

The following is an example configuration for the Weather.gov agent. All
configuration parameters are optional.

**Parameters**

1.  \"database_file\" - sqlite database file for weather data caching.
    Defaults to \"weather.sqlite\" in the agent\'s data directory
2.  \"max_size_gb\" - maximum size of cache database. When cache
    exceeds this size, data will get purged from cache until the cache
    is within the configured size.
3.  \"poll_locations\" - list of locations to periodically poll for
    current data. 
    1. For current weather, the only supported location format is station id.
       Format: [{"station": "KLAX"}, {"station": "KBOI"}]
    2. For hourly forecast supported  location formats are
       1. wfo, x, y - Format: {"wfo": 'BOU', 'x': 54, 'y': 62}
       2. latitude, longitude - Format: {"lat": 39.0693, "long": -94.6716}.  Weather agent will first lookup wfo,x,y 
          for the given latitude and logitude and then get the forceast data based on wfo, x, y
       3. station id - Format:  [{"station": "KLAX"}, {"station": "KBOI"}]
       The input list can contain valid locations with different formats. For example,
       ```[{"station": "KLAX"}, {"station": "KBOI"}, {"wfo": 'BOU', 'x': 54, 'y': 62}]``` is a valid input list for 
       hourly forecast
   
4.  \"poll_interval\" - polling frequency or the number of seconds
    between each poll.
    
    ```
    {
        "database_file": "weather.sqlite",
        "max_size_gb": 1,
        "poll_locations": [{"station": "KLAX"}, {"station": "KPHX"}],
        "poll_interval": 60
    }
    ```
    
# Registry Configuration

The registry configuration file for this agent can be found in agent\'s
data directory. This configuration provides the point name mapping from
NOAA\'s point scheme to the CF-conventions scheme by default. The file
leaves the unit name columns for each point blank, as this agent does
not include unit conversion. Points that do not specify
\'Standard_Point_Name\' were found to not have a logical match to any
point found in the CF-Conventions. For these points NOAA point names
(Service_Point_Name) will be used.

  |Service_Point_Name  | Standard_Point_Name            |  Service_Units |   Standard_Units |
  |--------------------|--------------------------------|----------------|------------------|
  |heatIndex           |                                |                |                  |
  |presentWeather      |                                |                |                  |                                                 
  |seaLevelPressure    |air_pressure_at_mean_sea_level  |                |                  |                
  |temperature         |air_temperature                 |                |                  |                


## Notes

The WeatherDotGov agent does not utilize an API key, as NOAA allows
users to gather weather data for free, and does not provide nor require
keys.

This implementation of the weather agent does not include historical
weather data, as NOAA does not provide an accessible endpoint from which
historical data may be obtained.

Data provided by NOAA is in a nested dictionary format. The base weather
agent does not handle unit conversion for arbitrary nested dictionary
format and hence this agent does not support unit conversion at this
time.

