Cumulus Wiki

Realtime.txt: Difference between revisions

Realtime.txt (view source)

Revision as of 07:31, 19 July 2021

1,410 bytes added ,  07:31, 19 July 2021
m
Re-sequence page, following support forum comments, making the list of fields come first, and rewriting customisation, adding links to other information on page
m (→‎List of fields in the file: Correction: list had been changed for MX, but said it was for 1.9.4, now clarifies the change at 3.7.0)
m (Re-sequence page, following support forum comments, making the list of fields come first, and rewriting customisation, adding links to other information on page)
Line 1: Line 1:
= List of fields in the file =


{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}{{Version badge 1}}This page applies to both flavours.[[Category:Cumulus MX]][[Category:Cumulus Files]][[Category:MX txt Files]][[Category:Cumulus 1]]
{{Template:Version badge Mx}}{{Version badge 1}}This Wiki page applies to both flavours.[[Category:Cumulus MX]][[Category:Cumulus Files]][[Category:MX txt Files]][[Category:Cumulus 1]]
 
This page was created for Cumulus 1, it has had some updates for MX, but not been kept up to date.
 
= Introduction =
 
*'''realtime.txt''' is a text file with a single line of ''space'' separated values.
*It contains a list of key values of the sensors, and is re-created frequently.
*After creation, it is usually set to upload to your website, and used to produce near instant readings.
*The realtime.txt file is NOT a log file and is constantly replaced. It does not therefore contain any historic data.
** Although this file is technically not a 'log file', it is optionally automatically produced by Cumulus, and follows a similar format to the other Log files.
 
 
== Where is the file used in Cumulus 1 ==
[[File:Badge v1.png]]: the following applies only to the legacy Cumulus.
 
The realtime.txt is used only in Cumulus 1 in the following areas:
*the 2 wind graphics at the bottom of the standard 'gauges' page on the website produced by Cumulus
*[[CumulusRealtime]] -- the new application developed in [http://silverlight.net/ SilverLight]
*The [[WeatherConsole]] and [[Sidebar gadget]] [[:Category:AddOns|addons]]
 
==Enabling this file in Cumulus 1==
[[File:Badge v1.png]]: the following applies only to the legacy Cumulus.
 
[[Image:CumulusInternetSettingsScreen.png|thumb]] This is the legacy screen that controls production of this file. Standard Cumulus 1 only uses this file for the optional real-time wind gauges (see [[#Where is the file used]]). It exists as one way that current Cumulus derivatives can be supplied to [[Category:User Contributions|third party additions]], and its content can be tailored to the needs of whatever you choose.
*The 'interval' sets how often Cumulus produces the file, to set that interval, click on the 'Configuration' menu then 'Internet', then set parameter labelled 'Realtime interval' by entering an integer number of seconds.
*Optionally the file can be uploaded to your [[Website_setup|externally-hosted web site]], if you want this (and it is usual) select all 3 selectors:
**Enable Realtime
**Enable Realtime FTP
**Realtime.txt FTP
*The uploading interval is the same as the file creation interval.
 
== Special note to Fine Offset/EasyWeather users ==
Weather stations which come shipped with the EasyWeather software should consider the real-time updating with care.
 
The station only updates every 48 (solar is only updated every 60) seconds, so aim for a real-time interval of around 30 seconds, that way a visitor knows not to expect updates too often but you also allow Cumulus to catch up to two updates within a minute (depending on when the first and second 48 second update came to Cumulus).
 
== Bandwidth Considerations ==
The file Cumulus uploads is less than 1024 bytes in size, but for the calculation we will assume 1024 bytes, and typically this is (for non Fine Offset stations) updated every 5 to 15 seconds depending on your 'Realtime interval' setting above.
 
Most internet providers now place a limit on the amount of Bandwidth you can consume each month. Bandwidth is a figure representing the data you can upload and download. Doing such a regular upload will impact on your allowance.
 
During a month (31 days) the upload process will consume roughly 175 Mbytes of bandwidth -- this is a tiny consideration as usually bandwidth restrictions from your provider start in the Gigabytes (Gb) range, not Megabytes (Mb).
 
On top of your internet connection bandwidth restrictions, you may also have bandwidth caps on your web server so this same figure should be considered for your web server.


= Recreating the file using web tags in C1 =
The list below represents the MX field list.  
[[File:Badge v1.png]]: the following applies only to the legacy Cumulus.


'''Note:''' that the built-in realtime.txt always uses a 'dot' decimal character (and so is JavaScript/PHP 'safe'), any web tag version will use your host computers localisation for decimals. [There are some [[Webtags#No_Commas|<#RCxxx>]] web tags available but they do not cover all the required values].
The final 1.9.4 version of Cumulus, (and releases of MX before 3.7.0) omit the final field shown below.
 
For historic interest, old versions of Cumulus 1 had fewer fields; although the table does not indicate the version at which each field was added, you can click the '''History''' tab and look at the early edits.
= Recreating the file using web tags in MX =
[[File:Badge vMx.png]] The following applies only to MX.
 
 
'''Note:''' ''from b3075 onwards, all decimal tags now support the "rc=y" parameter - see below.''
 
To ensure decimal compatibility across systems use a js construct such as:
 
  var rt = realtime.split(" ");
  var temp = +rt[2].replace(',','.');
 
when referring to decimal values in the constructed file.
 
 
For releases after b3074 web tags now accept the "rc=y" parameter, so if your locale uses a comma decimal you must add this parameter to all the web tags that produce decimal values
 
''(this is one complete line, although it may appear on this page as two or more due to screen width restrictions)''  
 
:<code><#date format=dd/mm/yy> <#timehhmmss> <#temp rc=y> <#hum> <#dew rc=y> <#wspeed rc=y> <#wlatest rc=y> <#bearing> <#rrate rc=y> <#rfall rc=y> <#press rc=y> <#currentwdir> <#beaufortnumber> <#windunit> <#tempunitnodeg> <#pressunit> <#rainunit> <#windrun rc=y> <#presstrendval rc=y> <#rmonth rc=y> <#ryear rc=y> <#rfallY rc=y> <#intemp rc=y> <#inhum> <#wchill rc=y> <#temptrend rc=y> <#tempTH rc=y> <#TtempTH> <#tempTL rc=y> <#TtempTL> <#windTM rc=y> <#TwindTM> <#wgustTM rc=y> <#TwgustTM> <#pressTH rc=y> <#TpressTH> <#pressTL rc=y> <#TpressTL> <#version> <#build> <#wgust rc=y> <#heatindex rc=y> <#humidex rc=y> <#UV rc=y> <#ET rc=y> <#SolarRad> <#avgbearing> <#rhour rc=y> <#forecastnumber> <#isdaylight> <#SensorContactLost> <#wdir> <#cloudbasevalue> <#cloudbaseunit> <#apptemp rc=y> <#SunshineHours rc=y> <#CurrentSolarMax> <#IsSunny> <#feelslike rc=y></code>
 
= List of fields in the file =
Remember that which fields you see, depends on which version of Cumulus you are running. The list below represents the MX field list. The final 1.9.4 version of Cumulus, omits the final field shown below.
{| border="1" class="wikitable"
{| border="1" class="wikitable"
|-
|-
! style="width:60px" | Field #
! style="width:60px" | Field number
! style="width:80px" | Example  
! style="width:80px" | Example content
! style="width:450px" | Description  
! style="width:450px" | Description  
! style="width:90px" | Equivalent [[Webtags]]
! style="width:90px" | Equivalent [[Webtags|web tag]] if your locale/region uses decimal points<br> See [[#MX web tags]] for equivalents in latest MX releases.
|-
|-
| 1  
| 1  
Line 376: Line 310:
|}
|}


== Example of the file ==


= Explaining the file =
Cumulus optionally generates this file, it represents one way that current Cumulus derivatives can be supplied to any [[:Category:User Contributions|third party additions]] you use, or your own external purposes.
Two examples taken from third party [[:Category:AddOns|addons]]:
* [[WeatherConsole]]
* [[Sidebar gadget]]
Standard Cumulus 1 can use this file for its optional real-time wind gauges functionality (see [[#Where is the file used in Cumulus 1]]).
There are two key points to understand about the source for generation of the file:
#First is that a [[Cumulus template file]] is held internally in the Cumulus code that can generate this file with some standard content as [[#List of fields in the file|listed here]]
# Second is that this internal template, regardless of any locale (or region) settings, always generates the file so that it is readable by [[PHP#Incorporating_Script|script languages]] that expect a full stop to separate the integer part of any real number from the decimal part of that real number.
Information about the default generated file:
* As hinted above, the generation of the file requires you to set various options, see [[#Generation of this file]]
* The '''realtime.txt''' is generated as a text file with a single line of ''space'' separated values.
* The file contains a list of key values of the sensors
* The file is intended to be re-created frequently.
* The file is usually set to upload to your website, where it might be used as a source of near instant readings.
* The realtime.txt file will never contain any extreme records, nor any daily (or longer period) summaries, nor any historic data.
==Creating a customised real time file==
Some users, and some third-party supplied web pages, require fewer, or more, fields than those provided in the standard '''realtime.txt''' file.
Arranging this is easy, the content of the file that Cumulus uploads to an external site can be tailored to the needs of whatever you choose.
All you need to do is create your own [[Cumulus template file]], sometimes called ''realtime-xT.txt'' (to indicate it is an e''X''tra file, a ''T''emplate file and is related to ''realtime''.txt), you can place this file in the [[web folder]], and ask Cumulus to process that file for you:
* [[File:Badge v1.png]]
*# Create the template file picking the web tags you want to include from:
*#*  If you use decimal commas, the list [[Webtags#CURRENT_CONDITIONS:|here]]
*#* If you use decimal points, the list [[Webtags#Current_Conditions|here]]
*# Arrange for the processing and uploading by using the Cumulus Configuration|Internet|Files dialog.
*#* Type in the name you have used for your template file in ''Local Filename''
*#* Tick the ''Process?'' checkbox,
*#* Tick the ''Realtime?'' checkbox,
*#* Finally, supplying a remote path and filename that you want created remotely, you can call it "realtime.txt" after the path name if you like
* [[File:Badge vMx.png]] From build 3075 onwards, all decimal web tags now support the "rc=y" modification parameter.
*#* Create the template file based on the list of web tags in the code snippet below. If you are unsure what they represent, look [[Webtags#Current_Conditions|here]].
*#* Use the '''Extra web files''' page in the [[MX_Administrative_Interface#Extra_Web_Files|interface]], follow the instructions in that link, ticking the ''Process?'' checkbox, and the ''Realtime?'' checkbox
===MX web tags===
''(this is one complete line, although it may appear on this page as two or more due to screen width restrictions)''  
''(this is one complete line, although it may appear on this page as two or more due to screen width restrictions)''  


<br> <tt>18/10/08 16:03:45 8.4 84 5.8 24.2 33.0 261 0.0 1.0 999.7 W 6 mph C mb mm 146.6 +0.1 85.2 588.4 11.6 20.3 57 3.6 -0.7 10.9 12:00 7.8 14:41 37.4 14:38 44.0 14:28 999.8 16:01 998.4 12:06 1.8.2 448 36.0 10.3 10.5 13 0.2 14 260 2.3 3 1 1 NNW 2040 ft 12.3 11.1 420.1 1 13.6</tt>
:<code><#date format=dd/mm/yy> <#timehhmmss> <#temp rc=y> <#hum> <#dew rc=y> <#wspeed rc=y> <#wlatest rc=y> <#bearing> <#rrate rc=y> <#rfall rc=y> <#press rc=y> <#currentwdir> <#beaufortnumber> <#windunit> <#tempunitnodeg> <#pressunit> <#rainunit> <#windrun rc=y> <#presstrendval rc=y> <#rmonth rc=y> <#ryear rc=y> <#rfallY rc=y> <#intemp rc=y> <#inhum> <#wchill rc=y> <#temptrend rc=y> <#tempTH rc=y> <#TtempTH> <#tempTL rc=y> <#TtempTL> <#windTM rc=y> <#TwindTM> <#wgustTM rc=y> <#TwgustTM> <#pressTH rc=y> <#TpressTH> <#pressTL rc=y> <#TpressTL> <#version> <#build> <#wgust rc=y> <#heatindex rc=y> <#humidex rc=y> <#UV rc=y> <#ET rc=y> <#SolarRad> <#avgbearing> <#rhour rc=y> <#forecastnumber> <#isdaylight> <#SensorContactLost> <#wdir> <#cloudbasevalue> <#cloudbaseunit> <#apptemp rc=y> <#SunshineHours rc=y> <#CurrentSolarMax> <#IsSunny> <#feelslike rc=y></code>
 
 
== Different interval or different file name ==
 
Occasionally there is a requirement from some users to create a copy of the realtime.txt file and have it posted to a location at the normal Cumulus web update interval rather than the real time interval, or perhaps because a filename other than realtime.txt is required.
 
Simply follow a variant on the instructions above.
* If you want the normal web update interval, don't tick the ''Realtime?'' checkbox.
* If you want a different filename, simply change what you put for ''Remote filename''.
 
=Generation of this file=
 
This is optional functionality, the default (in all flavours of Cumulus) is not to generate this file.
 
==Enabling generation of this file in MX==
 
The Settings pages of MX are being drastically rewritten as the software is developed.
 
Indeed the way of selecting generation of this file is due to change in the next release of MX as I type this, so specific instructions are not included here.
 
In general you need to make three selections:
# You need to enable the timer in MX that does actions at a real time interval.  
# You need to configure (as a number of seconds) how frequently that timer triggers the actions
# You need to enable the file transfer (or if available, the copy) process that gets files uploaded onto an external (e.g. web) site
# You need to enable the generation of this specific file
 
==Enabling generation of this file in Cumulus 1==


[[Image:CumulusInternetSettingsScreen.png]] This is the legacy screen that controls production of this file.
*The 'interval' sets how often Cumulus produces the file, to set that interval, click on the 'Configuration' menu then 'Internet', then set parameter labelled 'Realtime interval' by entering an integer number of seconds.
*Optionally the file can be uploaded to your [[Website_setup|externally-hosted web site]], if you want this (and it is usual) select all 3 selectors:
**Enable Realtime
**Enable Realtime FTP
**Realtime.txt FTP
*The uploading interval is the same as the file creation interval.


=== Alternative content ===
== Bandwidth Considerations ==


Some users, and some third-party supplied web pages, require a different set of fields to those provided in the standard realtime.txt file. In these cases, an alternative file, sometimes called realtime-xT.txt is set up in the web folder, processed and uploaded using the Extra Files feature.
The file Cumulus (1 or MX) uploads is less than 1024 bytes in size, but for the calculation we will assume 1024 bytes, and typically this is (for non Fine Offset stations, see [[#Special note to Fine Offset/EasyWeather users]]) updated every 5 to 15 seconds depending on your 'Realtime interval' setting above.
 
Most internet providers now place a limit on the amount of Bandwidth you can consume each month. Bandwidth is a figure representing the data you can upload and download. Doing such a regular upload will impact on your allowance.
 
During a month (31 days) the upload process will consume roughly 175 Mbytes of bandwidth -- this is a tiny consideration as usually bandwidth restrictions from your provider start in the Gigabytes (Gb) range, not Megabytes (Mb).
 
On top of your internet connection bandwidth restrictions, you may also have bandwidth caps on your web server so this same figure should be considered for your web server.
 
 
= Where is the file used in Cumulus 1 =
 
NOTE: Although MX can optionally generate the file, there is no functionality included in MX that will read this file for any purpose.
 
[[File:Badge v1.png]]: The 2 wind graphics added at the bottom of the example 'gauges' page in the web template set produced by Cumulus 1 were developed in [http://silverlight.net/ SilverLight] and they need data obtained by reading this file as part of [[CumulusRealtime|developing real time]] functionality.
 
= Special note to Fine Offset/EasyWeather users =
 
Weather stations which come shipped with the EasyWeather software should consider carefully how they use the real-time updating.  
 
The station only updates every 48 (solar is only updated every 60) seconds, so aim for a real-time interval of around 30 seconds, that way a visitor knows not to expect updates too often but you also allow Cumulus to catch up to two updates within a minute (depending on when the first and second 48 second update came to Cumulus).  


=== Different interval or different file name ===


Occasionally there is a requirement from some users to create a copy of the realtime.txt file and have it posted to a location at the normal Cumulus web update interval rather than the realtime interval, or perhaps because a filename other than realtime.txt is required. This can be achieved by creating a template file using the web tags below, and referencing this in the Cumulus Configuration|Internet|Files dialog. Ticking the 'Process?' checkbox, and supplying a remote filename will create this copy of the realtime.txt file.
= Example of the file =


''(this is one complete line, although it may appear on this page as two or more due to screen width restrictions)''  
''(this is one complete line, although it may appear on this page as two or more due to screen width restrictions)''  


:<code><#date format=dd/mm/yy> <#timehhmmss> <#temp> <#hum> <#dew> <#wspeed> <#wlatest> <#bearing> <#rrate> <#rfall> <#press> <#currentwdir> <#beaufortnumber> <#windunit> <#tempunitnodeg> <#pressunit> <#rainunit> <#windrun> <#presstrendval> <#rmonth> <#ryear> <#rfallY> <#intemp> <#inhum> <#wchill> <#temptrend> <#tempTH> <#TtempTH> <#tempTL> <#TtempTL> <#windTM> <#TwindTM> <#wgustTM> <#TwgustTM> <#pressTH> <#TpressTH> <#pressTL> <#TpressTL> <#version> <#build> <#wgust> <#heatindex> <#humidex> <#UV> <#ET> <#SolarRad> <#avgbearing> <#rhour> <#forecastnumber> <#isdaylight> <#SensorContactLost> <#wdir> <#cloudbasevalue> <#cloudbaseunit> <#apptemp> <#SunshineHours> <#CurrentSolarMax> <#IsSunny> <#feelslike></code>
<br> <tt>18/10/08 16:03:45 8.4 84 5.8 24.2 33.0 261 0.0 1.0 999.7 W 6 mph C mb mm 146.6 +0.1 85.2 588.4 11.6 20.3 57 3.6 -0.7 10.9 12:00 7.8 14:41 37.4 14:38 44.0 14:28 999.8 16:01 998.4 12:06 1.8.2 448 36.0 10.3 10.5 13 0.2 14 260 2.3 3 1 1 NNW 2040 ft 12.3 11.1 420.1 1 13.6</tt>
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/9439"