5,838
edits
Cumulus.ini (preserving history): Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
Cumulus.ini (preserving history) (view source)
Revision as of 10:56, 20 May 2021
, 10:56, 20 May 2021no edit summary
m (Add more sub-headings) |
mNo edit summary |
||
| Line 6: | Line 6: | ||
That is still the purpose of this page today, but the content of the file has changed dramatically, so this page had had to evolve too. | That is still the purpose of this page today, but the content of the file has changed dramatically, so this page had had to evolve too. | ||
==How this page was split== | |||
*The content relating to the legacy software (e.g. 19.4) has been moved to [[Cumulus.ini_(Cumulus_1)|legacy 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)|old MX page]]. | |||
**Please note, nobody copied the various changes from 3.8.0 to 3.9.7 from MX release announcements into the Wiki, if anyone can be bothered, they should be added to the documentation on that old MX 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. | |||
**This page is now only for release 3.10.1 onwards | |||
==How this page used to be laid out, and why== | |||
For both [[Cumulus.ini_(Cumulus_1)|Cumulus 1]] and [[Cumulus.ini(MX_3.0.0_to_3.9.7)|early MX releases]], the content on this page was arranged assuming people were editing the file directly. | |||
Therefore, the file was described by working through the sections on the file, and explaining the parameters that could go in each section. | |||
For the longer sections, parameters might be split into separate tables to make it easier. | |||
Before release 3.10.1, there were two types of parameters in Cumulus.ini. | |||
#"read-only" settings were made directly in the "Cumulus.ini" file, there was no way to adjust these parameters using the settings screens/pages | |||
#"read-write" settings could be changed in two ways, either by editing the file with Cumulus stopped, or by finding the parameter on a setting screen (for MX, these are in admin interface). | |||
:You will see in the two pages split off from this page ([[Cumulus.ini_(Cumulus_1)]] and [[Cumulus.ini(MX_3.0.0_to_3.9.7)]), how the parameters had to identify themselves as read-only or read-write. | |||
==Steve Loft Era== | ==Steve Loft Era== | ||
| Line 11: | Line 34: | ||
This page was created for the legacy Cumulus 1 software (up to 1.9.4). | This page was created for the legacy Cumulus 1 software (up to 1.9.4). | ||
Each time a beta version of Cumulus 1 was available, any parameters specific to that beta appeared in [[Cumulus.ini_(Beta)]], and only moved to the main page when that beta finished, and became the main release. | |||
That beta page was then briefly used for Cumulus 2. | |||
Finally, that beta page was used for all the changes in Cumulus 3 (the MX beta): | |||
*Some of the parameters for Cumulus 1 were not used by MX beta | |||
*Some of the parameters for Cumulus 1 were used by MX beta | |||
*Beta MX only added 3 new parameters | |||
This was the position when Steve Loft ceased his involvement with Cumulus. This page related to Cumulus 1 and the beta page was for MX. | This was the position when Steve Loft ceased his involvement with Cumulus. This page related to Cumulus 1 and the beta page was for MX. | ||
| Line 27: | Line 51: | ||
* For others he created new parameters | * For others he created new parameters | ||
During this early development, it was possible for this single page to cover both Cumulus 1 and MX. | During this early development in 2019, what had been on the [[Cumulus.ini_(Beta)]] page was slowly moved to this page, as 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 configuration start to increasingly diverge more and more from the legacy configuration, and this page had to be redesigned to cope, by introducing sub-sections (Cumulus 1 only, MX only, and both). | The rapid development of MX by the new developer from 2020 onwards, made MX configuration start to increasingly diverge more and more from the legacy configuration, and this page had to be redesigned to cope, by introducing sub-sections (Cumulus 1 only, MX only, and both). | ||
That design for this page started failing when new MX releases started to diverge from earlier MX releases. In other words, parameters that had existed at an early MX release, were no longer used by later releases. It was possible, but increasingly more and more difficult, to track new parameters to add that were added at particular releases, so the documentation got more and more obsolete. | That design for this page started failing when new MX releases started to diverge from earlier MX releases. In other words, parameters that had existed at an early MX release, were no longer used by later releases. It was possible, but increasingly more and more difficult, to track new parameters to add that were added at particular releases, so the documentation got more and more obsolete. | ||
| Line 35: | Line 59: | ||
To sum up, 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. | To sum up, 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. | ||
== | =Current Page Layout= | ||
==How does MX work now, and why has this page been given a new structure?== | ==How does MX work now, and why has this page been given a new structure?== | ||
| Line 86: | Line 91: | ||
If MX finds a parameter it does not understand, it ignores that parameter. This means a Cumulus.ini file created by the legacy software, or by an old release of MX, can still be read by the current release of MX, it just ignores all the obsolete parameters. | If MX finds a parameter it does not understand, it ignores that parameter. This means a Cumulus.ini file created by the legacy software, or by an old release of MX, can still be read by the current release of MX, it just ignores all the obsolete parameters. | ||
If (for example) you find the '''Extra Web Files''' editor hard to use, you might decide to stop Cumulus and still edit this configuration file directly for changes to those parameters. Given that MX ignores any parameter it does not understand, while editing the file, you can temporary have old and new parameters in the file. All you need to do is prefix those parameters you don't want MX to use with any character you like before the "Extra". | |||
== How MX creates a Configuration File == | == How MX creates a Configuration File == | ||
This page does not explain how to start using MX, please see [[MX on Linux]], [[MX on Windows OS]], and [[MX Administrative Interface]] as appropriate. | |||
The key fact relevant here is that no Cumulus release distribution contains a '''Cumulus.ini''' file: | |||
#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]] | #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. | #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. | So when you first use the software, you will need to use the [[MX_Administrative_Interface#Changing_Settings|admin interface]] to enter all settings (some have defaults that might be right for you), and that will lead to creation of the main configuration file. | ||
If you later upgrade to a newer MX build, as that release distribution does not contain a "Cumulus.ini", you cannot lose your settings. | |||
Furthermore, at the end of each (meteorological) day, MX creates a back-up in the [[Backup folder|backup/daily/TIME_NAME sub- folder]]. The TIME_NAME is constructed from a string of digits representing the date and time the directory was created (without any punctuation) e.g. 20060519090000. In that folder, recent MX releases, include a copy of the current "Cumulus.ini" file. | |||
==When does MX read the Configuration File== | ==When does MX read the Configuration File== | ||
Whenever MX is restarted, it reads the ''Cumulus.ini'' that | Whenever MX is restarted, it reads the latest ''Cumulus.ini'' and if it exists [[Strings.ini|strings.ini]]; from these one or two files it learns the configuration that you want it to use. | ||
MX also creates a backup copy of "Cumulus.ini" in a sub-folder of [[Backup folder]] that is named according to current date and time. | |||
What MX finds in your "Cumulus.ini" does of course determine what you see when you open any of the Settings pages, in the admin interface. | |||
The configuration settings in these (one or two) files: | |||
*Identify which weather station type MX is to read, and settings related to that model | |||
*Identify which [[Calculate_Missing_Values#Some_definitions|derivatives]] are source ones (read directly from weather station and converted to your preferred units) and which derivatives MX is to calculate for you. | |||
*Identify where you want MX to output to (options include external web sites, and database tables) | |||
*Identify how various standard output phrases are to be modified to suit you | |||
== Add new parameters to file== | == 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 save the settings page with that parameter. | If a new release of MX adds new parameters, then they will be automatically added to Cumulus.ini when you save the settings page with that parameter. | ||
In theory, there is no reason why you should manually add any parameters to the file. Since MX creates and edit the file, it will ensure all parameters it understands are in the file. | |||
Some parameters have a valid default value. If you need to change that value, find the appropriate setting by looking in tables below. | Some parameters have a valid default value. If you need to change that value, find the appropriate setting by looking in tables below. | ||
If MX creates the file, it will give an initial illegal value to any parameter where it cannot assign a default. This is to enforce the need to give these parameter a valid value before MX will allow you to save settings. Generally, MX will not do any weather data processing, until these ‘’’missing’’’ values are edited. In some cases, a new release of MX (such as 3.11.0 which added emailing capability) adds new parameters without any default values, and you might not realise that if you don't go into the relevant Settings page (Alarms for 3.11.0) and find you can't save (Enable for Alarms page). | |||
==How to Remove Redundant parameters from file== | ==How to Remove Redundant parameters from file== | ||
If you have been using Cumulus for a while, there might be parameters that are now obsolete left in your configuration file. | |||
MX will ignore any parameters that it no longer recognises, but there is a simple way to make MX create a new file for you, keeping your existing settings, but ensuring the new file does not have any obsolete parameters. | |||
''The following procedure is 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. | |||
Apart from that upgrade consideration, you can start afresh with a new file anytime by following this very simple procedure: | |||
You must do this while Cumulus MX running (to preserve existing settings)... | '''You must do this while keeping 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) | # 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 – simply click ‘’’Save Settings’’ (i.e. any action that makes MX save settings to its configuration file) | # In Cumulus go to one of the settings screens, (e.g. '''Program Settings''' which is currently a short page) – simply click ‘’’Save Settings’’ (i.e. any action that makes MX save settings to its configuration file) | ||
#*It is possible this might highlight a new parameter that does not yet have a valid value (e.g. the Alarm settings | #*It is possible this might highlight a new parameter that does not yet have a valid value (e.g. the Alarm settings page, which uses ‘’’Enable Alarms’’’ rather than "Save settings", got extra settings without defaults at 3.11.0). | ||
# Cumulus | # Cumulus (if it accepts that save) will now create a brand new '''Cumulus.ini''' file, | ||
#This will have all the settings you have chosen | #This will have all the settings you have chosen | ||
#They will now be in the order MX is expecting | #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! | #*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 from 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 | #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 redundant settings in the new configuration file. | ||
As well as changing the order in which parameters are stored, this re-generation | As well as changing the order in which parameters are stored, this re-generation may show up other changes (if you do have reason to examine the new file and compare with the old file): | ||
*A major change is likely in the <nowiki>'''[Station]'''</nowiki> section as that has seen a lot of changes as MX is developed. | *A major change is likely in the <nowiki>'''[Station]'''</nowiki> section as that has seen a lot of changes as MX is developed. | ||
*The <nowiki>’’’[Graphs]]’’’</nowiki> section has also seen a number of changes as MX has developed. | *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 | *The most dramatic change may happen in <nowiki>'''[FTP Site]'''</nowiki> as any reorganisations to the list of parameters for '''Extra Web Files''' are reproduced 100 times. | ||
=The settings pages in admin interface= | =The settings pages in admin interface= | ||
| Line 137: | Line 163: | ||
Please see [[MX_Administrative_Interface#Changing_Settings]] for basic information, including how to load the admin interface. | Please see [[MX_Administrative_Interface#Changing_Settings]] for basic information, including how to load the admin interface. | ||
The ‘’’Settings’’’ menu has links to a number of settings pages in its drop down. On this Wiki page, a separate second level headed section is used for each settings page. | |||
#SETTINGS THAT TAKE EFFECT | |||
Within that second level section in this Wiki (it covers the whole settings page), there are third level sections on this Wiki page that are named to match the way that settings page has grouped settings into a number of sections that have to be opened individually (by either a button for maximum accessibility, or a '''Click ▶to expand, click ▼ to collapse''' for alternative styling). | |||
If after opening any settings page sections MX then chooses to display sub-sections, this Wiki page will use fourth-level section headings that correspond with those sub-section names on the settings page. | |||
Finally, individual settings are normally presented as rows in tables for clarity on this Wiki page. | |||
There are 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. | |||
# MQTT parameters are handled slightly differently, as they did not fit that standard layout | |||
# As an exception, the mean temperatures, and normal rainfall figures, with one parameter per month, have been presented as text, rather than a table for simplicity | |||
# As another exception, for the Extra Web Files Settings page, where the settings page uses different software using a table to enter 800 settings, the table here is split into just 8 rows, each of which applies to 100 parameters in the file. | |||
==Do I need to restart MX?== | |||
Maybe... | |||
The settings available on the various pages in the admin interface fall into two groups: | |||
#SETTINGS THAT TAKE EFFECT IMMEDIATELY ON CLICKING “SAVE” | |||
#SETTINGS THAT ONLY TAKE EFFECT WHEN MX IS RESTARTED | #SETTINGS THAT ONLY TAKE EFFECT WHEN MX IS RESTARTED | ||
There used to be a third group. Before '''Release 3.11.2 - build 3131''' a few changes made in the interface were not saved into "Cumulus.ini", and therefore lost when MX was restarted. One example of these former exceptions was on Program Settings page where the former action was that choice for [[MXDiags folder|adding extra debugging information to file in MXDiags folder]] was not saved for subsequent session. | |||
For the current MX release, any change made (on any settings page) will be saved into "Cumulus.ini", and will still apply when MX is restarted. | |||
Unfortunately, there is no documentation available from developer on which settings do not take effect until MX is restarted, so this documentation cannot indicate where a restart is required. You can play safe, and restart MX each time you finish making edits to settings. | |||
==Program settings== | ==Program settings== | ||
