The API accesses the station's archived data.to view current conditions as they occur you will need to use another program.

Transcription

1 Davis Instruments Excel API 1.1 Introduction The Davis Excel API allows you to manage, analyze, and model Davis weather station data. The program functions within the familiar user and development environment of Microsoft Excel. With the API, you can hook up a weather station, download its data, and then store the data in an Excel worksheet for viewing and/or analysis. Alternatively, you can set the API to automatically download and recalculate the data at a prescribed interval, from once every 15 minutes to once each day. The API accesses the station's archived data.to view current conditions as they occur you will need to use another program. The API, first and foremost, serves as a tool with which you can build your own application. At its core, it enables a link with a weather station, as well as automatic data updates and worksheet storage and viewing. The API then leaves it up to you to develop applications that incorporate the data. We suggest using Excel's extensive macro capabilities, Visual Basic for Applications (VBA) facilities, or simply exporting the database into another, non-excel application. As a working example, the API includes a degree-day model that performs automatic calculations on sample archival data. Requirements The Davis Excel API requires Microsoft Windows95/98 operating system; Microsoft Excel 97; a WeatherLink data logger attached to a serial port (USB is not supported); and a Davis weather station (Perception, Weather Wizard, Weather Monitor, or GroWeather). At this time, the API does not support modem or radio networks. To make full use of this product you need a working knowledge of Excel and/or VBA. Installation ( 1 ) To install the API, run the self-extracting "Excel API 1.0.exe" file provided. "Davis Excel API 1.0.exe" will create a default directory - C:\ Excel API - and then copy the following files into that directory: IPMdata.xlt - a template file that is used to create a workbook for a new station. Groweather.dll - a dynamic link library file that allows communication with a GroWeather station. Weatherlink.dll - a dynamic link library file that allows communication with a Monitor, Wizard, or Perception station. Readme.txt - this documentation file PRD41.exe - a self-extracting archive of the Programmer's Reference Disk, which includes documentation of the DLL files.

2 ( 2 ) Install the DLL that corresponds to the station you are using in one of two ways: either keep them in the same directory as the API workbooks you will create (e.g., C:\Davis Excel API); or move them into the Windows system folder (i.e. C:\Windows\System).The DLL files allow Excel to communicate with your weather station. By default, the API assumes that the DLL files are in the same directory as the workbook. When an API workbook is loaded, the API automatically changes Excel's current directory to the workbook's directory. As long as Excel's current directory is the directory in which the DLL's are stored (e.g., C:\Davis Excel API), Excel will be able to communicate with the weather station. To avoid problems with Excel being unable to find the DLL files when Excel's current directory is changed (e.g., by opening a workbook in a different directory), move the DLL's into the Windows system folder. Then, comment out the code in the Open and Close Workbook functions that change the current directory. ( 3 ) Install the API template file in one of two ways: either copy it into the Microsoft Office Template folder, or leave it in your API directory (e.g., C:\Davis Excel API). Because of the unusual way Excel 97 deals with templates, selecting the template using Excel's File > Open will NOT create a new workbook but instead will save any changes to the template itself. Thus, if you copy the template to your template folder, click File > New to create a new API workbook. Or, if you leave the file in your API directory, double click on the template in Windows Explorer to create a new API workbook. CAUTION: Do not open the template by clicking File > Open in Excel, or by selecting the template from Excel's recently used file list. If you do, any changes made will be saved in the TEMPLATE instead of in a new workbook. Workbook Contents The API workbook contains three sheets, five user forms, and several VBA modules. Each Davis weather station requires a separate API workbook. The "Status" sheet has information about the status of the API workbook, including: type of station (model), serial port settings, time of last (and next) update, status of Auto Update and Auto Calculate features, and units of measurement. It also contains five command buttons that activate user forms to control the weather station and API interface. A full description of all fields and command options is given below. The "Raw_Data" sheet contains the data downloaded from your weather station. It contains data columns for all of the data fields on all Davis Instruments weather stations. Only the fields that are available on the attached weather station are filled when the station is downloaded. See "Update Data Command" and "Raw_Data Sheet" below for more details.

3 The "DD_Sample" sheet is an implementation of a simple degree-day model. Both the daily Hi/Low and integration degree-day calculation methods are implemented. The model is implemented in VBA code attached to the sheet object. This sample uses the Auto Calculate feature to automatically update the degree-day values when new data is downloaded. In addition, there is a hidden sheet that also contains the station, serial port, update, and units settings. These are the settings that control the behavior of the API. Do NOT make any changes to this page. Status Sheet The Status sheet contains status displays and command buttons to control the API. Status Displays The displays on the status page are for your information only, they do not control the behavior of the API. You will be unable to modify any values because the sheet has been protected. To change a setting, use the appropriate command button. Under the heading "Station and Connection" you see: the Station model, serial port, baud rate, and WeatherLink Revision selected. The Link Revision is only applicable to the GroWeather station. The Monitor, Wizard, and Perception stations ignore the value of this setting. Also shown in this column is the last archive interval that was set on the station with the Excel API, the time and date of the last time the weather station's time and date were set, and the version number of the DLL being used. The first four settings can be set with the "Setup Options" button. The next two can be set with the "Set Time / Archive Interval" button. The last display is updated every time the API communicates with the station. Under the heading "Update Status" you see: the name of the sheet where the station's data will be stored, the time that the station's data was last updated, the time that the station's data will be updated next (if Auto Update is enabled), Auto Update setting (Yes/No), the Auto Update interval (note that this can be different from the archive interval), Clear After Update setting (Yes/No), and Auto Calculate setting (Yes/No). These settings can be set with the "Update Data" button. Under the heading "Units of Measurement" you see: the units of measure used for: Temperature ( F/ C), Barometer (in Hg/mm Hg/mb/hPa), Rain and ET (in/mm) Wind Direction Codes (Numbers(0-15)/Letters(N,NNE,NE )), Wind Speed (MPH), Wind Run (mi), Humidity (%), Solar Radiation (Watts per meter squared), and Solar Energy (Langleys). Rain Rate will be reported in "<Rain Units> per hour". These units are used when data is updated and stored in the Raw_Data sheet. Those units with a white background (Temperature, Barometer, Rain/ET, and Wind Direction) can be set with the "Set Units" button. Control Buttons The 5 buttons on the status sheet allow you to control the behavior of the API.

4 Setup Options Command The "Setup Options" command allows you to set the station model and serial port settings. It also can test your connection. The "Station Model" can be chosen from one of Perception, Wizard, Monitor, or GroWeather. Every time the API communicates with the station, it verifies that the model connected to matches the one selected here Enter the "Com Port" number of the serial port the station is connected to. We have not tested this with COM ports greater than 4. The "Baud Rate" can either be 1200 or 2400 baud and must match the setting of the WeatherLink attached to the station. The "Link Rev" option only applies to GroWeather stations. All Monitor, Wizard, and Perception stations are effectively Rev D links and this setting is ignored. For GroWeather links, examine the Mfg. Code on its label. If the second character is a D or an E, then this is the Link Rev selection. If the second character is a number, then select Rev D. The "Test" button will use the selections in the dialog to test the connection to the selected weather station. The results will be displayed in the white display area above the buttons. Set Leaf Wetness Command (GroWeather Only) The GroWeather station has one slot that can be used for either a soil temperature (or any other temperature) sensor or a leaf wetness sensor. Use this command to see how the station is currently set, and to change the setting on the station. If the station is not set correctly, the data will not be logged correctly. Set Time and Archive Interval Command The left side of the "Set Time and Archive Interval" dialog shows the current time and date on the weather station. Below that are two edit boxes where a new time and date may be entered. These boxes are initialized with the current system time and date. The right side shows the archive interval currently set on the station, and allows the selection of a different interval. Note that unlike our standard software, setting the archive interval will not automatically clear the archive memory. This can cause problems if the weather data is managed by both this API and our standard software. For best results in this case, use our standard software to set the archive interval after the current data has been updated in both systems.

5 You can set the time/date and archive interval independently from each other. Simply select the button that will update the desired setting(s). When the station's time and date is set, the "Synchronized" status display will be updated with the current system time (even if the station is set to a different time). When the station's archive interval is set, the Archive Interval status display will be updated with the selected value. All times displayed on the status sheet refer to time on the computer system clock. Times in the Raw_Data sheet refer to time on the weather station clock. All time values are displayed in 24-hour format. Update Data Command The Update Data command is probably the most important command. The left side of the dialog shows the last time the data was updated (either manually or automatically). Below this is shown the time the next Auto Update will occur. This display will change interactively as you make changes to the Auto Update settings. If Auto Update is not enabled, this display will be blank. Below the next update display is the Auto Clear option. If this box is checked, then the archive memory will be cleared out after every update (either manual or automatic). Next is the Auto Calculate option. If this box is checked, then the VBA function "DoAutoCalc" in the "AutoCalculate" module will be called after every update. Edit the definition of this function to perform automatic calculations on the downloaded data. On the right side of the dialog are the Auto Update configuration options. First is the check box to enable the Auto Update function. If this box is not checked, no Auto Updating will occur. Next, select the frequency to update data. This setting is independent of the station's archive interval. On the other hand, it doesn't make sense to make the auto update interval smaller than the archive interval. The last Auto Update configuration option is the Update Offset setting. This will set the "phase" of the automatic updates. If the offset is zero and the interval is 1 day, the updates will occur at midnight. A 6 hour interval will have updates at 00:00, 06:00, 12:00, and 18:00. In general, it is not good to have an Auto Update event scheduled at the same time an archive record will be created, otherwise the creation of the archive record can be delayed and cause the data to be corrupted. The Update Offset can entered either as an integer number of minutes (5, 13, 90), or as a time value with hours and minutes (0:05, 0:13, 04:26). All time values are displayed in 24-hour format. If the offset value is larger than the auto update interval, then the remainder after dividing by the update interval is used. For example, an offset of "00:23" with an interval of "15 minutes" is equivalent to an offset of "00:08". When

6 changing the offset value, the "Time of Next Auto Update" display will be updated when focus leaves the offset edit box. The workbook is saved automatically after an Auto Update is performed. If Auto Calc is also enabled, it is performed before the workbook is saved. The workbook is also saved when closed, in order to clear the "Next Update" display. This is to remind the user that the Auto Update feature will not be active the next time the workbook is open until it is activated. There are three ways to exit the Update Data dialog. The first, "Update Data Now" will perform an immediate manual download, and will activate the Auto Update feature if it has been enabled. "Do Not Update Now" activates the Auto Update feature, if it is enabled, without performing a manual download. "Cancel All Updates" exits without activating the Auto Update feature, even if it is enabled. If there is an Auto Update pending, it is canceled when the Update Data dialog is started. When the API workbook is opened, the Auto Update feature is not active until activated by this dialog. Set Units Command This dialog allows you to select the units to display and store Temperature, Barometer, Rain (and ET), and Wind direction measurements. The native units for all Davis weather stations are: Fahrenheit for temperature, inches of mercury for barometer, and inches for rain and ET. Other units are derived from these by conversion and may involve some round off error. Wind direction is reported as one of 16 direction codes that represent the prevailing wind direction. These codes can either be displayed as a number between 0 and 15, or as a compass direction symbol (N, NNE, NE, etc). The direction in degrees can be calculated from the numeric code by multiplying it by Raw_Data Sheet This worksheet holds the archived data downloaded from your weather station. It has columns for all the weather parameters on all Davis weather stations. Only those that are available on the station in use will be filled when the data is updated. The data values are primarily directly measured values. Derived or calculated values are not stored. For more information on which variables are available for different stations, and on how to calculate some common derived values, see the Programmer's Reference Disk.

7 Each row is one archive record. The first column contains the time and date combined as an Excel date value. This makes it easy to plot time series graphs with missing data by using the Date/Time column as the x-axis in an xy plot. Missing data is indicated, in most cases, by blank cells. Care should be taken when using data values from this sheet to check for missing data, since Excel often treats the value of empty cells as zero. (This can be done in VBA with the IsEmpty function.) For wind direction, however, the value -100 (or dashes "---") is used to indicate that either there is no anemometer attached, or that the wind was calm throughout the archive period. The update procedure will use the calibration settings on the weather station for barometer, outside humidity, and temperature. Setting the calibration values has not been implemented in this version of the Davis Excel API. You can set these values either directly on the station console, or with our standard software. Otherwise, a calibration factor can be added by the API user when the data is used for calculation. Care should be taken when modifying values on this sheet. The Date/Time value in the last occupied row is used to determine how much of any newly downloaded data should be added to the database when it is updated. Therefore, do not modify the values in the Date/Time column or use cells in rows past the latest data. In general, it is OK to delete entire rows of data, but we do not recommend performing any other modifications to the data on this sheet. DD_Sample Sheet The DD_Sample sheet shows how a simple degree-day (heat units, growing degreedays, or cooling degree-days) model can be implemented. In the VBA editor, there is basic code attached to the worksheet (Sheet 2). The function CalcModel is called by the DoAutoCalc function after an update, if the Auto Calc option is enabled, to calculate degree days for the data added by the most recent data update. Pressing the "Re-Calculate Model" button will force a recalculation of the degree day model on the whole database. Degree days are calculated using both the hi/low method and the integration method. The hi/low method uses the daily high and low temperatures to compute a daily average temperature. The integration method uses the average temperature and interval length to calculate the degree days generated in each archive interval. The values in the Lower Threshold and Upper Threshold boxes (cells B3 and B4) control the limits for the degree-day calculation. If the upper threshold is blank, it is not used in the calculation. The data is summarized by day. The "Data Available" column is the cumulative time represented by data in the database for the given day, expressed as a fraction of a

8 day. As in the Raw_Data sheet, the date in the last row is used to determine where previous degree day calculations finished. The code for this model may be copied and modified. It is provided as is. Programming Interface To make full use of this API, you will have to write either VBA or Excel functions to perform modeling and analysis. By editing the DoAutoCalc function in the AutoCalculate module, you can perform automatic calculations after every update. We recommend that the code be written in a separate module that is called from the DoAutoCalc function, instead of writing the code directly in the DoAutoCalc function. The module "DataLocations" contains symbolic constant names for the column numbers of the various data elements in the Raw_Data sheet. Contact Information Davis Instruments is interested in any comments, questions, or suggestions you have regarding this Excel API. Please comments to API@davisnet.com.