5,838
edits
Cumulus.ini: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
Minor resequencing of page
(→First run of MX: Restore text lost when new page created) |
m (Minor resequencing of page) |
||
|
== Simplifications ==
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:
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
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.
=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?==
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
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.
=Settings Configuration for MX=
The MX software offers much functionality and flexibility. Consequently, it has an extensive set of configuration settings, fortunately
==First run of 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
The settings available on the various pages in the admin interface fall into two groups:
#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 those few settings were therefore lost when MX was restarted. One example of these former exceptions was
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.
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.
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.
==How to Remove Redundant parameters from file==
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.
=Tables listing Settings=
| |||
