5,838
edits
mNo edit summary |
m (→Configuration file: add links) |
||
(4 intermediate revisions by the same user not shown) | |||
=Introduction=
This page was inspired by this [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17749 update from Cumulus 1] forum topic. That post was made in January 2020, and therefore
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This page was last partially updated for the MX release available in
Appeal to contributors: Please
</div>
You might want to read the related page at [[My_migration_from_C1_to_MX]] which describes how this worked in practice for release version 3.4.5 (build 3069).
=Should I migrate to MX or not?=
=Migrating existing data files from legacy Cumulus to a recent build of MX=
If you want to continue using the same weather station, and you are not moving to a different home, you will want to maintain the data you collected using Cumulus 1 in your MX installation. This is what is meant by migration, and there is
Obviously, you will want to copy ALL (except weather diary which uses a different file) the files in the [[#"data" folder]], from any old installation into the new installation, but migrating these is not always easy, here is a quick summary of the potential issues (all discussed further in various subsections later):
* '''When you first run MX, the [[#Start date|Start Date]] is recorded in the configuration file'''
** In the legacy software, this date is purely used as something to appear on one of the [[Customised_templates#The_Standard_Templates_for_Cumulus_1|sample web templates]]
** In Cumulus MX, this date controls what data is read from [[Monthly log files]], such as [[Standard log files]], and [[Extra Sensor Files]], any lines in those files with earlier dates are ignored by CumulusMX.exe, ExportToMySQL.exe, and other utilities.
** You can edit this [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, in the admin interface select ''Station Settings → Common Options → Advanced Options → Records Began date''
* Be aware your new installation has to use the same "locale" as the old installation, or MX will struggle as the locale affects how new lines are stored, and how MX expects old lines to have been stored the same way.
* If your old installation, is on a different operating system to the new installation, remember that Microsoft Windows uses different line terminators to all other operating systems, although MX should cope with mixed line terminators, any third party routines reading your data files will probably not accept a line terminator change. See [[MX on Linux]] page for more information on this.
* Cumulus MX is much more fussy than Cumulus 1 about every line in any data file using exactly the same locale formatting:
** Cumulus 1 is able to accept any character (other than the list separator, and space) being used to separate hour and minutes in time-stamps, MX expects a colon ":"
** [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
** [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files, and how MX prefers decimal points to decimal commas
==File names==
Note that if you run MX on a UNIX based operating system (e.g. Linux or Raspberry Pi OS) all file names are case-sensitive, please read documentation to see where capital letters are required in those file names. Be aware that Wiki pages always change first letter to a capital,
==Line terminators==
If you are not running MX on a Microsoft Windows computer, ideally you should change the characters appearing at the end of every line in
I say ideally, because although Microsoft is fussy, and determined to be different by insisting files match its choice, most other operating systems can tolerate different line terminators. This means that MX will generally tolerate files using a mixture of line terminators. However, if you are using third-party routines, please be aware that these are often written to expect a particular line terminator, and they may give unexpected results when used with files that do not match that expectation!
With Cumulus 1 (or MX) on Windows, each line in every file ends with both carriage return and line feed.
For all Unix-based operating systems (Linux, Raspberry Pi OS, and other variants), each line should end with just a Line Feed.
To change end of line characters, run each file through an editor designed for programmers. Various editors are available but "Notepad ++" is one that is popular on Windows, but can run on other operating systems. In its '''Edit''' menu, choose '''EOL conversion'''. On a Linux system like a Raspberry Pi computer, please see [[MX_on_Linux#Changing_line_terminators]].
If you use PHP
==Configuration file==
MX's [[Cumulus.ini]] has different content to the legacy [[Cumulus.ini_(Cumulus_1)|'''cumulus.ini''']]. From release 3.12.0,many more new settings were added, more settings were removed, and some parameters in the file were renamed. The first cross reference, in listing all the parameters, makes it clear which settings were introduced in the legacy software, and which MX release added new settings, this should help you to grasp how many new settings exist!
'''The [[MX_Administrative_Interface#Changing_Settings|settings pages]] in MX, work differently to the [[Cumulus_Screenshots#Configuration_Menu_Screens|settings screens]] in Cumulus 1. You need to click ''Save'' and (in many cases) stop and restart MX before changed settings take effect.'''
Consequently, if you are migrating from the legacy software to MX now, it is best to rename your old '''cumulus.ini'' file so it is is not seen by MX. Let MX create a new configuration file with just the parameters it needs using the various [MX_Administrative_Interface#Changing_Settings|settings pages in the admin interface]]. That will ensure you don't get muddled by parameters used for Cumulus 1 (but not for MX); and you do have all the parameters you do need, set correctly.▼
===Configuration file naming restrictions===
Cumulus 1 can recognise, in some circumstances, "cumulus1.ini", and other variants, not just "cumulus.ini".
MX only recognises "Cumulus.ini". The Windows operating system is not case sensitive for file names. All other operating systems require the first letter of the filename to be a capital, and the remainder to be lower case as shown.
===Historical evolution of configuration file===
The oldest approach for migration from the legacy software, was to copy across to MX your existing configuration file, and let MX ignore all the parameters that do not apply to it. This worked because the early MX releases had few new parameters, and mostly used the majority of the old parameters.
For any parameters that were not set by the admin interface (and there were many "read-only" parameters in early releases of MX), one assumed these also existed in Cumulus 1 (refer to [[Cumulus.ini (Cumulus 1)]]) and so were already in your file.
Substantial changes to changes were made from release 3.8.0 onwards, hence [[Cumulus.ini]] is a new page applicable from that release. More changes were made in 3.10.0, and subsequent releases, as settings that used to have to be made directly in file were gradually moved to be advanced settings controlled in the admin interface. From release 3.12.0,many more new settings were added, more settings were removed, and some parameters in the file were renamed.▼
To add the few new parameters that MX did need (see [[Cumulus.ini (MX 3.0.0 to 3.7.0)]] page), you would then go to the [[MX_Administrative_Interface#Changing_Settings]] pages and work steadily through ALL the options.
▲Consequently, if you are migrating from the legacy software to MX now, it is best to rename your old '''cumulus.ini'' file so it is is not seen by MX. Let MX create a new configuration file with just the parameters it needs using the various [MX_Administrative_Interface#Changing_Settings|settings pages in the admin interface]]. That will ensure you don't get muddled by parameters used for Cumulus 1 (but not for MX); and you do have all the parameters you do need, set correctly.
Retaining your old settings as far as possible simplified any migration of data files from your legacy installation into MX, because it ensured you kept to same unit selections, and same extra sensor selections.
==Settings==▼
At releases like 3.3.0 and 3.6.0, amongst others, there were changes to "read-only" parameters for MX. These could not be adjusted through the admin interface, and needed to be entered manually into the '''Cumulus.ini''' file, as instructed on [[Cumulus.ini (MX 3.0.0 to 3.7.0)]] page.
===Subsequent evolution of configuration file===
Substantial changes to settings available were made from release 3.8.0 onwards. The content of the '''Cumulus.ini''' file changed drastically, with much deviation from the configuration file used in earlier releases (including for the legacy software), hence [[Cumulus.ini]] is a new page describing the settings, and the parameters appearing in the configuration file, applicable from that release.
▲
For example the changes include the (advanced) ability to change the number of decimal places for storing derived values like daily rainfall, sea level pressure, and wind speeds.
Changes to the [[New Default Web Site Information|Default Web Site]] (diverging away from the [[Customised templates]] approach in the legacy software) and implementing the option to use (as was available in the legacy software, and the earliest MX beta, but then removed) a copy action instead of a file transfer action for [[Your Own Server]], has led to many,many new settings. Thus the advice has become abandon your old legacy software cumulus.ini file when you move to MX.
▲===Settings===
The settings pages in Cumulus 1 and MX work differently:
* for Cumulus 1 you choose to save changes by clicking OK,
* for MX changes are only saved when you click a '''Save''' button if one is provided.
* The alarms page works slightly differently, with an "Update alarms" button.
* If there is no Save button anywhere on the screen (as in Extra Web Files) then the setting is saved to configuration file when you move to next field/line, and acted on when you next restart MX.
Be aware that you should restart MX after changing many settings
===Start date===
When you first run any Cumulus software (whatever flavour) a parameter is added to the configuration file that documents the date Cumulus was first used.
For Cumulus 1, this parameter appeared in two places on the example web template for all-time records, but was otherwise ignored. Thus if you decided to import into your data logs readings from before you first ran Cumulus, the legacy software would be able to find those earlier records, without you needing to change the date that appeared on the web page.
'''CumulusMX.exe''' uses this parameter to determine the first standard
From release 3.10.1, MX allows you to edit this start date within the admin interface, just select ''Station Settings → Common Options → Advanced Options → Records Began date''. It is "hidden" as an "advanced" setting, with a strict danger warning,
=== Station connections===
''You can skip this
This subsection is relevant if your station connects by a serial connection and MX needs to be told which port. It also applies if the serial connection is converted to USB.
If your weather station used a port to connect to Cumulus 1, that port was set on the settings screen as a number and stored in [[Cumulus.ini_(Cumulus_1)]] in the station section as a parameter in the format '''Port=n'''.
In Cumulus MX, as it runs on various operating systems, the port is specified using text (instead of a number), again you select it within settings, on Station settings page, but within [[Cumulus.ini]] in the station section the parameter is in the format '''Comport=tttttttt'''.
If your old parameter had a value of '''3''', and you are still using Windows, the new setting would have value of '''COM3''', i.e. serial port 3 now requires a "COM" prefix.
A typical parameter value for other serial connecting devices might be "/dev/
===RG11 Rain gauge===
If you use a RG11 rain gauge:
*Replace: '''RG11port=n''' and '''RG11port2 =n''' (Cumulus 1) where n is a number,
* With: '''RG11portName=xxxx''' and '''RG11portName2=yyyy''' (Cumulus MX on Windows)
The new value is a string with values as per previous paragraph depending on device on which Cumulus MX is running.
===Other Cumulus.ini parameters===
Lots of parameters in [[Cumulus.ini]] are being changed as MX is developed. So much had changed by the time that MX releases reached 3.12.0, the first run of that particular release created a brand new '''Cumulus.ini''' discarding the old file. If you migrate from Cumulus 1 to MX without stepping through MX releases, you may have several issues, but without knowing which MX release you have selected, all I can suggest is that you work through all settings found in the Settings page of the MX release you choose. Although you could compare [[Cumulus.ini (Cumulus 1)]] and [[Cumulus.ini]] pages, there is no guarantee that either is totally accurate!
==Strings.ini==
The contents of the [[Samplestring.ini|samplestring.ini]] file you get in your MX release distribution varies depending on the release you have downloaded.
Check your existing '''strings.ini''' file against the ''samplestring.ini'' file in the MX distribution you have. If the attribute names (left hand side of the equals sign) match for the parameters you selected to include in your '''strings.ini''', then you can reuse your existing file. If your file includes attributes that are no longer in the MX ''samplesting.ini'' file, then you will need to edit your '''strings.ini''' file that is placed in the folder containing CumulusMX.exe. You may also need to add new items into your '''strings.ini''' based on new content in ''samplestring.ini''.
==NOAA style reports==
The generation of reports is an optional feature, if you have never used it your (legacy) Cumulus Reports folder will be empty, then you have no files to move to your MX installation, and you should skip the rest of this sub-section.
Please see [[Reports_folder]] for full information. Cumulus software creates reports, it does not edit existing reports, so migration is fairly simple. Just copy the contents of the '''Reports''' folder in your original Cumulus installation into the folder in the new installation. Of course, nothing is totally simple, the encoding default changes between Cumulus 1 and MX, and once again we might need to consider end of line characters!
For those of you who are more technical:
* files created in Microsoft's Windows Operating System use two characters (carriage return and line feed) to end each line, while all other operating systems use a single character (line feed in most Unix derived systems). Apple Mac are again different in using just Carriage Return. This should not cause any problems.
* files can be encoded (how individual characters are represented by binary codes) by Cumulus in two different ways. There is more about encoding at [[Reports_folder#Encoding]], the relevance here is that if your MX settings and Cumulus 1 settings use different encodings (as they will if you let this default) you may find some characters (e.g. degree symbol) do not appear correctly when viewing some of your reports.
=="data" folder==
You should copy all files in the [[data folder]] from your legacy Cumulus installation to your MX installation if you want to be able to see past data
* See [[#Start date]] earlier on this page for a change that you may need to make to ensure MX accepts data in any old [[Standard log files]] and [[Extra Sensor Files]]
* See [[#Weather Diary]] later on this page, and [[Weather Diary]] page; Cumulus does not provide any utility to convert the old legacy format to the new MX format.
* See [[#dayfile.txt]] later still on this page, and [[Amending dayfile]] page, for how you can ensure MX can read your existing dayfile.txt file
* See [[#Line terminators]] earlier on this page for some technical issues if MX is running on a different computer to your Cumulus 1 installation.
===Standard log files and other log files===
The [[Speciallog.txt]] file optionally used by the legacy Cumulus 1, is not used by MX.
The [[Standard_log_files]] and any (optional) [[Extra Sensor Files]], from the legacy software can be transferred to your MX installation, but see [[#Start date]] earlier on this page, and [[Calculate Missing Values]] page to read about extra tasks you may need to do.
MX extends these [[Monthly log files]] by adding [[Air_Link_Log.txt|another optional set of files]].
===Weather Diary===
===the .ini files===
Once again, the simple instruction is to copy these from your old installation to your new installation, to ensure your extreme record history is maintained. Once again, differences between Cumulus 1 and MX mean that the process may not be that simple, especially if you try to migrate straight to the latest MX release.
Your Cumulus 1 '''.ini''' files can be read in all release versions from 3.0.0 to 3.5.y. Steve Loft did make two changes in his beta MX, these mean your .ini files may look strange while they have some entries made by Cumulus 1 and some made by MX:▼
====MX releases up to 3.5.4====
▲'''Your Cumulus 1 '''.ini''' files can be read in all release versions from 3.0.0 to 3.5.y.''' Steve Loft did make two changes in his beta MX, these mean your .ini files may look strange while they have some entries made by Cumulus 1 and some made by MX:
# all newly stored values will use decimal points in these files, (i.e. any decimal commas valid in the legacy software, are not used by MX).
# all newly stored time-stamps will use the ISO specification (ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times) so new dates have year first, the parts of the date are separated by hyphens, and new times use colon (:) between hour and minutes (i.e. the regional settings that the legacy software adopted have been abandoned by MX)
====Historical background to dates/times====
When Steve Loft designed his original Cumulus (1), he had no experience to draw upon as to the best way to treat items like dates. He wrote the software originally just for his own benefit and did not need to worry about time zones. Subsequently as he enhanced his software to make it usable by others, he faced many issues on how to cope with different time zones, and different weather stations having different sensors. In Cumulus 1, he basically focussed on compatibility by keeping to his original design for the data
When Steve Loft took a new look at the data log files for Cumulus 2, he started with a new design, the principal change was that he decided to use UTC for all fields in them that reference dates and times. Steve struggled with Cumulus 2 largely because he was (at that time) not familiar with the C# language he was later to use for MX. It is fair to say that conversions between local time and UTC did contribute to his failure to get Cumulus 2 to provide the functionality he had offered in the original Cumulus.
If you moved your Cumulus 1 installation from one windows pc to another, it is just possible that you might have a mix of "decimal comma" and "decimal point" in your values, or you might have changed the field separator (normally ";" or ","). Again, these must be consistent in all dayfile.txt lines for MX, and must match what is defined in the locale used.
=web server=
|
edits