1
SteelSeries JavaScript gauges
2
=============================
3
Created by Mark Crossley July 2011
4
5
Version 2.5.1
6
Updated: 25 January 2015
7
8
+-------------------------------------------------------+
9
| |
10
| Please read the more comprehensive notes on the Wiki: |
11
| http://wiki.sandaysoft.com/a/SteelSeries_Gauges |
12
| |
13
| And the FAQ on the Wiki: |
14
| http://wiki.sandaysoft.com/a/SteelSeries_FAQ |
15
| |
16
| Released under GNU GENERAL PUBLIC LICENSE |
17
| Version 2, June 1991 |
18
| See the enclosed License file |
19
| |
20
+------------------------------------------------------ +
21
22
Setting Up For Cumulus Users
23
============================
24
Some brief notes for Cumulus users (but other users should skim this as well):
25
26
Copy "weather_server\cumulus\realtimegaugesT.txt" to your Cumulus\web folder.
27
Copy "weather_server\cumulus\gauges-ssT.htm" to your Cumulus\web folder.
28
29
Configure Cumulus Internet|Files to:
30
realtime file:-
31
Local filename = <path>\Cumulus\web\realtimegaugesT.txt
32
Remote filename = <website_root_path>/realtimegauges.txt
33
Process = Yes
34
Realtime = Yes
35
FTP = Yes (unless you are local hosting)
36
gauges HTML file:-
37
Local filename = <path>\Cumulus\web\gauges-ssT.htm
38
Remote filename = <website_root_path>/gauges-ss.htm
39
Process = Yes
40
Realtime = No
41
FTP = Yes (unless you are local hosing)
42
43
NOTE: Cumulus does not actually update any data when it processes the web
44
page, it simply replaces the 'static-ish' values such as your station
45
name, location, version etc. If you wish you can edit the .htm file and
46
directly enter the information, then you do not need to get Cumulus to
47
process the file, just copy it once to your web site, removing the 'T'
48
from the file name.
49
50
If required edit the "gauges.js", the key items are at the top:
51
The relative path on your website to the "realtimegauges.txt" file.
52
The relative path on your website to your 'trend' graphs folder.
53
The relative path on your website to your old 'gauges' page.
54
- users with 'old' browsers will be redirected to this page.
55
If you do not require the UV/Solar Index gauges, then change the lines
56
showUvGauge : true,
57
showSolarGauge : true,
58
to
59
showUvGauge : false,
60
showSolarGauge : false,
61
62
63
If you have installed to a web folder different from your Cumulus 'root' you
64
will also need to edit the "gauges-ss.htm" file, and amend the relative path
65
to your Cumulus "weatherstyle.css" file.
66
67
Relative Paths :
68
Are just that, they specify where something is on your web site folder
69
structure relative to the page you are currently displaying.
70
So if you copy these gauges to a folder called 'gauges-ss' in the root of
71
your website, the relative path of the Cumulus css file is one folder back in the
72
path. You would then enter the path as "../weatherstyle.css".
73
74
Copy (or move) the folders 'web_server\css' and 'web_server\scripts' and their contents (the
75
files that are contained in the ZIP file) to the folder where your "gauges-ss.htm" file is
76
located (probably the same folder where all your other Cumulus HTM files are located).
77
78
79
What Next?
80
----------
81
After you get your new gauges page up and running, you will probably want to make it the
82
default gauges page on your web site. So assuming you are running the 'standard' Cumulus
83
web pages (if not then you can figure all this stuff out for yourself), you will need to
84
edit all the Cumulus supplied template files.
85
86
These files reside in your "<path_to_cumulus>\cumulus\web" folder. You will need to edit
87
each xxxxxT.htm file, and near the bottom change the link from "gauges.htm" to "gauges-ss.htm"
88
(also include the path if you have installed the SS gauges into a sub-folder from you main
89
Cumulus web site).
90
91
Next time Cumulus updates your web site, the links on all your existing pages should now
92
point to the new SS gauges.
93
94
It is as well to leave the original Cumulus gauges page on your site, the new page will direct
95
any really old incompatible browsers back to the original page.
96
97
If you decide on a different 'standard' gauge size, then you need to edit the gauges-ss.css
98
file. By default all the gauges use the ".gaugeSizeStd" class, simply change the width and height
99
settings there.
100
101
You can also remove any HTML elements associated with gauges you will not use as well, again
102
this is not mandatory, the script will remove them dynamically for you.
103
104
Browser Redirects
105
-----------------
106
107
If you want to redirect browsers that do not have scripting enabled, then you will have to
108
do this in the HTML file itself. In the header section add the following code:
109
<noscript>
110
<meta http-equiv="refresh" content="3; url=index.htm"/>
111
</noscript>
112
Obviously with the url changed to where ever you want redirect pointing.
113
114
115
Changing Languages
116
------------------
117
118
To switch statically, you need to edit the "gauges.js" file, and change the line 12
119
var strings = LANG.EN,
120
to
121
var strings = LANG.XX,
122
(where XX is the desired language code).
123
124
To add a new translation, edit the "language.js" file and copy one of the existing sections
125
e.g. English, to the end of the file, changing all the LANG.EN values to LANG.XX (where XX is
126
the code for the new language), and editing all the strings. The zip file contains a
127
language.js file with English, French, German, Dutch, Swedish, Danish, Finnish, Norwegian, Italian,
128
Spanish, and Catalan translations to get you going.
129
130
If you are only going to use one language, then deleting the unused language options and the
131
changeLang() function from the language.js file will speed up the page load time slightly.
132
133
To switch languages dynamically, you need to add script code to your page which sets the LANG
134
object to equal the desired language then call the changeLang() function.
135
e.g.
136
// Dynamic script to change the default language to German
137
changeLang(LANG.DE);
138
139
This will re-label all the gauges, and update the text/radio buttons etc on the web page.
140
141
However, changing the language for the gauges DOES NOT translate the displayed forecast
142
as the text of the message is being supplied by your weather station/software.
143
144
NOTE: If your forecast messages use accented characters (or any character not in the basic 103
145
characters in the LCD font), then I recommend that you disable the digital font on the status/forecast
146
display. Set the following in gauges.js:
147
148
digitalForecast : false,
149
150
Weather Display users have different options for the forecast message to be used. By default the
151
ccrlocal file uses the Davis VP %vpforecasttext% tag. Change this to what suits you best:
152
153
%vpforecasttext% Davis VP forecast
154
%forecasticonword% Words for the (Davis?) forecast icon
155
%dailywarning/forecast% forecast from input daily weather
156
157
158
159
160
Adding Logo's/Custom Images to the Gauge Backgrounds
161
----------------------------------------------------
162
The supplied code contains some commented out instructions to add a small logo to the temperature
163
gauge, and a larger image to the DewPoint gauge. These will probably be removed by most people,
164
they are added to demonstrate how to use this feature. See the comments in gauges.js about
165
removing/adding these logos.
166
167
In order to let the gauge background appear through your images you should make them
168
semi-transparent, which means saving them as PNG files.
169
170
The SteelSeries code will clip your images if they exceed the gauge background area, I suggest you
171
size the images similar to your desired gauge size. The code will resize the image to fit the
172
whole background, so it you want to retain the aspect ratio make your images square!
173
174
Forecast Messages
175
-----------------
176
By default for Cumulus the <#forecastenc> message is displayed which shows either the Cumulus
177
generated forecast or the external station generated forecast depending on how Cumulus is configured.
178
Starting with version 1.9.2 Cumulus has additional forecast message options:
179
<#cumulusforecastenc> - Always displays the Cumulus generated Zambretti forecast
180
<#wsforecastenc> - Always displays the external weather station forecast
181
182
If you wish to use one of these options, then you should edit the "realtimegaugesT.txt" file
183
and replace the '<#forecastenc>' tag with the one of your choice.
184
185
You can of course opt not to display the forecast at all, but display any data available from
186
your weather programs 'tags'.
187
188
189
Removing a Wind Rose and Other Optional Gauges
190
----------------------------------------------
191
From release 2.0 I have integrated the Wind Rose 'gauge' into the standard 'package', from v2.1.0 it is enabled
192
by default. From version 2.5.0 there is also an optional Cloud Base gauge, again enabled by default.
193
To disable the Wind Rose you have to make the following changes...
194
195
1. Edit gauges-ssT.htm/gauges-ss-basic.htm/gauges-ss-basic-inc.php and delete the 'radar' scripts
196
towards the end of the document.
197
<script src="scripts/RGraph.common.core.min.js"></script>
198
<script src="scripts/RGraph.rose.min.js"></script>
199
200
2. Edit gauges.js, and change...
201
showRoseGauge : true,
202
To...
203
showRoseGauge : false,
204
205
That's it, the Wind Rose should now be removed from your page.
206
Note for VWS users the Wind Rose will be automatically disabled, but these users should still remove the
207
scripts from the HTML as above to reduce the page load times.
208
209
To disable the other optional gauges, just edit gauges.js and change the following entries to 'false'...
210
showCloudGauge : true,
211
showUvGauge : true,
212
showSolarGauge : true,
213
214
215
Altering the gauge 'layout' on the page
216
---------------------------------------
217
It is easy to 'move' the gauges around the page to create alternative layouts. By default, there are
218
four rows of gauges laid out like this (letter = optional gauge)...
219
220
* * *
221
* * r r: Wind Rose
222
* * *
223
u s c u: UV-I, s: Solar, c: Cloudbase
224
225
To move the gauges you just need to edit the HTML file and move <div>'s (and their contents) with a
226
class="gauge". Each 'row' is contained within a <div> with a class="row". If you do re-order the
227
gauges, then DO NOT change the "tip_N" numbers, each number is associated with a particular gauge not
228
it's position on the page.
229
230
231
232
Altering the gauge sizes on the page
233
------------------------------------
234
235
From version 2.2.0 the sizes of the gauges is controlled via CSS and longer coded in the gauges.js
236
script. By default all the gauge canvas tags are set to pick up their size from the ".gaugeSizeStd"
237
class in gauges-ss.css file. To change the size of all the gauges, simply edit this class and set the
238
width & height to your required size - the width and height should always be the same.
239
240
You can easily have different sized gauges on the same page, in the gauges-ss.css I have created two
241
additional classes ".gaugeSizeSml" and ".gaugeSizeLrg", (again you can edit the width/height values
242
of these classes to whatever you want), to assign one of these alternative sizes to a gauge, edit
243
the HTML and change (for example)...
244
245
<canvas id="canvas_baro" class="gaugeSizeStd"></canvas>
246
to
247
<canvas id="canvas_baro" class="gaugeSizeLrg"></canvas>
248
249
This would change the Barometer from a 221 pixel gauge, to 261 pixels (using the default values).
250
251
252
Weather Display Users
253
=====================
254
These files will work with WD if you switch the following value in gauges.js:
255
weatherProgram : 0,
256
To...
257
weatherProgram : 1,
258
259
This will make the script use the WD customclientraw.json file rather than the Cumulus realtimegauges.json file.
260
A template for this file suitable for processing by WD is provided in the zip file - weather_server/weather_display/customclientrawlocal.txt
261
262
To process the customclientrawlocal.txt, in WD you need to:
263
* in control panel, webfiles/web page setup, real time ftp setup
264
* see the custom client raw file setup...and tick to create that
265
* make sure the needed customclientrawlocal.txt is in the clientraw folder location
266
267
For Weather Display you should use the provided HTML files gauges-ss-basic.htm, or gauges-ss-basic-inc.php. The file
268
gauges-ssT.htm is designed to be 'processed' by Cumulus before uploading to the web site.
269
270
271
customclientrawlocal.txt
272
------------------------
273
The value for Humidex is set to Celsius by default. You may want to change this
274
tag from %humidexcelsius% to %humidexfaren% if you use Fahrenheit as your temperature
275
scale. (there is no WD tag to report the value in your default scale).
276
277
The value for Cloudbase is set to metres by default. You may want to change this tag
278
from %cloudheightmeters% to %cloudheightfeet%, remember to also change the value for
279
"cloudbaseunit":"m" to "cloudbaseunit":"ft"
280
281
These and the forecast tag (see above)
282
are the only things you should have to edit in the ccr file.
283
284
285
286
Virtual Weather Station (VWS) Users
287
===================================
288
These files will work with VWS if you have set-up VWS to upload the WeatherFlash conditions files
289
(wflash.txt, wflash2.txt). You do not have to purchase WeatherFlash to use these scripts, but
290
just have to set up VWS to upload the files via HTTP or FTP methods. See VWS, Internet, WeatherFlash
291
dialog for setup and use either Server File or Active Server Page to perform the upload with
292
an interval of 10 seconds or so.
293
294
steelseriesVWSjson.php
295
----------------------
296
Configure the steelseriesVWSjson.php file settings area near the top of the file for the
297
location of the WeatherFlash Data/ directory (using relative file addressing), and for your
298
other preferences (units, time zone, etc.).
299
300
In scripts/gauges.js,
301
* change the weatherProgram variable to 2 to indicate VWS is being used.
302
* change the imgPathURL to the relative URL location of the VWS vwsNNN.jpg graphs.
303
* change the realTimeURL_VWS to the relative URL path of the steelseriesVWSjson.php script
304
305
In gauges-ss-basic.htm,
306
* remove the wind rose scripts by deleting the following lines...
307
<script src="scripts/RGraph.common.core.min.js"></script>
308
<script src="scripts/RGraph.rose.min.js"></script>
309
310
Note that VWS does *not* produce data for all the entries to be displayed.
311
The following are missing due to this lack of VWS supplied data:
312
* wind rose display: the display will be disabled by default.
313
* rain chart: the time of last rain is 'n/a'.
314
* all-time min/max barometer pressure: the Barometer gauge will not show red areas up to
315
the all record low pressure and from the record high pressure to the max of the gauge.
316
* some gauges show only current values as the min/max values are not computed by VWS.
317
* the humidex number is not provided by VWS, but computed by the steelseriesVWSjson.php script instead,
318
so there is no humidex graph available.
319
320
(Thanks to Ken True of saratoga-weather.org for the VWS support script)
321
322
323
324
WeatherCat Users
325
================
326
327
Please see the WeatherCat wiki page for instructions: http://wiki.trixology.com/index.php/Steel_Series_Gauges
328
329
330
331
332
Meteobridge Users
333
=================
334
335
Some features of the gauges page are not available, when you configure the program type to "4" the
336
script automatically disables the Wind Rose gauge and the pop-up graphs.
337
338
(Thanks to Ken True of saratoga-weather.org for the Meteobridge support script)
339
340
341
342
343
WView Users
344
===========
345
346
In order to use the wind rose features, you may need to tweak your installation to produce the required
347
data. The supplied file uses the tag <!--dayWindRoseList-->. Please see this thread...
348
https://groups.google.com/d/msg/wview/Yxdy5IS0R6U/RhFv4eUBd-MJ
349
350
351
352
WeeWX Users
353
===========
354
355
Please refer to the separate readme.txt in the weather_server\WeeWX folder.
356
357
358
359
What is 'Long Polling'
360
======================
361
362
HTTP long polling is a technique for only downloading data from the server when it is updated. An outline
363
of the process is below, because it requires action on the web servers part, it requires something like PHP
364
to be running on the web server.
365
366
1. The client requests the webpage from the server using regular http.
367
2. The webpage executes javascript which requests the realtime from the server.
368
3. The server does not immediately respond with the requested file but waits until the file is updated.
369
4. When there is new data available, the server responds with the new file.
370
5. The client receives the new data and immediately sends another request to the server, re-starting the process at step 3.
371
372
Configuring Long Polling
373
------------------------
374
375
Standard long polling is only available for those web sites running PHP. The steps involved are:
376
377
1. First establish the web site using the standard realtime text file for your weather software.
378
2. Edit the long polling PHP file 'realtimegauges-longpoll.php', and set the name and path of your realtime file on the web server:
379
$RealtimeFilename = $_SERVER['DOCUMENT_ROOT'].'/realtimegauges.txt';
380
3. Upload the long polling PHP file 'realtimegauges-longpoll.php' to your web server.
381
4. Edit the gauges.js script on your web server, and enable long polling:
382
config = {
383
...
384
longPoll : true, // if enabled, use long polling and PHP generated data !!only enable if you understand how this is implemented!!
385
386
Then set the path to the long polling PHP file:
387
...
388
realTimeURL_LongPoll: './utils/realtimegauges-longpoll.php', //*** ALL Users: Change to your location of the PHP long poll realtime file ***
389
390
Check that the realtime update interval is set correctly to your realtime interval:
391
...
392
realtimeInterval : 5, //*** Download data interval, set to your realtime data update interval in seconds
393
394
Test it out, it should download the JSON data when the page loads, then every time the file is updated on the server.
395
It is important that you also correctly configure the realtim upload interval, as this is used to determine if the next
396
download request should be queued immediately or delayed a while. PHP by default has a maximum 30 second runtime for
397
scripts, so we do not want to wait for a response longer than that - the script sets the max wait time to 20 seconds.
398
399
400
401
402
Cloud Base Gauge
403
===================
404
405
The cloud base gauge performs some rounding of the displayed values to prevent the display bouncing around too much.
406
407
If the display is in metres, then values below 1000 m are rounded to 10 m, above 1000 m, they are rounded to 50 m.
408
If the display is in feet, then values below 2000 ft are rounded to 50 ft, above 2000 ft, they are rounded to 100 ft.
409
410
411