Cumulus Wiki

Cumulus.ini: Difference between revisions

Cumulus.ini (view source)

Revision as of 07:10, 12 July 2021

274 bytes added ,  07:10, 12 July 2021
m
Minor resequencing of page
(→‎First run of MX: Restore text lost when new page created)
m (Minor resequencing of page)
Line 32: Line 32:
== Simplifications ==
== Simplifications ==


The MX configuration is simpler that that used by the legacy software. The ongoing development of MX is making it even simpler, by revising the pages for the setting of all parameters, and the labels/grouping.
Using the MX configuration is simpler that that used by the legacy software. Since MX requires far more parameters as it has far more optional functionality, the developer had to devise a way to make it easier for those using MX to quickly assign the settings that might be best for those new to Cumulus to get the software working without needing to understand all the settings.
 
The ongoing development of MX is focused on making configuration even simpler, by revising the pages for the setting of all parameters, and improving the labels/grouping.


It may be worth remembering why the legacy software made life complicated:
It may be worth remembering why the legacy software made life complicated:
Line 50: Line 52:




== How MX creates a Configuration File ==


This Wiki page does not explain how to start using MX, please see [[MX on Linux]], [[MX on Windows OS]], and [[MX Administrative Interface]] as appropriate.
This Wiki 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:
The key fact relevant here is that no Cumulus release distribution contains a '''Cumulus.ini''' 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) as described later in this page, and that will lead to creation of the main configuration file.  
#If you start Cumulus MX interactively 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 any weather station, and will not do anything more.
 
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 entered in your existing file. However, be aware that a new release may remove some settings, and add new settings, hopefully the release announcement will give specific details. Otherwise, you will need to work through all the Settings Pages, and all the "MX Sections" (see Terminolgy below)
If you later upgrade to a newer MX build, as that release distribution does not contain a "Cumulus.ini", you cannot lose your settings entered in your existing file. However, be aware that a new release may remove some settings, and add new settings, hopefully the release announcement will give specific details. Otherwise, you will need to work through all the Settings Pages, and all the "MX Sections" (see Terminolgy below)


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.
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.
=How this Wiki page classifies settings=
This new Wiki page is no longer designed around the way parameters appear in the file, as earlier pages with this name were. Here are some of the reasons:
# Settings can appear in any order in the file, but it is easier to find them on this page if they are listed alphabetically
# Releases might add new parameters, or remove old parameters, so looking at a file does not identify which parameters need to be explained on this page
# Releases might add new sections in the file, or remove old sections in the file, so organising this page by those "File sections" no longer makes sense
# The settings interface in MX is being comprehensively redesigned.  That means this documentation cannot be organised by the way MX organises its settings pages. 
#* To clarify that reason, if this Wiki page was organised according to the Settings Screens that applied say at release 3.8.0, a different sequence might be required in say 3.12.0 because that changed the Settings Screens.
Some classification is still needed to help you the reader find settings, only you can judge whether the grouping here suits you! In creating this page, I have tried to think of a way to group various settings and arranged those groups alphabetically, to make navigation as easy as I can.
Of course if you have your own ideas of a better way to group the documentation here, you are welcome to implement your preference, by editing this page.
==Tabular presentation==
Within the groupings I have selected, individual settings are normally presented as rows in tables for clarity on this Wiki page.  The  individual tables can have up to 7 columns. The columns can explain for each setting:
* Where in the admin interface you edit it (MX page and MX section in terminology below)
* Whether the Setting is always shown on the Settings Page ("Always" is shown), or is only shown if an earlier Setting has a particular selection (dependency is shown)
* What File Section (in terminology below) it appears in with the file (always appears, and is shown, between square brackets)
* The attribute name used for the parameter in the file (always shown with an equals sign after it)
* Which release introduced the setting(s)
* What is the default value for the parameter, (and what that default value means)
* A description of what the parameter represents, and what values it can take
If the content of any column would be same for every row, then that column is omitted, and the relevant information is instead stated before the table.
Exceptions to above table styling:
# MQTT parameters are handled slightly differently, as they did not fit that standard layout
#  The mean temperatures, and normal rainfall figures, with one parameter per month, have been presented as text, rather than a table for simplicity
# For the Extra Web Files Settings page, where the settings page uses [[MX_Basic_info#editable_grid|editable grid software]], instead of listing all 800 settings individually, the table here is split into just 8 rows, each of which applies to 100 parameters in the file.
==Terminology used on this Wiki Page==
{| class="wikitable" border="1"
|-
!style="width:30px" | Terminology
!style="width:800px" | What it means
|-
| Qualifications:
* '''Settings page'''
* '''Wiki page'''
| Because "page" could refer to either this page or the Settings page, page will always be qualified
|-
| Shown on Settings page?
| Sometimes whether you see a particular setting on the Settings Page, depends on a previous selection has been made, that is explained under this heading
|-
| MX Section
| Under this heading you will find how to navigate to the relevant setting within the admin interface. This covers the page  where you edit the setting, followed by →, and then the section (and sub-section where relevant) that you have to select to see the setting
Each MX section on the Settings page has to be opened individually (by either a button for maximum accessibility, or a '''Click ▶to expand,  click ▼ to collapse''' for alternative styling).
|-
| Label on Settings page
| Under this heading you will discover how MX labels the individual setting where you edit that setting
|-
| File Section
| Within the file, a number of section headings are used, to gather multiple parameters together. Thus under this heading, for each setting, the table shows the '''File Section''' where the parameter will be stored
|-
| Parameter Line Entry
| Within the file each setting is represented by a parameter in format '''attribute=value''' on a line to itself without any punctuation symbols. If the parameter has a default value, that is shown here and explained in next column
|-
| Default
| This is the value (if any) that the individual setting takes when it has not been amended. Some parameters do not have a default value and "(none)" will be shown in this case.  No brackets surround literal text representing default value, which is normally also seen in '''Parameter Line Entry'''.  In general,  round brackets are used in '''Default''' column to indicate an explanation.
|-
| Description
| Under this heading you will find an explanation of the setting including (where relevant) what values it can take
|}


==When, and How, does MX read the Configuration File?==
==When, and How, does MX read the Configuration File?==
Line 68: Line 134:
Whenever MX is restarted, it reads the latest ''Cumulus.ini''  and if it exists [[Strings.ini|strings.ini]] (briefly mentioned below); from these one (or two) file(s), it learns the configuration that you want it to use.  
Whenever MX is restarted, it reads the latest ''Cumulus.ini''  and if it exists [[Strings.ini|strings.ini]] (briefly mentioned below); from these one (or two) file(s), it learns the configuration that you want it to use.  


For completeness I mention here, configuration information for MX can also be stored in an optional file [[strings.ini]], that is used to identify how various standard output phrases are to be modified to suit you, but this Wiki page ignores that file.
For completeness I mention here, configuration information for MX can also be stored in an optional file [[strings.ini]], that is used to identify how various standard output phrases are to be modified to suit you.


MX works differently to how the legacy software that was described above worked. Essentially, MX reads the whole file, for each attribute part of a parameter in the file, there is a variable stored within the MX code. So the value part of each parameter is assigned to the respective variable. Hence MX will not permit any duplicates for any parameter.  If MX finds a parameter it does not understand, it ignores that parameter.   
Essentially, MX reads the whole file, for each attribute part of a parameter in the file, there is a variable stored within the MX code. So the value part of each parameter is assigned to the respective variable. Hence MX will not permit any duplicates for any parameter.  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, as it just ignores all the obsolete parameters.  However, since MX now has a lot of new parameters in the file, that were not in the legacy file, nor in a file created by an early MX release, it is often easier to start again with a new configuration file, as explained later, to ensure the configuration of MX is correct for you.
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, as it just ignores all the obsolete parameters.  However, since MX now has a lot of new parameters in the file, that were not in the legacy file, nor in a file created by an early MX release, it is often easier to start again with a new configuration file, as explained later, to ensure the configuration of MX is correct for you.
Line 81: Line 147:
=Settings Configuration for MX=  
=Settings Configuration for MX=  


The MX software offers much functionality and flexibility.  Consequently, it has an extensive set of configuration settings, fortunately about from the initial settings of model and units (see next sub-section), recent releases have simplified many of the settings for optional features by providing particular selections to affect a whole range of others (for predicted uses), instead of forcing you to individually work through every individual setting.
The MX software offers much functionality and flexibility.  Consequently, it has an extensive set of configuration settings, fortunately apart from the initial settings of model and units (see next sub-section), recent releases have simplified many of the settings for optional features by providing particular selections to affect a whole range of others (for predicted uses), instead of forcing you to individually work through every individual setting.


==First run of MX==
==First run of MX==
Line 112: Line 178:
If you change a setting directly in the file, you must stop MX beforehand. The setting takes effect when you restart MX.
If you change a setting directly in the file, you must stop MX beforehand. The setting takes effect when you restart MX.


If you change a setting, using the admin interface, it may, or may not, take effect immediently...
If you change a setting, using the admin interface, it may, or may not, take effect immediately...


The settings available on the various pages in the admin interface fall into two groups:
The settings available on the various pages in the admin interface fall into two groups:
Line 118: Line 184:
#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.
''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 those few settings were therefore lost when MX was restarted. One example of these former exceptions was that the former action selecting [[MXdiags folder|adding extra debugging information to file in MXDiags folder]] was previously not saved for subsequent session.


Unfortunately, there is no documentation available from developer on which settings, at any release, do not take effect until MX is restarted.
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. That restart will ensure all settings changed in the last session do take effect, even those that did not take effect before the restart.  


A further complication is that in some releases, certain settings that used to require a restart have been changed so they take effect intermediately.  It is anticipated this will continue to change as MX develops.
Unfortunately, there is no documentation available from developer on which settings, at any release, do not take effect until MX is restarted.  We do know that you need to do a restart after choosing the station model, and that is unlikely to change.


This means that any attempt to document which changes do require a restart is working against a moving target, 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, or you can read all the support forum announcements, and see if you can find any information about whether a restart is needed.
In early MX releases most configuration settings required a restart of MX before they took effect, but since then in some releases, certain settings that used to require a restart have been changed so they take effect intermediately.  It is anticipated, as MX develops, the majority of settings will become ones that take effect without a restart of MX.
 
This means that any attempt to document here which changes do require a restart of MX is working against a moving target. Consequently, this documentation does not indicate where a restart is required.  You can either play safe, and restart MX each time you finish making edits to settings, or you can read all the support forum announcements, and see if you can find any information about whether a restart is needed, for whatever particular settings you are changing, at the release you are using.




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. That restart will ensure all settings changed in the last session do take effect, even those that did not take effect before the restart.


==How to Remove Redundant parameters from file==
==How to Remove Redundant parameters from file==
Line 198: Line 265:
As a specific example, release 3.11.0 added emailing capability; that requires quite a lot of new parameters to be added to the file.  You could use MX without these new parameters, but the Alarm Settings page would not allow you to click '''Enable''' until you had defined various settings on another Settings page, as well as on this Alarm Settings page.
As a specific example, release 3.11.0 added emailing capability; that requires quite a lot of new parameters to be added to the file.  You could use MX without these new parameters, but the Alarm Settings page would not allow you to click '''Enable''' until you had defined various settings on another Settings page, as well as on this Alarm Settings page.


=How this Wiki page classifies settings=


For a large number of reasons, this new Wiki page is no longer designed around the way parameters appear in the file, as earlier pages with this name were:
# Settings can appear in any order in the file, but it is easier to find them on this page if they are listed alphabetically
# Releases might add new parameters, or remove old parameters, so looking at a file does not identify which parameters need to be explained on this page
# Releases might add new sections in the file, or remove old sections in the file, so organising this page by those "File sections" no longer makes sense
# The settings interface in MX is being comprehensively redesigned.  That means this documentation cannot be organised by the way MX organises its settings pages. 
#* To clarift that, if this Wiki page was organised according to the Settings Screens that applied say at release 3.8.0, a different sequence might be required in say 3.12.0 because that changed the Settings Screens.
Some classification is still needed to help you the reader find settings, only you can judge whether the grouping here suits you! In creating this page, I have tried to think of a way to group various settings and arranged those groups alphabetically, to make navigation as easy as I can.
Of course if you have your own ideas of a better way to group the documentation here, you are welcome to implement your preference, by editing this page.
Within the groupings I have selected, individual settings are normally presented as rows in tables for clarity on this Wiki page.  The  individual tables can have up to 7 columns so they can explain for each setting:
* Where in the admin interface you edit it (MX page and MX section in terminology below)
* Whether the Setting is always shown on the Settings Page ("Always" is shown), or is only shown if an earlier Setting has a particular selection (dependency is shown)
* What File Section (in terminology below) it appears in with the file (always appears, and is shown, between square brackets)
* The attribute name used for the parameter in the file (always shown with an equals sign after it)
* Which release introduced the setting(s)
* What is the default value for the parameter, (and what that default value means)
* A description of what the parameter represents, and what values it can take
If the content of any column would be same for every row, then that column is omitted, and the relevant information is instead stated before the table.
Exceptions to above table styling:
# MQTT parameters are handled slightly differently, as they did not fit that standard layout
#  The mean temperatures, and normal rainfall figures, with one parameter per month, have been presented as text, rather than a table for simplicity
# For the Extra Web Files Settings page, where the settings page uses [[MX_Basic_info#editable_grid|editable grid software]], instead of listing all 800 settings individually, the table here is split into just 8 rows, each of which applies to 100 parameters in the file.
==Terminology used on this Wiki Page==
{| class="wikitable" border="1"
|-
!style="width:30px" | Terminology
!style="width:800px" | What it means
|-
| Qualifications:
* '''Settings page'''
* '''Wiki page'''
| Because "page" could refer to either this page or the Settings page, page will always be qualified
|-
| Shown on Settings page?
| Sometimes whether you see a particular setting on the Settings Page, depends on a previous selection has been made, that is explained under this heading
|-
| MX Section
| Under this heading you will find how to navigate to the relevant setting within the admin interface. This covers the page  where you edit the setting, followed by →, and then the section (and sub-section where relevant) that you have to select to see the setting
Each MX section on the Settings page has to be opened individually (by either a button for maximum accessibility, or a '''Click ▶to expand,  click ▼ to collapse''' for alternative styling).
|-
| Label on Settings page
| Under this heading you will discover how MX labels the individual setting where you edit that setting
|-
| File Section
| Within the file, a number of section headings are used, to gather multiple parameters together. Thus under this heading, for each setting, the table shows the '''File Section''' where the parameter will be stored
|-
| Parameter Line Entry
| Within the file each setting is represented by a parameter in format '''attribute=value''' on a line to itself without any punctuation symbols. If the parameter has a default value, that is shown here and explained in next column
|-
| Default
| This is the value (if any) that the individual setting takes when it has not been amended. Some parameters do not have a default value and "(none)" will be shown in this case.  No brackets surround literal text representing default value, which is normally also seen in '''Parameter Line Entry'''.  In general,  round brackets are used in '''Default''' column to indicate an explanation.
|-
| Description
| Under this heading you will find an explanation of the setting including (where relevant) what values it can take
|}


=Tables listing Settings=
=Tables listing Settings=
Sfws
5,838

edits

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