Cumulus Wiki

Today.ini

Revision as of 09:38, 16 March 2020 by Sfws (talk | contribs) (→‎Composite Example of 'today.ini' file)

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 are source for figures that appear on the main screen, for Cumulus 2 and 3(MX) they appear on the dashboard you can view. These files are normally located in the "Data" sub-folder of the path where your Cumulus.exe is installed. See FAQ on location of data log files for where else to look.

Sections in yesterday.ini

See example at end of page. Each section is headed with something in square brackets [], then a number of parameters in format "attribute=value".

Sections in today.ini

The today.ini contains a number of sections, also headed with something in square brackets [], then a number of parameters in format "attribute=value". 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 minute (Total), and the number of Samples in that total, the Cumulative Chill Hours in the season, and the cumulative Heating and Cooling Degree Days for the current day. The [Pressure], [Humidity], [AppTemp], or apparent temperature, and [Dewpoint] sections just hold Highs and Lows. The [WindChill] section only holds lowest, the [HeatIndex] section only has highest, while 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 always present are [ET], [Solar], and [FineOffset] whether these are updated depends on whether your weather station supplies the necessary information. All today.ini also have [NOAA] which will only be populated if you have set up NOAA reports, if you have it shows the file names of the latest monthly and yearly reports.

Differences between Cumulus 1 and Cumulus MX

All the sections listed above are found in both versions of the software, and for all except [FineOffset] the contents are identically formatted. For the exception, Cumulus 1 uses real values with 5 digits before the decimal place and several after to represent time as fractional Days Since 30 Dec 1899; while Cumulus MX shows time in ISO 8601 format of "yyyy-MM-ddTHH:mm:ss" (using the net specifiers that MX uses). MX adds an additional section [Records] that contains entries like "Alltime=2020-03-06T06:42:13", in that case it indicates that various all-time records (lowest temperature, lowest apparent temperature, and greatest wind chill, in this example) were set on 6 March, but none have been broken since.

When Cumulus is running

The highs and lows, as held in memory while Cumulus is running, are constantly re-written to today.ini. At the end of a day [either midnight, or 9am (or 10am) depending on your configuration and season], the final values and timestamps written to today.ini file are rolled-over. Many are written as a new line appended onto dayfile.txt and most become values and timestamps in yesterday.ini; then 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. Equally, if you close Cumulus during the day it will write the final values for highs and lows and their timestamps to today.ini as part of the close down process.

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 log 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.

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, but details of that update should be in the Diags, so look there to see what correction will be required to eliminate the rogue value. 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!

Notes:

  • If you do decide to edit 'today.ini' outside Cumulus, you must close Cumulus down first!
  • Don't try to edit 'yesterday.ini' within a few minutes before or after Cumulus performs a rollover (either at rollover time or on restarting if it was not running at rollover time).

Editing rainfall in today.ini within Cumulus

This applied to Cumulus 1 and Cumulus MX. Both contain an editor for 'today's rain'.

  • You may wish to 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 log file for the current month.
    • You 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 new line added at next roll-over.
  • This edit does not change any lines already in the 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 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, because you have to work backwards through time working out what needs to be subtracted from the rain counter value from what increment the old value had from the one immediately earlier.

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 properties (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, see example below.

Composite Example of 'today.ini' file

The minimum content for this file is the "[General]" section. See 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. I discovered this as I have a PHP script that reads today.ini from the backup directory and it failed because I had changed the order of sections from the order I had previously coded in my script when I copied part of my today.ini from a nearby site (the Chill Hours figure shown represents a season, but I have just started at a new location so I adjusted my figure to agree with his). Morale of this story is don't make assumptions when writing a script, make it cope with all possibilities!
[General]
Date=29/09/2019
Timestamp= (the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")
CurrentYear=2019
CurrentMonth=9
CurrentDay=13

[Wind]
Speed=10.7008972167969
SpTime=10:09
Gust=22.0114517211914
Time=08:42
Bearing=90
Direction=E
Windrun=63.1526298522949
DominantWindBearing=317
DominantWindBearingMinutes=1041
DominantWindBearingX=-3914.11743164063
DominantWindBearingY=4215.82763671875

[Pressure]
Low=1014.89996337891
LTime=11:13
High=1018.79998779297
HTime=00:06

[Rain]
High=0
HTime=00:00
Start=1923.59997558594         
Yesterday=0                    
LastTip=2012-09-14 10:48
HourlyHigh=0
HHourlyTime=00:00
ConsecutiveRainDays=2
ConsecutiveDryDays=0
RG11Today=20

[ET]
Annual=1148.2578125
Startofday=1147.24182128906

[Temp]
Low=8.30000019073486
LTime=01:16
High=16.8999996185303
HTime=11:41
Total=7500.697265625
Samples=714
ChillHours=3147.15673828125
HeatingDegreeDays=5.34738397598267
CoolingDegreeDays=0.502222061157227

[HeatIndex]
High=16.8999996185303
HTime=11:41

[AppTemp]
Low=5.0417857170105
LTime=01:30
High=15.0359125137329
HTime=11:52

[WindChill]
Low=6.39816427230835
LTime=01:30

[Dewpoint]
Low=5.30104923248291
LTime=00:52
High=10.7219848632813
HTime=11:38

[Humidity]
Low=65
High=88
LTime=11:45
HTime=06:06

[Solar]
SunshineHours=1.08333301544189
SunshineHoursToMidnight=5.80002069473267
HighSolarRad=1048
HighSolarRadTime=09:41
HighUV=7.40000009536743
HighUVTime=09:41
SunStart=0

[NOAA]
LatestMonthlyReport=NOAAMOSep2012.txt
LatestYearlyReport=NOAAYR2012.txt

(The above section will look like the one below if NOAA reporting has not been set up)

[NOAA]
LatestMonthlyReport=
LatestYearlyReport=

[FineOffset] (this is MX format when not a Fine Offset station)
FOSensorClockTime=0001-01-01T00:00:00
FOStationClockTime=0001-01-01T00:00:00

[FineOffset] (this is when using a Fine Offset station)
FOSensorClockTime=(the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")
FOStationClockTime=(the format here is different for Cumulus 1 e.g. "29/09/2019 09:50:00" and Cumulus MX e.g. "2019-09-29T09:50:00")

(this last section only appears if you are using Cumulus MX)
[Records]
Alltime=2020-03-06T06:42:13

Example yesterday.ini

See Average_temperature for one key transformation between today.ini and yesterday.ini, no ET parameters are retained, plus there are some wind and some rain parameters not copied from today.ini to yesterday.ini. This log file is exactly same in Cumulus 1, 2, and 3 (MX).

NOTE: Yesterday's total rainfall from weather station is stored in today.ini, but yesterday's total rainfall from RG-11 sensor is stored in yesterday.ini. 

[General]
Date=28/04/2011

[Wind]
Speed=7.2
SpTime=09:00
Gust=15.9
Time=12:15
Bearing=315
Direction=NW
Windrun=35.3391151428223
DominantWindBearing=230

[Temp]
Low=5.6
LTime=05:34
High=21.0
HTime=14:46
HeatingDegreeDays=3.76118206977844
CoolingDegreeDays=0.702986478805542
AvgTemp=12.4447975158691

[Pressure]
Low=29.72
LTime=09:00
High=29.85
HTime=22:12

[Rain]
High=1.2
HTime=00:34
HourlyHigh=0.899999976158142
HHourlyTime=02:04
RG11Yesterday=0

[Humidity]
Low=49
High=99
LTime=14:34
HTime=00:34

[Solar]
SunshineHours=0
HighSolarRad=0
HighSolarRadTime=09:00
HighUV=0
HighUVTime=09:00

[HeatIndex]
High=21
HTime=14:46

[AppTemp]
Low=3.98110413551331
LTime=05:34
High=21.0052318572998
HTime=15:50

[WindChill]
Low=5.59999990463257
LTime=05:34

[Dewpoint]
Low=5.4555492401123
LTime=05:34
High=11.6547174453735
HTime=09:03

Cross-references for explanations of key parameters

Bearing and Direction, Windrun;

Temp, Total and Samples, Humidity, Heating degree days, Cooling degree days, AppTemp, Heat index, wind chill, Chill hours, Dewpoint;

Rain, ConsecutiveRainDays, ConsecutiveDryDays;

NOAA.

Retrieved from "https://www.cumuluswiki.org/index.php?title=Today.ini&oldid=4701"