5,838
edits
Cumulus.ini (preserving history): Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
no edit summary
mNo edit summary |
|||
|
=History of this page=
This page was created for the legacy Cumulus 1 software (e.g. 1.9.4). When a beta version of Cumulus 1 was available, any parameters specific to that beta appeared in [[Cumulus.ini_(Beta)]]. That beta page was then briefly used for Cumulus 2. Finally, that beta page was used for Cumulus 3 (the MX beta).
This was the position when Steve Loft ceased his involement with Cumulus. This page related to Cumulus 1 and the beta page was for MX.
When Mark Crossley brought MX out of beta, MX was basically using a sub-set of the legacy parameters – so it was possible for this single page to cover both Cumulus 1 and MX.
The rapid development of MX by the new developer, made MX start to diverge from Cumulus 1, and this page had to be redesigned to cope, by introducing sub-sections (Cumulus 1 only, MX only, and both).
However, MX then started to diverge from earlier MX releases. It was impossible for this page to show information for the legacy software, for early MX releases, and for later MX releases. As MX diverged again, it was time to start splitting this page.
The content relating to the legacy software (e.g. 19.4) has been moved to [[Cumulus.ini_(Cumulus_1)|this page]].
The content relating to releases 3.0.0 to 3.7.x has been moved to [[Cumulus.ini(MX_3.0.0_to_3.9.7)|this page]] where it is hoped someone will document the various changes from 3.8.0 to 3.9.7, as currently they are not documented anywhere.
The past history for both those two new pages remains available via the history tab on this page.
To conclude, in the past the content on this page was arranged assuming people were editing the file directly.
(In earlier releases, "read-only" settings were made directly in the "Cumulus.ini" file, while "read-write" settings were made either in the file or via the interface. You will see in the two pages split off from this page, how the parameters had to identify themselves as read-only or read-write).
=Revising Content of this page=
From release 3.10.1, much of the information that was produced for earlier MX releases became invalid. MX 3.10.1 has added a lot of new settings, and it has made others redundant.
Consequently, this page was emptied again, and made ready for new content to reflect how MX works from 3.10.1 onwards. PLEASE HELP TO POPULATE THIS PAGE WITH ALL THE RELEVANT CONTENT.
#One big change in 3.10.1 is that all settings are now made via the [[MX Administrative Interface|Admin interface]].
#*Therefore it makes no sense anymore to organise this page how someone editing the file directly might want.
#*This page is now organised by how you change settings in the admin interface (i.e. similar to how settings have been explained in [[MX_Administrative_Interface#Changing_Settings]]).
#Another change is that some of the settings that used to be made on the “Station Settings” page, are now made on different pages in that interface.
#Yet another change is that what you pick in some settings can affect what settings are shown later on the page.
#*You could say the settings pages have become intelligent.
#*For example, when you select a weather station type it ensures only parameters that relate to that weather station type are shown.
#*As another example, you can opt in or out of the default web site design, so that determines which parameters relating to web sites are shown.
#A final change is that some parameters are grouped as “Advanced”, so that novices can avoid those.
=How this page shows settings=
Settings are now arranged according to the menu selections, as that is the way you change them.
'''Cumulus.ini''' is a text file containing initialization parameters used by the Cumulus MX software application.
== Creating Configuration File ==
When Cumulus MX is run for very first time, the file does not exist, as it is not included in the release distribution.
#If you start Cumulus MX without a configuration file, and you have a screen attached so you can see the output from the engine, it will show this: [[File:MX first start.PNG]]
#As you can see, it is running, but it does not know what station type, so it cannot connect to it, and will not do anything more.
So when you first use the software, you will need to enter all settings (some have defaults that might be right for you), and that will lead to creation of the main configuration file.
==Reading Configuration File==
Whenever MX is restarted, it reads the ''Cumulus.ini'' that now exists.
The settings it finds tell it what options you have selected, and which sections of the MX code apply for your selections of weather station type (input) and for your selections of what processing it should do, and for where you want it to send weather data to (output).
==File contents==
The file is a simple text file. It is divided into sections with section names in square brackets (e.g. [Station]). These sections can appear in any order, by default new sections are appended after all previous sections.
Within each section, there are parameters. Each parameter is in format '''Attribute=Value''', and appears on a line to itself.
The parameters, within a section, can be in any order, by default new parameters are appended at end of the relevant section.
== Add new parameters to file==
If a new release of MX adds new parameters, then they will be automatically added to Cumulus.ini when you access that setting.
Some parameters have a valid default value
Some parameters have an initial illegal value, and you are forced to give these parameter a valid setting before MX will allow you to save settings. In some cases, these ‘’’missing’’’ values will even stop MX doing any weather data processing.
==Remove redundant parameters from file==
Best done after, not before, you [[Updating MX to new version|upgrade]] MX, as installing a new release might add/remove parameters to/from Cumulus.ini.
If you have been using Cumulus for a while, there might be parameters that are now obsolete left in your configuration file, and as newer parameters are appended at end that might make the parameter order look strange. You can start afresh with a new file anytime by following a very simple procedure as follows.
You must do this while Cumulus MX running (to preserve existing settings)...
# Rename your existing '''Cumulus.ini''' to say '''Cumulus.ini.sav''' (this keeps the file, but stops MX finding it)
# In Cumulus go to one of the settings screens
#*It is possible this might highlight a new parameter that does not yet have a valid value (e.g. the Alarm settings screen does not have a “save settings”, but it has ‘’’Enable Alarms’’’, and if you have not set all these parameters previously that will fail as there are parameters on this page that do not have a default value.
# Cumulus should create a brand new Cumulus.ini file,
#This will have all the settings you have chosen
#They will now be in the order MX is expecting
#*For the legacy software, the advice was to manually sort parameters alphabetically within sections to make it easier to find them, and avoid duplication. MX default sort order is where entries are set in the code, and that is far from alphabetic!
#As MX is unaware of settings it used previously, but does not use now, and MX is unaware of what settings the legacy software used, it won’t write back any of these redundant settings in the new configuration file.
As well as changing the order in which parameters are stored, this re-generation will show up other changes:
*The <nowiki>’’’[Graphs]]’’’</nowiki> section has also seen a number of changes as MX has developed.
*The most dramatic change may happen in <nowiki>'''[FTP Site]'''</nowiki> as any changes to the list of parameters for '''Extra Web Files''' are reproduced 100 times.
=The settings pages in admin interface=
Please see [[MX_Administrative_Interface#Changing_Settings]] for basic information, including how to load the admin interface.
A KEY POINT TO REMEMBER HERE IS THAT SETTINGS FALL INTO TWO GROUPS
#SETTINGS THAT TAKE EFFECT IMMEDIENTLY ON CLICKING “SAVE”
#SETTINGS THAT ONLY TAKE EFFECT WHEN MX IS RESTARTED
Unfortunently, there is no documentation available from developer on which settings fall in which category, so nothing can be shown here yet.
The ‘’’Settings’’’ menu has links to a number of settings pages in its drop down. Each link name appears in a separate second level headed section below.
Within that second level section that covers the whole page, there are third level sections on this page that are named to match the sections that appear on the settings page in the admin interface.
If those sections can be opened to display sub-sections, those will appear here as fourth-level sections.
Finally, individual settings are presented in tables below. There are two different formats for these tables:
#Configuration file [Section] name appears in a column, permitting one table to cover parameters that appear in different sections in the file
# Configuration file [Section] name appears at top of table, signifying all parameters in that table are in same section of the configuration file.
==Program settings==
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:100px" | Label on Settings page
!style="width:600px" | Description
|-
|style="background:lightgray;"|[Program]
|
|
|style="background:lightgray;"|Section name
|-
|EnableAccessibility=0
|Enable accessibility features
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:100px" | Label on Settings page
!style="width:600px" | Description
|-
|-
|style="background:lightgray;"|[Program]
|
|
|style="background:lightgray;"|Section name
|-
|StartupPingHost=
|Host to PING on program start-up
| Add a hostname or IP to address to ping at startup. Cumulus waits until the ping is successful before trying to read from your station. Leave blank to disable
|-
|StartupPingEscapeTime=999
|PING escape time (mins)
|Specify a time after which if no ping response is received carry on starting Cumulus MX anyway
|-
|StartupDelaySecs=0
|Start-up Delay (secs)
|Add a delay before the Cumulus tries to start reading the station.
|-
|StartupDelayMaxUptime=300
|Max system uptime to apply the start-up delay
==Station Settings==
This is a different settings page. However, the settings made on this page appear in different [Section]s of the configuration file, so do check in each table.
===Accessibility===
Yes, this selection can be made on two different pages in the admin interface.
{| class="wikitable" border="1"
|-
!style="width:600px" | Description
|-
|style="background:lightgray;"|[Program]
|
|
|style="background:lightgray;"|Section name
|-
|EnableAccessibility=0
|Enable accessibility features
====Davis VP/VP2/Vue====
{{Template:WorkInProgressBanner}} This table does not yet have all details in it.
{| class="wikitable" border="1"
|-
|
|
|style="background:lightgray;"|Section name - the following parameters
|-
|VP2SleepInterval=500
Oregon Scientific specific
{{Template:WorkInProgressBanner}}Some cells in table not yet completed
{| class="wikitable" border="1"
|
|
|style="background:lightgray;"|Section name - the following parameters
|-
|Humidity98Fix=0
{{Template:WorkInProgressBanner}} The following table has some gaps to fill in
{| class="wikitable" border="1"
|
|
|style="background:lightgray;"|Section name - the following parameters
|-
|ImetWaitTime=200
====Davis WeatherLink Live====
{{Template:WorkInProgressBanner}} This table has not been populated yet
{| class="wikitable" border="1"
!style="width:300px" | Description
|-
|style="background:lightgray;"|[Station]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in Station section
|-
|
|
|
|
|}
====Ecowittt GW1000 Settings====
|-
|style="background:lightgray;"|[Solar]
|style="background:lightgray;"|Section Name - the following parameters
|-
|SunThreshold=75
This section was introduced by release 3.5.0 (build 3071)
Cumulus.ini Section Name is [MQTT]
{| class="wikitable" border="1"
|-
!style="width:600px" | Function
!style="width:150px" | Where to Edit
|-
|Server=
==NOAA Settings==
===Create NOAA files after daily rollover===
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
| AutoSave=1
| Create NOAA files after daily rollover
|0
| *0= do not use Reports functionality
*1= do use Reports functionality
|}
===Site Details===
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
|Name=Personal Weather Station
|Site Name
|(empty)
|What you would like to see in report title for your station name
|-
|City=
|City
|(empty)
|Enter here your hamlet, village, town, or city, name
|-
|State=
|State
|(empty)
|Enter here your local authority area or region (state in USA)
|}
===Output Files===
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
|MonthFileFormat='NOAAMO'MMyy'.txt'
|Monthly filename format
|'NOAAMO'MMyy'.txt' (note quotes round 'NOAAMO' and round '.txt')
|Here you specify the filename template for MX to use when reading, or writing, monthly reports
There is a prefix text in quotes,then comes a way to specify months (see [[Reports_folder#NOAA_style_Report_Naming]]), and finally comes the mandatory text extension. e.g. "NOAAMO"MMMyyyy".txt" would also be valid.
|-
|YearFileFormat='NOAAYR'yyyy'.txt’
|Yearly filename format
|'NOAAYR'yyyy'.txt'
|Here you specify the filename template for MX to use when reading, or writing, yearly reports
There is a prefix text in quotes,then comes a way to specify months (see [[Reports_folder#NOAA_style_Report_Naming]]), and finally comes the mandatory text extension.
|}
===Report Format Options===
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
|12hourformat=0
|Time format
|0 (24 hour)
| How times are output on reports
* 24 Hour
* 12 Hour
|-
|NOAUseUTF8=1
|Use UTF-8 encoding
|Please see [[Reports_folder#Encoding]]
By default, reports use UTF-8 encoding, this can display for example degree characters as well as normal A-Z and 0-9 (or locale equivalents)
If unticked (0 appears in file), then iso-8859-1 encoding is used
|-
|UseDotDecimal=0
|Use a 'dot' decimal point
|0 (locale)
| Should dot or comma decimal be used?
*0= as defined in your locale
*1= dot decimal place, regardless of what in locale
(The reason for this is that some people instead of looking at reports, have a script that parses the report and outputs in a different way)
|}
===FTP Options===
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
|AutoFTP=0
|Auto FTP NOAA report files
|0 (disable)
|Assuming you have selected (in earlier sub-section) that MX is to create reports
*0= Disable any further action with filename
*1= Enable the file transfer process you have defined for MX, to upload the file for you (at first update time after rollover has completed)
|-
|FTPDirectory=
|FTP directory
|(empty)
|Where you want MX to use as destination folder on your FTP server
*Leave blank and MX will use wherever has been specified in main internet settings (this fits how the default web site is designed to work)
* Specify a folder relative to FTP root, and MX will upload reports to that folder instead (if you use any files from default web site, then you will need to amend the JavaScript file:
<code>let rptPath = ''; // Your path should have a trailing "/", eg. 'Reports/'</code> by putting your folder name in, an example is given for the case when “/Reports” is a sub folder off the main upload destination, note how you don’t include a leading slash, but you must add a trailing one.
|}
===Thresholds===
‘’Please note any temperatures you specify in these settings must use the same units as you have asked MX to report temperature in. Equally any rainfall amounts you specify here must use the same units as you have asked MX to report rainfall in.’’
{| class="wikitable" border="1"
|-
!style="width:30px" | Parameter Line Entry
!style="width:60px" | Label on Settings page
!style="width:20px" | Default
!style="width:300px" | Description
|-
|style="background:lightgray;"|[NOAA]
|
|
|style="background:lightgray;"|Section name - the following parameters appear in NOAA section
|-
|HeatingThreshold=15.5
|Heating threshold
|65<sup>o</sup> F or 18.3<sup>o</sup>C
|[[Heat/cold_degree_days_and_Chill_hours#Heat_Degree_Days| Heating Degree Days]] are a measure of the need for heating, based on time below, and temperature difference below, a threshold temperature. The international standard says 15.5 <sup>o</sup>Celsius is a suitable threshold to ensure comfort. For historical consistency, the default used by MX is based on the threshold used when Steve Loft first implemented this in [[Reports_folder#A_brief_history_of_these_reports|Cumulus 2 (enhancement request 44)]], and that was done to match some early look up tables.
|-
|CoolingThreshold=22
|Cooling threshold
|65<sup>o</sup> F or 18.3<sup>o</sup>C
|[[Heat/cold_degree_days_and_Chill_hours#Cold_Degree_Days|Cold Degree Days]] are a measure of the need to cool the air to make it more comfortable, based on time above, and temperature difference above, a threshold temperature. The international standard says 22 <sup>o</sup>Celsius is a suitable threshold to ensure comfort. For historical consistency, the default used by MX is based on the threshold used when Steve Loft first implemented this in [[Reports_folder#A_brief_history_of_these_reports|Cumulus 2 (enhancement request 44)]], and that was done to match some early look up tables.
|-
|MaxTempComp1=22
|Max temp comparison 1
|(empty)
|The report will count the number of days when this threshold is exceeded. In the parameter I have quoted, the first comparison has been set to agree with the cooling degree day threshold
|-
|MaxTempComp2=0
|Max temp comparison 2
|(empty)
|The report will count the number of days when this threshold is exceeded. In the parameter I have quoted, the second comparison has been set to agree with feezing point (I’m using Celsius)
|-
|MinTempComp1=15.5
|Min temp comparison 1
|(empty)
|The report will count the number of days when this threshold is exceeded. In the parameter I have quoted, the first comparison has been set to agree with the heating degree day threshold
|-
|MinTempComp2=0
|Min temp comparison 2
|(empty)
|The report will count the number of days when this threshold is exceeded. In the parameter I have quoted, the second comparison has been set to agree with feezing point (I’m using Celsius)
|-
|RainComp1=0.5
|Rain comparison 1
|(empty)
| The report will count the number of days when the daily rainfall exceeds this threshold. In the parameter I have quoted, the first comparison has been set to the same as I have set else where as my significant rain threshold
|-
|RainComp2=
|Rain comparison 2
|(empty)
| The report will count the number of days when the daily rainfall exceeds this threshold.
|-
|RainComp3=
|Rain comparison 3
|(empty)
| The report will count the number of days when the daily rainfall exceeds this threshold.
|}
===Normal Mean Temperatures===
*The parameters run from ‘’’NOAATempNormJan=’’’ to ‘’’NOAATempNormDec=’’
*There is one box labelled for each month on the settings screens
*All the defaults are (blank)
*What you enter is the mean temperature, long-term averages (say over 10 or 30 years if available) say is expected that month, often taken from local climate statistics, or your own past measurements
===Normal Precipitation===
Rainfall equivalents of mean temperature described above
| |||
