5,838
edits
Today.ini: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
Minor resequencing of page
m (Update category) |
m (Minor resequencing of page) |
||
|
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This page was written for the (legacy) Cumulus 1 software. It has been partially updated to cover MX, but MX continues to change and the information here relates to an old MX release!
If any contributor is willing to update content, so it is more friendly for those using latest release, can they ensure this page is still helping those using older MX releases and the legacy Cumulus software.
</div>
= Introduction =
The files '''today.ini''' and '''[[yesterday.ini]]''' are used by Cumulus to store some counts, plus the Highs and Lows (and their timestamps) for key parameters as reached on each of the two days, for Cumulus 1 these files are where the figures that appear on the main screen are stored.
In Cumulus 2 and 3(MX) these files hold figures that appear on the today/yesterday page of the [[MX Administrative Interface|local interface]] you can view.
==Where are the files stored?==
The files '''today.ini''' and '''[[yesterday.ini]]''' are located in the [[Data folder|"Data" sub-folder]] of the path where your cumulus.exe (or CumulusMX.exe) is installed.
Microsoft Windows Operating Systems, may relocate some files, as explained at [[FAQ#I_can.E2.80.99t_find_my_data_files.21| FAQ on location of data log files]].
= Format of the file =
All '''.ini''' files use a common format as described at [[:Category:Ini_Files]], where some differences between the legacy Cumulus and MX are noted.
Essentially, this format is that square brackets surround section names. The sections (after the first [General]) can be in any order, Cumulus will maintain whatever order the sections are currently in.
Under each section name, there is a list of parameters <code>attribute=value</code>, with one parameter per line. The attribute names are defined by Cumulus, but can appear in any order, the values are stored in the units selected by the Cumulus user. For real (not integer) numbers, the decimal part cannot be easily converted between base 10 (used for display) and the base 2 (used internally by the Cumulus code), and therefore you may see more decimal places than you expect.
For '''today.ini''', it is important to be aware that MX can read a file created by Cumulus 1 (MX can read the time format in the value for '''Timestamp=''' parameter whether it is in Cumulus 1 or MX format), but Cumulus 1 cannot read a file that has been updated by MX.
For readability you can insert blank lines into files '''today.ini''' and '''[[yesterday.ini]]''', Cumulus will not mind. Do not however introduce any punctuation nor change the format of any parameter line.
Remember Cumulus needs to read and update '''today.ini''' throughout the day, so do not attempt to edit it while Cumulus is running, as that could conflict with an edit by Cumulus.
==Typical Sections within file==
As Cumulus is developed it is adding further sections, but the legacy Cumulus by 1.9.4 used the following:
* The [General] section stores current date and time.
* The [Wind} section stores the highest wind speed and highest gust, it holds the sum of wind speeds as wind run, and details for the dominant wind.
* The [Temp], or temperature, section stores the highest and lowest temperature, the sum of all temperatures from every sample (Total), and the number of Samples in that total, the Cumulative Chill Hours total (for the season), and the cumulative Heating and Cooling Degree Days for the current day-so-far.
* The [Pressure], [Humidity], [AppTemp] (for apparent temperature), and [Dewpoint] sections just hold Highs and Lows.
* The [WindChill] section only holds lowest, the [HeatIndex] section only has highest.
* The [Rain] section holds a lot of different parameters, including the Start count that derives most rain outputs, and the LastTip date-time.
Other sections present in 1.9.4 are [ET], [Solar], [NOAA], and [FineOffset] whether these are updated depends on whether your weather station supplies the necessary information, and whether you have set up NOAA reports.
MX adds, amongst others, an additional section '''[Records]''' that contains entries denoting when extreme records were last revised. For example "Alltime=2020-03-06T06:42:13", indicates when the all-time extreme records was last updated. In the example file, there were various extreme records broken at that time on 6 March (lowest temperature, lowest apparent temperature, and greatest wind chill), but none have been broken since.
= Differences between Cumulus 1 and Cumulus MX =
As Cumulus 1 was developed it added further sections to both '''today.ini''' and '''[[yesterday.ini]]'''. As MX is developed, it also is adding further sections. Since both these files are recreated on a daily basis, their content will always be what is defined for the release you are running.
The key difference between all [[:Category:Ini_Files]] for the different flavours is the time-stamps:
* [[File:Badge vMx.png]]Cumulus MX shows date/time in ISO 8601 format of <code>yyyy-MM-ddTHH:mm:ss</code>(using the net specifiers that MX uses).
* Cumulus 2 (no longer available) used UTC time-stamps
* [[File:Badge v1.png]] Cumulus 1 used the format specified in Control Panel for your region settings, for UK that would would typically be <code>day/month/year (space) hour:minute</code>
==When Cumulus is running==
The key difference between Cumulus 1 and MX is the frequency of updating today.ini:
* Mark Crossley code updates this file at [[Standard log files|Standard interval]]
* Steve Loft code updates this file at [[Recent history|Recent history interval]]
When you close Cumulus, it will write the final values for highs and lows and their timestamps to today.ini as part of the close down process.
=End of day actions=
End of day actions happen when Cumulus detects that it is processing weather data for the rollover time [either midnight, or 9am (or 10am) depending on your configuration and season], this might be during the processing of archive data while Cumulus is catching up after it has been restarted, or in normal running when those clock times are reached.
Oversimplifying the process a bit, the contents of today.ini, goes to two places:
# yesterday.ini
# a new line appended onto [[dayfile.txt]]
After that a new today.ini is created.
The three files have a few differences in content, so rolling-over does involve a little editing work:
* for example the 'Total' and 'Samples' values in today.ini become the single 'AvgTemp' in yesterday.ini and dayfile.txt;
* another example is the multiple lines in the [General] section of today.ini shrink to just one item in yesterday.ini (Date) and one item in dayfile.txt (abbreviated date).
When Cumulus is left running, a daily backup of all the files is created as part of this rollover in a subfolder 'daily' of the backup folder. Depending on the release you are running, the files included in the backup may be a snapshot of their content just before rollover, just after rollover, or at the first standard interval after rollover.
=Composite Example of 'today.ini' file=
The minimum content for this file is the "[General]" section. See [[FAQ#I.E2.80.99ve_just_installed_Cumulus.2C_and_it_didn.E2.80.99t_download_all_the_old_data_from_my_weather_station | FAQ here]] for the single reason why you might want to remove all other sections from your file when you are first starting use of Cumulus with a weather station. This is an example made up of composites that may not all be present in an actual file; and an actual file may have the sections in a different order. Because this example is made up of composites, the times shown are not all consistent, in a real file no time anywhere will be later than the time at the top!
*This composite contains time-stamp formats used by Cumulus 1.x.y and Cumulus MX in the few places where they differ. Notes in round brackets () are not part of the file, they simply explain elements of the composite.
*The sections can be in any order; I'm not sure what order Cumulus 1 and Cumulus MX use when they first create this file, but when they recreate this file, the order remains unchanged. So if you do edit this file and that edit leaves the sections in a different order, both versions of Cumulus will from then onwards use that new order.
<pre>
[General]
LTime=01:30
[Dewpoint]
[Solar]
SunshineHours=1.08333301544189 (This is Cumulus 1 example)
SunshineHoursToMidnight=5.80002069473267 (This is Cumulus 1 approach)
HighSolarRad=1048
HighSolarRadTime=09:41
[[FAQ#The_longest_dry.2Fwet_spell_for_this_month.2Fyear_includes_days_from_last_month.2Fyear | ConsecutiveRainDays]], [[FAQ#The_longest_dry.2Fwet_spell_for_this_month.2Fyear_includes_days_from_last_month.2Fyear | ConsecutiveDryDays]];
[[Reports folder|NOAA]]
[[Category:Ini Files]]
=General information=
You can skip the following subsections unless you have a particular need to read them.
== Dealing with rogue values ==
The today file is written to throughout the current day as any new High or Low for the day at reached. If your weather station reports a rogue value, an incorrect update to the High or Low may result. Full details of the impact of this, and how to make corrections, are covered on [[Correcting Extremes]] page. Here it is sufficient to say it is worth looking in the diagnostics, to see if you can spot when the problem occurred:
* [[File:Badge vMx.png]] [[MXdiags folder]]
* [[File:Badge v1.png]] [[Diags_folder]]
'''Notes:'''
* The only today.ini entry that Cumulus allows you to edit is today's rain (see next subsection)
* If you do decide to edit 'today.ini' outside Cumulus, you must close Cumulus down first!
* Think carefully, whether it is easier to wait until next day, when the entry is in dayfile.txt for which cumulus does provide an editor
=== Editing rainfall in today.ini within Cumulus ===
This applied to Cumulus 1 and Cumulus MX. Both contain an editor for 'today's rain'.
*Normally you would not need to edit today.ini, as if you wait until the next day, Cumulus provides (with its Edit menu) an easy way to amend the stored extremes for this month, this year, monthly records, and all-time. The wrong figures may be displayed on the yesterday screen for this next day, but yesterday.ini can be edited more easily!
* You may wish to [[FAQ#.28Invented_rain.29_Error_in_today.27s_total | edit the rain data]] if there has been a quirk in your weather station sensor for rain (or in figure reporting) during the day and the figure is abnormally inflated (or indeed under-reported).
*The stored rainfall today start ''count'' value in today.ini may be edited via ''Today's rain'' screen on the '''Edit''' menu.
**This edit purely changes the ''Start='' line within the '[rain]' section, i.e. changes the ''Total rainfall counter (content depends on weather station type, might be rainfall total so far this year; it is not intended to be useful in itself, it may vary for no apparent reason)'' value that is stored within today.ini.
**Consequently, using this feature creates a sudden increase or decrease in the 'Total rainfall counter (content depends on weather station type, might be rainfall total so far this year)' figure stored the next time Cumulus updates its [[Standard_log_files |log file]] for the current month.
**You may still need to manually edit (using an external text editor) the other parameters within that [Rain] section to correct the other rain statistics held in 'today.ini':
***last tip time-stamp ("LastTip=")
***highest rainfall rate so far today and time-stamp ("High=" and "HTime=")
***hourly high amount and time-stamp ("HourlyHigh=" and "HHourlyTime=")
***consecutive wet/dry days ("ConsecutiveRainDays=" and "ConsecutiveDryDays=") - remember these counts are to last roll-over, they exclude today
**If you do edit any parameter values remember to ensure the replacement is in exactly same format as before (whether integers, real numbers or a particular format for time-stamps)
*This edit does not affect any derived rainfall values (such as totals for the month or year that are displayed (and output via web-tags)), unless you subsequently close and restart Cumulus the same day to force recalculation of the longer period totals.
* You don't need to restart Cumulus after a change to today's rain to ensure that [[dayfile.txt]] has correct line added at next roll-over.
* This edit does not change any lines already in the [[Monthly_log_files |log file]] for the current month, so any process you have that reads those will read some wrong values and this can distort for example graphs attempting to portray rainfall within a day.
** Although ''rainfall since midnight'' is stored in the last field of the Cumulus [[Monthly_log_files |log file]] for the current month, manually editing there will not help as Cumulus does not read it from there. Cumulus works out rainfall since midnight by looking at the entry at (or first just after) midnight, and that past line has not been updated.
** If you want to correct rainfall since midnight there because you have processes that read this file, then remember you can only safely edit (using a specialist CSV editor, a good text editor, or a programmer's editor like 'Notepad++) that file with Cumulus stopped, as Cumulus demands full locked access to this file for periodic updating.
** Editing this file is difficult,
*** If you want to decrease the actual rain, you need to increase the rain counter, and vice versa
*** You have to work backwards through time working out the alteration to the rain counter for the actual rainfall increment, in the period since the preceding entry.
=== Editing today.ini or yesterday.ini outside Cumulus ===
If the rogue value is not rainfall, then you might need to edit today.ini or yesterday.ini using an external editor. '''Note:''' If you do edit either of these files, you must close Cumulus down first!
The files are text files, so edit using any plain text editor. The format consists of a number of sections (section title is delimited by [ ]), and a number of parameters (consisting of attribute name, an equals sign and a value). Blank lines can be included for readability, they are ignored in these .ini type log files. All values have to be specified in the correct format, so ensure new entry matches old format.
== Restart and Catch-up ==
If you restart Cumulus during the day it will read the ''today.ini'' file at startup, so it can resume tracking extremes of the key parameters starting from latest stored values in today.ini. On restart it also writes a backup of today.ini (and some of the other Cumulus files) into the sub folder 'backup' below the folder with the cumulus.exe. Because Cumulus software does it changes first in an internally stored area before writing out to today.ini, if you try to edit today.ini while Cumulus is running, you may find your edit is lost next time Cumulus itself outputs an updated file, even if your edit is not lost, you may lose a Cumulus edit by saving your own edited version to overwrite the Cumulus edit. So never edit without stopping Cumulus first. (yesterday.ini is created at rollover and then not updated, so that file can be edited while Cumulus is running provided you are several minutes away from rollover time).
If your weather station type supports it, while Cumulus is doing a catch-up, after being restarted, ''today.ini'' will be updated with revised highs and lows as it processes the station's memory; and if necessary it will do a roll-over as it processes the readings for the relevant time (this roll-over process takes a bit longer to create the daily backup than that when Cumulus is left running). As explained on support forum, there can be problems if Cumulus is started/stopped just before or just after (i.e. close to) its roll-over time, the problems were worse for earlier versions of Cumulus 1, but have been reduced in newer builds of C1 and therefore for MX. You should not start or stop it within whatever time you have set as interval between logs.
== Changes to this file at particular releases ==
''This section may not be a complete history, and may not be kept up to date; so don't take it as authoritative''
*3.11.0 build 3129 (released on 7 May 2021)
**Fix: End of day backup now always runs at rollover, so like most releases of the legacy software, the stored file represents the true end of day position.
*** For example in the '''[General]''' section, the ''Date'' (calendar date) and ''Timestamp'' attributes will relate to when it was last updated, but the three '''Current'' attributes will relate to the meteorological date just ended.
*** For the today.ini in the backup/daily folder, last update time-stamp will indicate time as at one update cycle before end of day, but file last modified will show that was at end-of-day
**New: Added (to [Temp]) GrowingDegreeDaysThisYear1=, and GrowingDegreeDaysThisYear2=.
*3.7.0 - build 3089 (released on 28 July 2020)
**Canadian Humidity Index (Humidex) added for highest extreme monitoring in today.ini (and other longer period extreme log files)
*Release 3.6.6 build 3082 (released on 1 June 2020)
**Values in the file had been stored (in all previous builds) using 15 decimal places (because of difficulty in representing decimal parts of numbers in binary), from this release revised so all values stored using 17 significant figures
*Release 3.6.3 - build 3079 (released on 21 May 2020)
** Fix long standing problem with today.ini becoming corrupted when Microsoft Windows is shutdown
* Release 3.6.0 build 3076 (released on 4 May 2020)
** added '''Feels Like''' to daily high and low extremes monitored in today.ini (and other longer period extreme log files)
*From version 1.9.4 build 1089 to release 3.10.5 build 3122
** The '''today.ini''' stored in the daily backup contains the position as at '''start of day''' (or in specified older MX releases, up to one UPDATE interval later), so it does not contain any information (except Cumulative Chill Hours) that relates to day that has just ended.
*Up to version 1.9.4 build 1088 (released 28 Jan 2014)
**The '''today.ini''' stored in the ''cumulus\backup\daily\FOLDER_NAME'' ((where FOLDER_NAME is based on date and time of creation) represented the end of day (including on last day of month) extremes
*version 1.8.9 (released on 31st March 2010)
**Fix problem with month names (timestamp in today.ini) using ''short date format''
* version 1.8.6 (released on 14th April 2009)
**Don't write today.ini unless station contacted
*version 1.8.5 (released on 12th February 2009)
**Fix wrong times for some of today's extremes
*Not documented
** It is believed that today.ini may have been introduced at version 1.4
*Version 1.0 27th January 2004 First release
**Only dealt with current conditions handling, there was no tracking of daily extremes
| |||
