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