### davconCW_HowTo.txt ###
FOR script ver CW2.4.1 :-
Davis Console VP2 (and VUE), Cumulus and Weather Display, php scripts.
These scripts deliver a 'Live' representation of the actual Davis Consoles for
users of the Saratoga template system.
Note - if using an alternative dashboard and associated files, then for items
such as showage, setting changes may be required in the alternate files, not
those referenced here.
These scripts 'close the loop' - the data from the console is processed
by the weather software, transmitted to the website, then reproduced as a
representation of the console from which the data came.
Working scripts (driven by Cumulus) may be viewed at;
http://silveracorn.nz/weather/ menu item - Live Console
There is one main script and VP2 and VUE include scripts for each screen layout;
davconvp2CW.php is the main script - may be copied/renamed to davconvueCW.php
The include files are named;
davconvp2CW-inc.php for the Davis VP2, VPro2 and VPro2 Plus consoles
davconvueCW-inc.php for the Davis VUE console
The scripts work with Cumulus and with Weather Display.
(There is an alternate package for Cumulus users of the standard Cumulus
generated website scripts utilising davconvp2CU.php/vue and include files)
The same data is used for either VP2 or VUE and the supplied davconvp2CW.php
handles either display by setting the $console variable which then uses the
associated include file to handle the differences between each console type.
The options are;
if using both, make a copy of davconvp2CW.php and rename the copy
davconvueCW.php and use both -inc files.
if only using the VP2 console, use the vp2CW.php and the vp2CW-inc.php files.
if only using the VUE console, rename the davconvp2CW.php to davconvueCW.php
and use the vueCW and the vueCW-inc file.
See the INSTALLATION section below for further details.
All other files / folders in this package are common to both vp2 and vue scripts
REQUIREMENTS;
1. SARATOGA Template system ajax / PHP scripts
NOTES rearding HTML5
At version 2.4.0, the package was upgraded to HTML5.
Since early 2012, Ken True has made changes to a number of scripts to
enable both HTML4/XHTML and HTML5 scripts to work with the templates.
This does require that a number of scripts be updated. So if you have not
updated your templates since before Feb 5 2012 then you should do so now.
Updates available at http://saratoga-weather.org/wxtemplates/updates.php
While these scripts should still run, a number of validation errors will
be present and unexpected behaviour may arise now or in the future.
There is a (partial?) list of the affected files at the end of this HowTo.
If you have been keeping up to date there should be nothing to do!
2. Davis Vantage Vue, Pro, Pro2 or Plus
(will also work with SOME other stations that deliver a forecast string else
the forecast will be empty and a 'grid' icon will display.
- configured for LaCrosse and Oregon Scientific. Only a subset of the
icons are available for these stations and the forecasts are very brief).
3. Cumulus weather software OR Weather Display software.
4. davconvp2CW.php (and/or davconvueCW.php) - placed in main scripts folder.
davconvp2CW-inc.php (and/or davconvueCW-inc.php) in main scripts folder.
5. ./davcon/ folder and all its files, jquery libraries, scripts and
.css, jscroller2.js, fonts and graphics supplied in this application package.
6. For Cumulus only:-
davcon24T.txt - to generate davcon24.txt - supplies data for the 24 hr graphs
and a few other tag data items
7. Current system tested in English only. Icon matching requires Saratoga
$vpforecasttext containing Davis forecast strings in English. There are no
included translation functions EXCEPT for the scrolling forecast text.
See notes in the customisation section below for options.
INSTALLATION;
Note:- if testing this script in a different folder structure from
the main site then the paths will need to be changed to suit.
The standard used references files and folders by prefixing the them with ./
to ensure they are referenced to the main script folder.
Ensure the files loaded by the wx software are available to these folders,
or while testing, copy the files to the test folders structure.
For WD, All data is supplied from the standard files uploaded to the website
for the Saratoga Template system.
For Cumulus, the Graph data requires a special file - davcon24.txt which must
be sent to the website.
Some data is processed directly from realtime file(s) and other data via tags
through Saratoga site variables.
1. Unzip davconsoleCWxxx_xxx.zip into a local working folder on your PC
A. If using Cumulus; (davcon24T.txt is NOT required for Weather Display!)
a.Copy the 24hr graph data file davcon24T.txt to the C:\Cumulus\web folder
b. Set up Cumulus to generate the output from davcon24T.txt and send it
to the website;
Use the Cumulus, Configuration, Internet, Files panel and select an
unused entry.
Configuration / Internet settings / Files
In the Local Filenames, click Browse and select the
C:\Cumulus\web\davcon24T.txt file as the local filename.
In the Remote Filenames box, enter the webserver location and
davcon24.txt as the Remote Filename to use (No 'T').
e.g. /servername/folder/davcon24.txt (same location as other
website files).
Tick Process and FTP
Leave the Binary? box unchecked,
Check the Process? box.
Leave the Realtime? box unchecked.
As this file is used to update the hourly graph data there is no
need to send it at the realtime interval
Check the FTP? box.
Press OK on the Internet Settings dialog to close it and save the
settings.
B. TO change davconvp2CW.php to davconvueCW.php
a. Open davconvp2CW.php in your editor and save as davconvueCW.php
b. At line 162, change $console = 'VP2'; to 'VUE'; - upper case!
If you have a 'Plus'
At line 163, change $vp2Plus = 'N'; to $vp2Plus = 'Y'; - upper case!
c. WD Users - Check the setting at
line 149 $realint
Ensure this is set to match the clientraw.txt update cycle time in
seconds * 1000. This is used for status messages and serves the same
purpose as the setting for reloadTime in ajaxWDwx.js.
line 164 $uomsys,
for Metric measurements set $uomsys = 'M'; - upper case!
for Imperial/english, set $uomsys = 'I'; - upper case!
C. For Both Cumulus and Weather Display;
a. Copy davconvp2CW.php (and/or davconvueCW.php) to the main scripts
folder for the console(s) you wish to display.
Also copy the matching -inc file(s) to the same location.
b. Copy all the remaining files to the webserver EXCEPT:- davcon24T.txt
and this davconCW_HowTo.txt.
Ensure the ./davcon/ folder and all its files are placed immediately
below the main scripts folder.
All the files in ./davcon/ are common to Cumulus and WD, and to VUE
or VP2 Consoles (except for the xxx_consolexxx.png console images).
The physical VP2 console uses larger Icons than the VUE, however these
scripts use the Vue size icons for both Vue and VP2.
c. To test davconvp2CW.php (and/or davconvueCW.php), open the website and
edit the URL replacing index.php or other script name (if any)
with davconvp2CW.php (or davconvueCW.php), press enter.
d. When you have the script(s) working, add davconvp2CW.php
(and/or davconvueCW.php) to flyout-menu.xml;
-
2. There is a routine in the davconvp2CW.php script (and vue if used)
to monitor the action of the icon matching routine.
If the routine cannot determine the icon from $vpforecast it will
create a file davconfcst.txt in the main scripts folder and write the
missing forecast details to it while using grid.png
(three horizontal bars) for the forecast icon.
So if the grid icon is displayed as the forecast icon, (and the forecast
is NOT "FORECAST REQUIRES 3 HOURS OF RECENT DATA"),
and a station that provides a forecast string is being used, then
1. The forecast is not Standard Davis, LaCrosse or Oregon scientific,
2. The forecast is not in ENGLISH, or
3. The forecast string is missing. Please advise BCJKiwi via
the contact form on http://silveracorn.nz/weather so the script
may be updated. Please include davconfcst.txt in your message.
Davis forecasts are for the next 12 hours. The icon should match the
real console. If one does not match, again, advise BCJKiwi
including details of the icon and the forecast string.
3. DOES THE EMULATION MATCH THE PHYSICAL CONSOLE?
The data on the image is the data provided by the weather software.
There will be some differences in layout and presentation.
To avoid a large number of button selection processes, the script adopts a
rotation approach where a number of the displayed items 'rotate' between
different data items.
There are settings to manage this activity.
4. When using the vp2Plus setting, there is a day/night switch which turns off
the the ET/UV/Solar data rotation display at night (when it would typically
display all zeroes).
Similarly, storm rain rotation turns off if there is no storm rain.
CUSTOMISATION;
Use a PROPER EDITOR - NOT windows notepad - suggest notepad++ if you don't
already have one.
Ensure encoding is set to UTF-8 without BOM / ANSI as UTF-8
The same source data is used for either VP2 or VUE console so
either one (or both) may be used regardless of which console is
actually being used.
We find the vp2 version works well on smart phones and tablets.
All option changes are made in davconvp2CW.php (and/or davconvueCW.php) EXCEPT
Non-standard units for WD - see item 4.2 below.
SCREEN WIDTH - narrow templates and VP2
If you are using the standard Saratoga weather-screen-yourcolor(s)-narrow.css
layouts then the VP2 image (but not the VUE) will not fit as it is too wide.
The simplest fix is to change the width in the ...-narrow.css file(s) from
the default 800px to 830px.
This setting is in the 3rd block down from the top;
#page {
margin: 20px auto;
color: black;
background-color: white;
padding: 0;
width: 800px;
border: 1px solid #959596;
}
Change width: 800px; to width: 830px;
This is the only change needed for standard Base-World or Base-USA templates.
1. There is a "meta-refresh" routine which automatically refreshes the page
and also adjusts the refresh time to synchronise the page refresh to the
tag file upload time (+ ~ 20 secs).
WD Users - If $timeofnextupdate is not present, or not showing the right
time, then please carefully review Ken True's setup guide at
http://saratoga-weather.org/wxtemplates/setup-WD.php
This line should be present in testtags.txt and WD set to deliver it to
the website as testtags.php.
The ONLY items affected by this meta refresh routine are the graph, the
forecast icon and the scrolling forecast text.
The Davis Console updates the forecast and icon once per hour on the hour.
2. For the davconvp2CW.php scripts (and/or davconvueCW.php), the CU/WD selection
should be automatic (using settings-weather.php $SITE['WXsoftware'])
3. The moon phases hemisphere should also be automatically adjusted via
settings.php $SITE['latitude'].
4. For a VPro2 Plus (Solar, UV & ET), change the default for $vp2Plus
at line 163 from 'N' to 'Y'.
Note that for WD, ET is not provided in clientraw so instead is taken from
clientrawextra.
5.1 Cumulus Users;
The units and the Units of Measure legend displayed (kph/mph, deg C/F etc)
will match Cumulus settings.
5.2 Weather Display Users;
The javascript module ./davcon/jquery.davconsoleCW.js auto-configures the
data items using calculations and units based on the variables
$uomsys (line 164), $timeformat (line 188) and $dateformat (line 190).
Should you wish to use other measurement combinations (e.g. knots, m/s) or
mix metric and imperial you will need to edit
./davcon/jquery.davconsoleCW.js directly in the WD section beginning at
line 130.
6. Station number and data receive indicator are shown by default.
The station number(s) may be configured, and the display of number or
indicator may be turned on or off.
The station number may be set at any of the 8 locations but to match the real
VP2 console, they should be placed in the correct locations.
The Vue console uses a different placement and terminology console,
This script uses the VP2 terminology for both VP2 and Vue
Set the station's numbers at line 168 - refer to the script for details.
Set the display of station number at line 169 and data receive indicator
($showantenna) at line 170.
7. To change the frequency of the rain data & dew rollover and data refresh
for all but graph and forecast data;
At line 172, edit the 3 in
$itimeout = 3; // default 3 = time between changes in seconds.
This is the time between the rotating data exchanges in secs (compass
pointer, wind speed/dir, dew, rain, ET/UV/Solar). Compass data changes at
'realtime'.
We recommend $itimeout be set equal to (or some even divisor of) the
'realtime' update time to match the new realtime data updates.
There are three rotation items that can have their behaviour changed
windrotate - Line 175;
1 = wind speed only or 2 = wind speed & wind direction in degrees
dewrotate - Line 177;
Options 1 through 4 as shown in the script
dayrnrotate - Line 185;
1 = Daily (& ETrans if VP2) or 2 = Daily rain, Etrans & Storm rain
Time and Date display may be configured as 'metric' or 'US'
timeformat - line 188;
1 = Force time display to 'metric' 24 hr format hh:mm
2 = Force time display to 'US' 12 hr format hh:mm am/pm
dateformat - line 190;
1 = Force date display to 'metric' format dd/mm
2 = Force date display to 'US' format mm/dd
8. Below the image there are status messages indicating next update time, and,
age of the realtime update.
a. To stop the "Next Graph and Forecast update @ ~ hh:mm" message displaying,
at line 192, change $showupdate = 1; to $showupdate = 0;
WD Users - If $timeofnextupdate in testtags.php is not present in,
or not showing the right time, then please carefully review Ken True's
setup guide at http://saratoga-weather.org/wxtemplates/setup-WD.php
b. NOTE: The 'showage' feature requires ./davcon/showage.js.
i. To stop the "Realtime" data updated ss secs ago" message displaying,
at line 199, change $showage = 1; to $showage = 0;
These two status messages may also be set to 2.
Option 1 "looks ahead" to the next update time
Option 2 "looks back" to the last update time
9. Graph data;
a. For Cumulus Users, this is provided by the file davcon24.txt and is loaded
at tag file load time (set by Cumulus file uploading).
b. For WD users it is provided by clientrawexta.
While the file content changes at these upload intervals the graph represents
24 hrs at 1 hourly intervals.
10. Button options;
a. The second column (or row) of buttons on the console and on the table
below the image (Forecast/WXcen - Done) are set to call the default
Cumulus local scripts.
These may be changed at line 211 through 227, use the same syntax.
Alternatively the local filename e.g. './wxcugraphs.php' may be replaced
by a url e.g. 'http://silveracorn.nz/weather'
To change the description beside the button in the table;
Edit the associated button text at line 213 through 228.
b. To make a button inactive;
edit the $....btntxt = "some text"; to $....btntxt = ""; NO SPACE! to
remove the text next to the button. Both the table button and the
associated console button will be disabled. This will leave the button
in place with its legend but inactive.
c. The buttons that can call scripts may be configured to;
i. open these scripts in the same tab as the existing page replacing
the page and requiring use of the 'back' button on the browser to
return to the console page.
or;
ii. open these scripts in a new tab (assuming the user has tabs
configured in their browser.)
This behaviour may be customised to suit your preference but do think of
visitors' preferences as well which may not be the same as your own.
At line 230, change $taboption = 1; The four options provide for either,
neither, or both the console and table buttons to use new tabs.
There is also a tooltip to indicate when a new tab will be used instead of
the default browser behaviour. This may be turned off by changing the
setting at line 234 $showtooltip = true; from true to false.
NOTE:- the tool tip is not fully supported by IE10 but is in IE8 9 & 11 as
well as the current versions of FF and Chrome.
For IE10 the buttons work as intended but the tooltip does not display
on the table buttons (but does on the console buttons- the code is
quite different in these two areas)
11. Translations
a. Forecast text;
The icon decoder relies on the original English text from the console
DO NOT ALTER THIS SECTION!.
Translation of the scrolling forecast text requires forecast translations
to be provided in the Saratoga langtrans-xx.txt files. If these are not
added then the scroller forecast text will remain in English
b. Static text (e.g. labels like TEMP OUT or INSIDE) not delivered by
the weather software may be changed to your language in
davconvp2CW-inc.php (and/or davconvueCW-inc.php) starting at line 165/7
If the text changes when data rotates then you will need to change the
text in ./davcon/jquerydavconsoleCW.js instead. Proceed with extreme
caution in this script as some items come from CU or WD and others are
hard coded in the .js rotation code blocks.
HTML5 Saratoga Updates from February 5th 2012 (partial? list):
Check that these files are at or later than the version shown below.
ajax-gizmo.php Version 1.14 - 17-Mar-2013 - Multilingual (and possibly other versions.)
common.php Version 1.07 - 09-Feb-2013
CU-trends-inc.php Version 1.09 - 05-Feb-2013 (and possibly other versions.)
flyout-menu.php (ML) Version 1.08 - 05-Feb-2013
footer.php Version 1.01 - 05-Feb-2012
include-style-switcher.php Version 1.19 - 05-Feb-2013
plaintext-parser.php Version 1.30 - 30-Dec-2013
top.php Version 3.04 - 05-Feb-2013
wxquake.php Version 1.04 - 24-May-2013
At this time, common.php may need line 429 to eliminate a validation error as
border="0" is no longer valid in this context.
If you do not have the Language flags on your site, then no change is required.
changed to;
to remove warnings if Language option flags are used.
Enjoy!