Migrating from Cumulus 1 to MX: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
Like other longer pages in this Wiki, the content is divided into sections, if you are interested in a particular issue, find it in the table of contents, rather than reading whole page!


This page covers moving from Cumulus 1 to MX, and '''in particular it explains exactly what is required to run MX on the Windows Operating System'''.
=Introduction=
 
It was partly inspired by this [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17749 update from Cumulus 1] forum topic.  As that post was made in January 2020, the bulk of the text on this page relates to Version 3.3.0, which was the MX release that was in use at the time. The "How I did it" section was added based on release version 3.5.0 build 3069. The "Moving Files to MX" section was updated for release version 3.7.0 when increased functionality available in MX made it attractive to Cumulus 1 users, and the support forum saw posts from a number of users who were struggling to get MX to recognise their Cumulus 1 files.


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 relates to Version 3.3.0, which was the MX release that was in use at the time.


<div style="background: LemonChiffon;padding:5px; margin:2px;">
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document was written for a MX release that is no longer latest!
[[File:Crystal Clear info.png|40px]] This page was last partially updated for the MX release available in June 2021; that is no longer latest!


The text needs to be updated so that it covers those who move from Cumulus 1 to a version of MX  up to 3.5.y (which is an easy transition), and those who subsequently move to the latest MX release and wish to take advantage of extra functionality that provides.
Appeal to contributors: Please work out any updates needed for this page, so it is kept correct for more recent releases!
</div>
</div>
{{TOCright}}




= Considerations when moving between Cumulus flavours =
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?=


NOTE: This section is based on Steve Loft's wording taken from the support forum with minimal alteration for its new context.  It therefore applies only to beta MX.
The legacy Cumulus will never be updated, and as more people migrate to MX there will be fewer people to help you if the legacy cumulus software gives you a problem. MX has a major advantage it runs on more devices, and for example a Raspberry Pi computer is far cheaper to leave on all the time to run MX (knowing it will never be rebooted by Windows updates). The current developer of MX offers support, and other people are also gaining expertise, so if you have a problem you will get help.
 
You can move between [Cumulus flavours] fairly easily, but you should really read all the guidance.
*In particular if you use decimal commas with Cumulus 1, then you MIGHT have issues when MX tries to read existing log files.
*[For separator characters in dates and lists] whilst Cumulus 1 only takes settings from the control panel in Windows,
** MX running in a Windows environment, takes settings from the locale you specify in a parameter when starting MX, or the Control Panel in Windows,
** MX running in a non-windows environment takes settings from the locale you specify in a parameter when starting MX, or the default locale in your Mono installation
** MX [may] take some [settings from] interaction between the two [the specified locale and the default locale], and MX may struggle to read file [lines] created by Cumulus 1 if the MX locale is not precisely same as settings when that file [line was] created.


==Should I migrate to MX or not?==


It is important to say up front that MX started with very little of the functionality that the original Cumulus offered, but over time MX has gained more and more functionality. Features in the original Cumulus have been gradually added to MX, but also MX offers a lot that is not in the original Cumulus. See [[Compare_C1_and_MX|Compare C1and MX]] page for more on this.
Of course MX started with very little of the functionality that the original Cumulus offered, but over time MX has gained more and more functionality. Features in the original Cumulus have been gradually added to MX, but also MX offers a lot that is not in the original Cumulus. See [[Compare_C1_and_MX|Compare C1and MX]] page for more on this. Unfortunately, there is no list anywhere of all features in Cumulus 1. [[About_Cumulus|About_Cumulus does not cover all features]]. Nor is there a list of features still to be introduced into MX. Therefore it is hard to help you understand whether functionality changes between the flavours will suit you.


There are Cumulus users who tried MX, then have migrated back (from MX) to the legacy product; either on a temporary basis (to use a missing feature before they return to MX) or in a very few cases decided to stay with Cumulus 1 (because they prefer it). It is worth noting here that the legacy Cumulus is a stable product with very few bugs, but MX is constantly being developed and thus likely to contain bugs (these obviously vary depending on release as some are fixed and others appear). To put this in context, MX now has a huge amount of functionality and it is difficult for the developer to test all the different features.
There are Cumulus users who tried MX, then have migrated back (from MX) to the legacy product; either on a temporary basis (to use a missing feature before they return to MX) or in a very few cases decided to stay with Cumulus 1 (because they prefer it). It is worth noting here that the legacy Cumulus is a stable product with very few bugs, but MX is constantly being developed and thus likely to contain bugs (these obviously vary depending on release as some are fixed and others appear). To put this in context, MX now has a huge amount of functionality and it is difficult for the developer to test all the different features.


== Moving files from Cumulus 1 to MX beta==
Cumulus 1 creates a [[Speciallog.txt|special log]] containing just temperature and humidity values, this is NOT available in MX.


There are some complications to take account if you try to use files created by the legacy Cumulus software when you swap to using MX, but that should not stop you migrating. It might mean that you choose to make your MX migration as an experiment, and maintain the ability to go back to the original Cumulus software until you are sure all your existing files have been transferred successfully.
Although from version 1.7.5 onwards the original Cumulus counts air frosts and gale days, this feature is not in MX.


===Configuration file===
The [[Cumulus_Screenshots#View_data|This Period]] screen that is a popular feature of the original Cumulus software as it tabulates data simply, is not available in MX.


It can be slightly confusing that the [[Cumulus.ini (Cumulus 1)|configuration file in the legacy Cumulus software]] has the same name as the [[Cumulus.ini|MX configuration file]], as although there is some consistency between many of the parameters in both, there are also some key differences (especially for later MX releases), and many parameters used by Cumulus 1 will be ignored by MX.  Any ex Cumulus 1 main configuration file will gain a lot of new entries (that may upset Cumulus 1) once it has been processed by MX. In fact in your first run of MX you will have a lot of settings pages (on the admin interface) to work through to ensure all the new settings are correctly initialised.
=Migrating from original Cumulus to beta MX=


If you are '''running MX on Windows''', filenames are not case sensitive, so MX will recognise "Cumulus.ini" or "cumulus.ini". But although Cumulus 1 might recognise "Cumulus1.ini" or anything else other than "Cumulus.ini". MX only recognises "Cumulus.ini". If you are planning on '''running MX on another device''', filenames are case sensitive, and your Cumulus 1 configuration file must be called "Cumulus.ini" with an initial capital followed by lower case, so it might need to be renamed.  
The beta builds (version 3.0.0) of MX were designed to make it easy to migrate. This section is based on Steve Loft's wording taken from the support forum with minimal alteration for its new context.


====Examples of parameters that you might need to replace====
You can move between [Cumulus flavours] fairly easily, but you should really read all the guidance.
*In particular if you use decimal commas with Cumulus 1, then you MIGHT have issues when MX tries to read existing log files. 
*[For separator characters in dates and lists] whilst Cumulus 1 only takes settings from the control panel in Windows,
** MX running in a Windows environment, takes settings from the locale you specify in a parameter when starting MX, or the Control Panel in Windows,
** MX running in a non-windows environment takes settings from the locale you specify in a parameter when starting MX, or the default locale in your Mono installation
** MX [may] take some [settings from] interaction between the two [the specified locale and the default locale], and MX may struggle to read file [lines] created by Cumulus 1 if the MX locale is not precisely same as settings when that file [line was] created.


It is very difficult to list here which parameters you need to replace as it depends on your set-up. By set-up I mean which weather station type you use, which functionality within Cumulus you use, and which MX release you are installing. Thus treat what appears below as just examples, not a definitive guide.
While MX was in beta, there was limited documentation about what features were included and why, there was some fault reporting and a tracking list that showed when some of those issues were fixed, also initially the documentation on how MX had implemented features it did have was very sparse. The lack of a list of features in Cumulus 1, meant it remains difficult to track which Cumulus 1 features are or are not implemented in MX. Steve Loft said parts of MX were simply machine code level copies of parts of Cumulus 1 functionality, and parts were trying to offer better functionality, but he never said what was included in these two categories.


If you use the standard trends web page:
There was a list of enhancements requested by users for Cumulus 1, but that list was deleted before work on MX started. Despite that, it does seem that some features that were on the now lost list of enhancements for Cumulus 1 that never got implemented in Cumulus 1, have been implemented in MX, although again there is no definitive documentation.
*Replace: '''IncludeSTDImages=1''' (Cumulus 1) by ''IncludeGraphDataFiles=1'' (Cumulus MX) in [FTP site]


If your weather station uses a serial port type connection:
=How to install MX=
*Replace: '''Port=n''' (Cumulus 1) where n is a number, by ''ComportName=COMn'' (Cumulus MX on Windows) where the value is a string where n is same number, or replace by '''ComportName=/dev/ttyUSB0''' (CumulusMX on unix device) where the actual device name might need to be different if you have multiple USB ports.


If you use a RG11 rain gauge:
The basic instructions for installing MX (see [[MX on Linux]], [[MX on Windows OS]], or [[Raspberry Pi Image]], as appropriate for fuller instructions):
*Replace: '''RG11port=n''' and '''RG11port2 =n''' (Cumulus 1) where n is a number, by '''RG11portName=xxxx''' and '''RG11portName2=yyyy'''  (Cumulus MX on Windows) where the value is a string with values as per previous paragraph depending on device on which Cumulus MX is running.
#Download the MX distribution (from [[Software]] for latest version or from https://github.com/cumulusmx/CumulusMX/releases if you want an earlier release version)
#Unzip into the location where you are going to install MX.


==== Parameters added ====
== 'Engine' and 'Admin Interface' for MX ==


I cannot give you a definitive list here on what parameters are needed by MX that will not be in a configuration file created by the legacy Cumulus software, this is because it depends so much upon which version of MX you install when you move from Cumulus 1 (and which weather station type you use).  A laborious way to discover what applies for you, is to work through all release announcements (starting at earliest in forum and ending at the release you have selected to install) for details. In the later MX releases, more and more of the parameters are set through web pages in the [[MX_Administrative_Interface#Changing_Settings|admin interface]] and so working through those pages will ensure all the extra parameters needed in the configuration file are set correctly for your installation. However in earlier MX releases, the web pages in that interface only include the "read-write" parameters, and there are many "read-only" parameters that need to be entered manually into the configuration file.  Because this page was created when the latter applied, it is likely that information later on this page will be obsolete (unless someone has done the necessary updates).
When you run the original Cumulus software it displays a screen (see [[Cumulus_Screenshots#Main_Screen]], and from there you navigate to other screens to view data or change settings.


MX is different, it consists of a stand-alone 'engine' which performs the reading and logging of data, uploading to a web site etc. This 'engine' is a command-line/terminal/console application which has no user interface. It does write diagnostic information to a [[MXdiags_folder|diagnostic log]], but many people run MX on a device that has no monitor and so the terminal output (if any) is not monitored.


===Compatibility for Data Log files===
When you successfully start MX, the engine is running, and it continues, until it is terminated by control C (or its equivalent in a Mac environment). (You can also run MX as a service, that has different ways to start and stop, discussed in the links given in previous section).


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 log files (both those ending in '''.ini''' and those ending in '''.txt''', and only adding extra fields to the end.
The separate [[MX Administrative Interface|admin interface]](unfortunately this is called various names in the support forum, including "user interface", "dashboard interface", and "admin interface") is provided by virtue of the engine acting as a web server. You can view the admin interface by typing the URL of the built-in web server into your browser, either on the same machine, or on a separate machine sharing the same local network.


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 using UTC was also a major factor in his failure to get Cumulus 2 to provide the functionality he had offered in the original Cumulus.
If you install MX on Microsoft Windows, then a few extra one-off steps are needed to allow this web server functionality:
#  Windows Defender has to be told to allow all for Cumulus MX.
#  Typically for other security packages, select "CumulusMX.exe" then right click and select "Change File Rating to Trusted"
#  In any "Firewall" package, add port 8998 as one that was permitted.
#  Using "command prompt as administrator" type  <tt>netsh http add urlacl url=http://http://192.168.1.64:8998/ user=\users</tt>, the response "URL reservation successfully added" means it worked. This command is apparently to allow all users to bind to port 8998 (i.e. that used for the Cumulus interface). This also means you don't have to run the engine (CumulusMX.exe) in an administrator user, nor select "Run as administrator" from right click menu on the shortcut, nor set the properties for any shortcut to run in any special way.


When Steve Loft designed Cumulus MX, he was able to learn from his experiences with both Cumulus 1 and Cumulus 2, and he decided to use dates to an ISO specification (ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times), but in the local time zone of the particular user, and therefore log files are not [https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=15167 backwards compatible]However those MX beta builds were designed to be forward compatible in that all date formats used by Cumulus 1 could be read, although MX would when rewriting any date change them to the new format.
The default URL if the browser is on the same machine as MX is http://localhost:8998/.  Newer releases of MX will tell you an IPv4 address to use, such as by typing "http://192.168.1.64:8998/".


After Mark Crossley took over development of MX, he initially retained much of the code created by Steve Loft. However after his release of version 3.5.4, he simplified much of the core code, and for dates in the data log files this means that MX can no longer read any dates that are not in the format used by the locale used for running MX. In an important example, this implies that while [[Dayfile.txt]] for Cumulus 1 could use any (non-space) character to separate the different parts of the date in the first field (and times in many other fields), MX now can only accept the character defined for separating parts of a date in the locale  (and only accept ":" for time separator).  
Equally, if "localhost" is already in use for another web server (that you already run on your device), unless you can differentiate purely by port number you may need to use the correct IPv4 address as above, even on the same device.


For security reasons, the admin interface should not be accessible via the public internet.


Key summary points (apply to MX beta and early MX releases up to version 3.5.4):
=Migrating existing data files from legacy Cumulus to a recent build of MX=
*Steve Loft designed MX beta so that in general it was able to read [[Category:Log Files|Data Log files]] created by the original (legacy) Cumulus.
**See individual articles (accessed from that link) for more details on such differences.
**'''Please note, most of the information for MX here is taken from notes by Steve Loft, and so it applies to MX 3.0.0.'''
* If you move from Cumulus 1 to a version of MX  up to 3.5.y, the transfer is likely to be significantly easier. This is because Steve Loft was keen to keep forward compatibility in his beta MX, and it took a while for Mark Crossley to revise the part of the MX code that reads log files.
** Cumulus 1 is tolerant of various separators for dates and times.
**Cumulus MX 3.0.0 insists all times use a colon separator (says Steve Loft), and all dates are in ISO format.
*This means, '''MX releases from version 3.0.0 to 3.5.4''' can read the date/time entries in the Cumulus 1 format and in the MX format.
*When the MX software needs to update a particular entry (e.g. an extreme) in a particular file, it will subsequently save the file and change the content for the affected line to the new format.
*Consequently, within a single file both formats will co-exist, you may see lines using Cumulus 1 format for the extremes that have existed for a while, and Cumulus MX format for any new extremes.
 
===Update as at MX release 3.7.0===
 
In particular '''internal''' changes mentioned in release announcements for various 3.6.x versions, and for release 3.7.0, have made MX work significantly differently and it is now more fussy about content of log files having to be in correct MX format.
** It is difficult to move from Cumulus 1 to a release of MX that is 3.6.z or higher, mainly because you may find that Cumulus 1's .txt, and .ini, files can no longer be read.
**This is because '''for releases 3.7.0 onwards''', each log file in modern MX releases must have lines that match what is in the local settings absolutely perfectly;
**For Example: this means MX is now very fussy about the symbol that separates the 3 parts of a date, very fussy about decimal symbol, and expects the number of parameters/fields in files to be consistent with release 3.7.0.
**Thus modern releases are less tolerant of log files created by the original Cumulus software;
 
===Note for MX release 3.10.0===
 
This is when even more changes were made with regard to configuration settings, and has invalidated more of the documentation on this page. However, the author who created this page has not upgraded to later MX releases and is unable to update this page. When somebody else updates this page, this section should be updated to reflect the revised position.
===General points===


* 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 change first letter to a capital even when a file that must be all lower-case is being described.
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 quite a bit to read, taking up most of the rest of this Wiki pageThe Cumulus configuration files for Cumulus 1 and for MX share the same name, but their content is very different, so these are discussed at length in subsections below.
* Cumulus 1 is reasonably tolerant of numbers using a comma to separate the integer and decimal part of real number.
** MX 3.0.0 will accept both decimal commas and decimal full stops in the standard log files, the extra sensor log files, and the daily summary log file.
**In all versions of MX, the software expects periods/full stops in .ini files regardless of the locale in use, please see the [https://cumulus.hosiene.co.uk/viewtopic.php?f=27&t=12908 Cumulus MX Announcements and Download - PLEASE READ FIRST] for details, but generally if you want to transfer these files from Cumulus 1 to MX, it is best if '''you edit them so all decimal numbers have a "." between the integer and decimal parts'''.
* In individual articles, any differences in the precise content or format within individual files will be highlighted.


== Key differences and similarities between Cumulus 1 and MX ==
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


NOTE: This section is also based on Steve Loft's wording taken from the support forum with minimal alteration for its new context.
==File names==


* While Cumulus 1 has a tool to generate graphs itself and then uploads them to your website, the graphs used in Cumulus MX are drawn when the end-user loads the web page, they use Highcharts routines that are free for non-commercial use only, i.e. you may not use MX with these graphs on a company web site.
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, so do check carefully if that wiki page is describing a file name that must be all lower-case.
* While Cumulus 1 runs as an application that includes a main screen, and other screens, that appear when you start it, Cumulus MX is two separate applications, there is the "engine" that connects to your weather station and processes that data, but there is also a separate administrative interface. The latter is viewed on a browser ''on any device connected to the same local network'' as the device that runs the engine. On this admin interface you change settings, you can edit the various logs, and you can view a series of web pages that allow you to see all the weather derivatives output from MX.
* The settings for Cumulus 1 are held in [[Cumulus.ini_(Cumulus_1)|'''cumulus.in''']] and those for Cumulus MX in [[Cumulus.ini]]. For MX the file name is case sensitive [on non-Windows devices] and must have capitals where shown.
**The case sensitivity of MX [on all devices, even Windows,] also applies to the section names within the file e.g. [FTP site] must use capitals for the FTP and must use lower case for site. Edit any section names that do not follow format in the wiki article for this file referenced above.
**All the characters used within this configuration file must be within ASCII range (represented by binary 0 to 127, basically A to Z, a to z, 0 to 9, and some punctuation), any extended characters (such as those used for accented characters, symbols and non English characters) must be removed.
**Whilst many settings are common between both flavours, some are not used by MX and MX has some new ones. In particular if you used '''Port''' in Cumulus 1, that will not be carried across to MX, and you will need to set '''ComPort''' instead. You are advised to check all '''Settings''' using the MX admin interface.
*The contents of your Cumulus 1 '''Reports''' folder (NOAA style reports) do not need to be read by MX as it creates new files and does not read old ones (although you may need to edit the setting that determines the way months are represented to ensure the name of newly created files matches format used in older files).
*The contents of your Cumulus 1 '''data''' folder (log files ending with extension '''.ini''' or '''.txt''') can NORMALLY be read by MX (but see points listed below).
**'''The statement above is not always true''' for [[Dayfile.txt]], newer releases of MX attempt to read the whole file as they start up, and will abort if (for any individual line) the date format in the first field does not match the format in the '''locale''' used when MX was started, will object if any decimal field has the wrong character used for that decimal point/comma, will complain if any time does not use colon as separator, and will fail if the field separator is not a consistent character!
**There is another potential problem, if you use decimal commas in your Cumulus 1 '.ini' files then you do need to change, in each stored value, the decimal commas into periods/full stops.
**MX when it needs to update any '''.ini''' files will change the way dates are stored, see the [[:Category:Log Files|Log File]] pages in the Wiki for more information.
** The remaining '.txt' files in the data folder will work with both Cumulus 1 and MX - assuming you are using the same decimal and list separators in MX as you used in Cumulus 1 (i.e. the same locale).
*The Cumulus 1 web templates (files using web tags) will not work with MX (whether you use the standard files provided or have written your own replacements)
** Newer MX releases do not use HTML template files at all, they can optionally use default web pages on your server that obtain the necessary weather information from '''.json''' files that are (optionally) generated and (optionally) file transferred to your web server. Please see [[Default Website Development]] page for more information.
** Older MX releases do use web templates that contain [[Webtags|a series of web tags]] to represent the weather information; but the tags for MX and Cumulus 1 are not interchangeable. For any web templates you have written, you will almost certainly need to change some web tags, and you may find this difficult because certain formatting characters (e.g. H or M) have different meanings when they appear in isolation in an output format to what they mean when combined with others (e.g.H:mm or 'd M'). See the [[Webtags]] page for full information on how to change these, and ask in the support forum if you have difficulty.
*MX releases also contain lots of extra utilities, that are not described here. (Other file names within MX will be as supplied in the zip that you download, or as Cumulus MX decides when it creates the file).
* The settings 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. If there is no Save button anywhere on the screen (as in Extra Web Files) then the setting is saved when you move to next field/line.


'''MX runs on a number of operating systems'''
==Line terminators==


Consequently if you are moving from Windows to (for example) Linux, remember you need to learn a host of new commands!  The [[Setting up Raspberry Pi]] page might help you, but  [[Raspberry Pi Image]] describes a simpler way to install MX (assuming you have another device linked to your RPi to do downloads and micro-SD card preparation).
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 every file you move from Cumulus 1.


=Features and functionality=
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!


== Cumulus 1 features not ever going to be included in MX ==
With Cumulus 1 (or MX) on Windows, each line in every file ends with both carriage return and line feed.


Unfortunately, there is no list anywhere of all features in Cumulus 1. [[About_Cumulus|About_Cumulus does not cover all features]]. Nor is there a list of features still to be introduced into MX. Thus this section is neither authoritative nor definitive.  It is possible that functionality listed here might be considered in the future, but I have seen no hint of it being considered.
With MX on a Mac, each line should end with just a Carriage Return.


One big feature that Cumulus 1 had was this '''view period''' screen as illustrated here and described above, where you could specify any start and end dates, so it was easy to see a summary for any day in the past, any week in the past, any month, year or season, whatever you needed. MX does not offer anything tabular option like this.
For all Unix-based operating systems (Linux, Raspberry Pi OS, and other variants), each line should end with just a Line Feed.


Cumulus 1 creates a [[Speciallog.txt|special log]] containing just temperature and humidity values, this is NOT available in MX.
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]].  


Although from version 1.7.5 onwards the original Cumulus counts air frosts and gale days, this feature is not in MX.
If you use PHP Hypertext Pre-processor anywhere on your installation, normally that is written for "Line-feed" as line terminator and any "carriage return" in your files may mess up the content unless you code in a "trim" function to remove it. Hopefully, if you use PHP, you are technical enough to realise you may need to edit the code depending on which device it is being run on!


== Cumulus 1 Functionality Missing in beta MX ==
==Configuration file==


Many other features of Cumulus 1 were missing in the beta MX, as written by Steve Loft.
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!


However, subsequent developments headed by Mark Crossley have now added the majority of the missing features and the list of missing features added is below.
'''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.'''


It is still difficult for a Cumulus 1 user to work out the disadvantages of leaving Cumulus 1. There are some obvious advantages in moving to MX, there are a lot of extra new features, there is ongoing support in the forum, and there is prospect of more improvements in the future. Cumulus 1 will never be enhanced.
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.


== The look for web site  ==
===Configuration file naming restrictions===


Cumulus 1, and later Cumulus MX versions - generate a moon image that can use FTP to place it on your web site.
Cumulus 1 can recognise, in some circumstances, "cumulus1.ini", and other variants, not just "cumulus.ini".  


Cumulus 1 generated a number of chart images. MX generates a number of JSON files with data for graphs instead.
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.


The "bird" image used as a background on standard web pages is still provided with MX.
===Historical evolution of configuration file===


The actual web pages provided in MX fulfil same range of outputs as Cumulus 1, but these are not interchangeable.  
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.  
*The Trends page of Cumulus 1 will not work as that simply displayed uploaded images, the MX Trends page uses HighStock to draw graphs from the data pairs in the uploaded JSON files.
*The old gauges page is replaced by Steel Series gauges.


== Enhancements during Beta stage for MX and after MX came out of beta ==
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.


While MX was in beta, there was limited documentation about what features were included and why, there was some fault reporting and a tracking list that showed when some of those issues were fixed, also initially the documentation on how MX had implemented features it did have was very sparse. The lack of a list of features in Cumulus 1, meant it remains difficult to track which Cumulus 1 features are or are not implemented in MX. Steve Loft said parts of MX were simply machine code level copies of parts of Cumulus 1 functionality, and parts were trying to offer better functionality, but he never said what was included in these two categories.
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.  


There was a list of enhancements requested by users for Cumulus 1, but that list was deleted before work on MX started. Despite that, it does seem that some features that were on the now lost list of enhancements for Cumulus 1 that never got implemented in Cumulus 1, have been implemented in MX, although again there is no definitive documentation.
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.


The documentation that does exist is the release notes issued by Steve or Mark. In the next few sections, an attempt is made to prećis such announcements to track when the basic functionality from Cumulus 1 made it into MX.
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.  


Of course weather station design evolves,  and the sensors available vary. Thus another feature of MX development is adapting to new weather station dongles and new sensors (which obviously cannot be added to Cumulus 1). Once MX came out of beta, the changes in each release are being tracked in another [[Cumulus_MX_formal_release_versions|article]]. Obviously, you still need to look at the support forum for the detailed information in full release announcements about fixes, functionality changes, and actions needed to update to new major versions.
===Subsequent evolution of configuration file===


= The difference in how a Cumulus 1 user and a MX user see current values and change settings =
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.


== Cumulus 1 ==
More changes were made in 3.10.0, and subsequent releases, as settings that previously had to be made directly in file were gradually moved to be advanced settings controlled in the admin interface.  In addition, these releases, have added many new settings never encountered in your legacy software. 


Cumulus 1 was an all in one application, it both read the data from the weather station and provided the user interface for you to see the derived data and change the settings.
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.


== 'Engine' and 'Admin Interface' for MX ==
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.


MX is different, it consists of a stand-alone 'engine' which performs the reading and logging of data, uploading to a web site etc. This 'engine' is a command-line/terminal/console application which has no user interface. It does write diagnostic information to a [[MXDiags_folder|diagnostic log]], but many people run it on a device that has no monitor and so the terminal output (if any) is not monitored.


When you successfully start MX, the engine is running, and it continues, until it is terminated by control C (or its equivalent in a Mac environment).
===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. 


The separate [[MX Administrative Interface|admin interface]] is provided by virtue of the engine acting as a web server. You can view the admin interface by typing the URL of the built-in web server into your browser, either on the same machine, or on a separate machine sharing the same local network. The default URL if the browser is on the same machine as MX is http://localhost:8998/.
Be aware that you should restart MX after changing many settings.  This is because many settings are only written to configuration file, not yet to internal code, and such settings are only read from configuration file when MX starts. The developer is changing the code, so that in more cases edits on the settings pages do update the settings used by the code, as well as the file, but at time of writing there is no list of which settings work like that, and which require a restart.


If you are using the browser on a different device on your local network to the device running MX, you cannot use that local host shortcut. Instead you specify a IPv4 address, that is listed in your router (might be called a hub) for the device running MX, this IPv4 address will look like '192.168.y.z' (where y and z are numbers that vary between implementations).
===Start date===


Equally, if "localhost" is already in use for another web server (that you already run on your device), unless you can differentiate purely by port number you may need to use the correct IPv4 address as above, even on the same device.
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 security reasons, the admin interface should not be accessible via the public internet.
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.


= Operating Systems for Cumulus 1 and MX =
'''CumulusMX.exe''' uses this parameter to determine the first standard data file to start reading from, it will ignore any data files for earlier dates, it will also ignore any lines with an earlier date in the first data file. Thus if you were to migrate your Cumulus 1 configuration file into MX, you should check the [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter in the '[Station]' section is correct for your earliest data before you let MX read this configuration file for first time.  If you need to make any edit, ensure you stick to exactly the same date format.


As expressed by Steve Loft MX runs on:
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, because of the importance of sticking to exactly the right date format when you edit it!


# Microsoft Windows operating system (Cumulus 1 only runs on this)
=== Station connections===
#* To run MX on Windows, you need .NET installed which is included on Windows 7 upwards.
# Unix derivatives Linux and Mac OS X.
#* To run MX on the additional platforms, it requires the Mono runtime, and you will need to install this


''You can skip this subsection if your weather station connects to MX either by USB or by wireless connection''. 


= Changing from Cumulus 1 to MX=
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 you are going to run MX on  a different device to that running Cumulus 1, see [[Setting up Raspberry Pi]] article for details.  Although those notes are applicable to Linux operating systems, other Unix based systems, and those using the Mac operating system also need '''Mono''' to be installed. There is more information  about Mono in the main [[Cumulus MX]] article, and you should also read that.
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'''.  


The remainder of this article was written assuming you are installing MX on the same Windows Operating System as you used for running Cumulus 1. However, the files that you need to copy across from your Cumulus 1 installation to your MX installation remain the same whatever device you are installing MX on, although you may need to use File Transfer Process or a USB storage device to move the files to the new device.
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'''.  


== Cautions to be aware of should you already use library software prior to installing MX ==
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. 


*If you have been using Cumulus 1, and you decided to customise your web site:
A typical parameter value for other serial connecting devices might be "/dev/ttyUSB3" where the final digit will change depending on the new connection. You can search for posts on the support forum that talk about how to find out what connection is being used, depending on what hardware you are using.
**you may already be using highcharts, jQuery, bootstrap, and other library software
** and you may have selected to load latest versions for maximum functionality.  
*You might be enhancing what is provided with Cumulus 1,  
*or you might use your web site for other purposes (not just Cumulus).  


*If so, you may find some Cumulus MX web pages do  not work correctly.
===RG11 Rain gauge===
**This is because Cumulus MX uses obsolete versions of library software and the way it is coded means MX is not compatible with current versions.
**For Cumulus MX to work you need to ensure the versions of such software loaded for your web pages, are not used by your browser when viewing MX admin interface or MX web pages.


*Equally, ensure that the versions of library software loaded by MX, do not stay loaded when you wish to view any of your web pages that use these libraries, as your desired functionality might be limited by the library versions MX uses!
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)


== Files to copy from Cumulus 1 into where you are installing MX==
The new value is a string with values as per previous paragraph depending on device on which Cumulus MX is running.


Subsequent sections will deal in more detail with various aspects like editing existing files, that are relevant to all the approaches below.
===Other Cumulus.ini parameters===


But first, let us focus on what to do to actually get the MX release distribution installed. It does not come with a installer, it comes as a zip of all the files that are needed. So first we will summarise the MX install options for someone currently using Cumulus 1, then we will explain the approach in more detail both in respect of that install of MX and the incorporation of Cumulus 1 files.
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!


There are three approaches to installing a MX release distribution zip:
==Strings.ini==


#Install MX OVER your Cumulus 1 installation (this only works if you want to run MX on same PC as you have been running Cumulus 1)
This is another configuration file, but it is an optional one. Please remember that the Microsoft Windows Operating System is case insensitive for file names, so "Strings.ini", "STRINGS.INI", and "strings.ini" are all treated as the same file by any Cumulus software.
#*This means that all your existing files will be available to MX
#*This is simplest approach for those who want a simple install
#*You may need to edit a few files, please see references to files that might need editing later
#*Because you have Cumulus 1 and MX executables in same location, you would expect it is easy to run either, but as already explained some files can  not be read by Cumulus 1 after MX has changed their content
#Take a copy of your Cumulus 1 installation and store that copy where you can use it if you want to return to Cumulus 1
#*In original Cumulus 1 location, delete Cumulus.exe (or whatever your Cumulus 1 executable was called)
#*Now follow the instructions for first approach, installing MX over the existing files (but ignore the point about running both executables)
#Install MX in a NEW location (this might be on your PC that was running Cumulus 1 or onto another device such as a Pi)
#*This approach requires you to manually copy various files from old folders to new location
#*MX requires all files from "data" and "Reports" folder created by Cumulus 1.
#*You also need "strings.ini" (if you use that), and "Cumulus.ini_(Cumulus_1)", plus any other tailoring set-up files, batch processes etc. you might use.
#*This approach is generally easier if you want to be able to go back to running Cumulus 1


=== 1: SIMPLE OVERWRITE APPROACH===
If you install MX on another operating system, then the file system is case sensitive, in this case MX will only recognise "strings.ini".


Unzip the MX download (from [[Software]] for latest version or from https://github.com/cumulusmx/CumulusMX/releases if you want an earlier release version) so the folder '''CumulusMX''' is the same folder as that which has "Cumulus.ini_(Cumulus_1)" in it.  The unzip ensures all the files that need to be in sub-folders go into correct sub-folders.
If you have not created a [[Strings.ini|strings.ini]] file in your (leagacy) Cumulus top level folder, then you have no file to move to your MX installation, and you should skip the rest of this sub-section.


Your [[Category:Log Files|log files]] in the data folder and any NOAA reports you may (they are optional) have created in Reports folder are available to MX. You should read the page in that log file link, as you might need to edit some items in the '''.ini''' filesFor the '''.txt''' files, you need to check that all lines are consistent in using the same character to separate the 3 parts of the date, and the same character is used throughout to separate the items in list of fields.
The contents of the [[Samplestring.ini|samplestring.ini]] file you get in your MX release distribution varies depending on the release you have downloaded.   


*Cumulus 1 will accept any character (except space, a digit, or the character used to separate fields in a list) as a separator for the date parts
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''.
* MX will only accept the character defined in your locale (for a Windows pc that is actually set in Control Panel which Windows does not make easy to access preferring you to use its Settings app.
*There is a Clock and Region section in Control Panel and in the Region window you '''define the separator MX will use in the Short date item''', most easily by clicking additional settings).
*Now ensure that is same character as used in al lines of your .txt log files.
** If you have some lines using say "/" and some using "." or "-" as date separator, then there are many editors available that offer a global replace.
***As an example, Notepad++ has a '''Replace All in All Opened Documents''', so you can open multiple documents and do a global replace of "/" into "-"  very easily. Notepad++ saves the file in the same encoding as it was before, but you can also check it is UTF-8 with no Byte Order Mark via the menus.
***Note that you cannot easily replace "." or "-" globally in dates, because those appear as valid characters in fields. To edit those, you would need to open the files in a spreadsheet editor like '''Libre Office''', you need to ensure that the dates column is treated as text, then select that column and do a replace in just the date column, and then save as a CSV format file changing the extension to .txt. There is more information on this in relevant log file articles.
**The basic Microsoft Notepad that comes with Windows has a Replace option in its Edit menu, but some versions of this editor (check '''Save As''' options) don't allow you to pick "UTF-8" encoding (if that is not already shown) when saving to ensure MX can read the output.
**Also be aware when using Google editors that they may save the file in the wrong format unless you can choose a UTF-8 no BOM option.


=== 2: COPY C1 AND OVERWRITE ORIGINAL WITH MX APPROACH ===
==NOAA style reports==


Alternatively, to run Cumulus MX with your existing Cumulus data, first take a back up copy of your existing Cumulus directory.
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.


Next obtain the MX distribution release as a zip as per previous option.
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!


Now unzip Cumulus MX into the original Cumulus folder. The new CumulusMX.exe should end up in same folder as existing Cumulus.ini_(Cumulus_1), there will be other files in this folder, and there will be some new folders you have not seen before like '''interface''' and '''MXDiags''', but MX continues to use the existing sub-folders without any change of name.  
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.


This saves you from copying any of your Cumulus 1 files, they just stay where they are and get used by MX.
=="data" folder==


Where your existing [[Cumulus.ini_(Cumulus_1)]] file makes reference to local folders (in say Extra Web Files), those references stay valid.  The only edit you will make to configuration that affects Cumulus.ini_(Cumulus_1) is dependent on your weather station type, as explained later MX uses a different parameter to refer to the port used by the weather station.
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, but as mentioned earlier there are some complications:
* 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 [[#Extreme Record files]] later on this page, and [[:Category:Ini Files]], for information on differences between the legacy files and the MX files
* 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.


Be aware that MX changes the date formats in some files, so that Cumulus 1 can no longer understand them, so be cautious about copying log files (.ini and .txt) back to your Cumulus 1 back-up should you want to revert to using Cumulus 1.
===Standard log files and other log files===


Some other issues that were described in previous sub-section will apply in this case, because for MX this approach (preserving Cumulus 1 in a new location) is no different to previous.
The [[Speciallog.txt]] file optionally used by the legacy Cumulus 1, is not used by MX.


=== 3: NEW LOCATION APPROACH===
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.


These notes apply whether you are installing in a new location on your PC or installing MX on a different device.
MX extends these [[Monthly log files]] by adding [[Air_Link_Log.txt|another optional set of files]].


Obtain the MX download (from [[Software]] for latest version or from https://github.com/cumulusmx/CumulusMX/releases if you want an earlier release version).
===Weather Diary===


When you do the unzip as explained below, it ensures all the files that need to be in sub-folders go into correct sub-folders. You then add various folders and files from your Cumulus 1 installation into correct places. As said before, this sub-section gives only a brief mention of possible issues with existing files, later sections will explain those in more detail.
As explained on [[Weather_Diary|weather diary]] page, the Cumulus 1 weather diary uses a different file to MX, and indeed takes a very different model for how to store the information.


#First create a new directory (recommended name CumulusMX) and unzip the contents into it.
Therefore don't copy [[Log.xml]] file into the data folder of your MX installationYou will need to manually use the [[Weather_Diary#How_to_edit_the_contents|admin interface Edit menu]] to access the new diary and add your previous entries one by one.
#*For a pi, the instruction might be <tt>unzip -o CumulusMXDist3'''nnn'''.zip</tt> where '''nnn''' is the last 3 digits of the build number.
#Then copy (or file transfer over)
#* your previous '''data''' folder contents into the new data folder created by unzipping, as before you might need to edit some log files
#*your previous '''Reports''' folder contents (if any) into the new Reports folder created by unzipping
#*your Cumulus.ini_(Cumulus_1) file goes into the top level folder, the one with ExportMySQL.exe, CumulusMX.exe and the .dll files,
#** Check that destination file, it must be "Cumulus.ini_(Cumulus_1)" (ensure it starts with capital letter and all other letters are lower case)
#** In the new "Cumulus.ini_(Cumulus_1)" edit any lines that made reference to the old windows location. Remember, that only windows uses "\" in paths, and your new device will require reference to new locations. Even if you are still using windows, you may need to make changes to reflect that the files are now in a new location.
#**You can delay changing other settings (like the port used to access your weather station which uses a different parameter in MX) when you have access to the Settings pages in the MX admin interface
#* any other configuration files that you may have created (e.g. strings.ini, twitter.txt etc).


The big advantage of this approach is that anytime you are not running MX you can go back to Cumulus 1 and let it run from where it left off (subject to availability of past data in your weather station, and possibly unplugging weather station from one device and plugging it into PC). Obviously you cannot run Cumulus 1 and MX at the same time accessing the same weather station (even if both are on same device and so no unplugging and plugging in is needed).
Please note the editing interface has been changed from release 3.10.1, but the page linked to above may not have been updated. A major change in the upgrade relates to handling of time-zones.


== Editing files==
Please also note that the Cumulus 1 weather diary permitted multiple entries to be stored for an individual day, but the MX implementation only permits a single entry per day.  Also the configuration file defines a time when the entries stop applying that may not match the rollover time for other weather measurements.


Do remember that with Cumulus 1 on Windows, each line in every file ends with both carriage return and line feed. If you are moving to MX on a Mac, each line should end with just a Carriage Return. For all Unix-based operating systems (Linux, Raspberry Pi OS, and other variants), each line should end with just a Line Feed. There are various editing tools that can do the necessary modification of all lines for you in just a couple of clicks; one such tool is Notepad++ (which although mostly used on PCs, can be used in other operating systems).
==Extreme Record files==


===Cumulus.ini_(Cumulus_1)===
The [[Correcting_Extremes]] page explains how extreme records are stored in the [[:Category:Ini Files]] discussed below, with the changes to all-time records being  tracked in [[Alltimelog.txt]].


If you are running MX on Windows, filenames are not case sensitive, so MX will recognise "Cumulus.ini_(Cumulus_1)" or "cumulus.ini". But although Cumulus 1 might recognise "Cumulus1.ini" or anything else other than "Cumulus.ini_(Cumulus_1)", MX only recognises "Cumulus.ini_(Cumulus_1)".
You will find that MX creates at least one file that was not in the older Cumulus ([[Correcting_Extremes#How_do_I_correct_my_monthly_all-time_records.3F|monthlyalltimelog.txt]]).


If you are planning on running MX on another device, filenames are case sensitive, and your Cumulus 1 configuration file must be called "Cumulus.ini_(Cumulus_1)" with an initial capital followed by lower case, so it might need to be renamed.
===the .ini files===


If you read the [[Cumulus.ini_(Cumulus_1)]] article, you will see that some parameters in the configuration file are only used by Cumulus 1, some only by MX, and some apply to both. MX will ignore any Cumulus 1 parameters it does not recognise, so you don't need to edit out lines. MX will also add any parameters it needs as read/write parameters for its settings, so in general you do not need to add them manually, you can simply set them using the relevant page in the settings part of the admin interface. There are of course a number of read-only parameters (these are ones that are entered directly into the configuration file and cannot be edited using settings), and there are some of these that are Cumulus 1 only and some that need to be added manually if you want to change the default.
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.


There are a few exceptions to the above paragraph, if you look at [[Cumulus.ini_(Cumulus_1)#Parameters_changed]] you will see the list of a few parameters that '''may need to be changed''' in this configuration file (it depends on what type of weather station you use). But you don't need to look them up as they are also mentioned in next 2 sections (station settings and web pages) below.
====MX releases up to 3.5.4====


There are also some differences in how some parameters in this file are used in the 2 flavours.
'''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)


One to remember now is to check the "StartDate=" line in the '[Station]' section is correct for your earliest data before you let MX read this configuration file for first time, as '''CumulusMX.exe''' uses that to find the first log file to start reading from, it will ignore any log files for earlier dates; whilst Cumulus 1 and '''ExportMySQL.exe''' can process all log files in the data folder as they look for file name pattern and do not check dates.
* '''MX releases from version 3.0.0 to 3.5.4''' can read all the date/time entries in any file whether in the Cumulus 1 format or in the MX format.  
* MX will change any dates to the ISO format only when it needs to update that particular date/time. 
* Consequently, within a single file both formats will co-exist, you may see lines using Cumulus 1 format for the extremes that have existed for a while, and Cumulus MX format for any new extremes.


It is advised that you work through all the MX settings screens once you have the [[MX Administrative Interface|Admin interface]] working, ensuring they do represent how you want MX to work.  Some of the settings are for functionality you did not have in Cumulus 1 versions, and for these you will need to look up the link earlier in this sub-section.
If you used decimal commas in your Cumulus 1 installation, you will make the migration to MX easier, by an edit of each ".ini" file to change those commas to full stops.


For the read-only settings in Cumulus.ini_(Cumulus_1), you may need to read the documentation in the forum.  The Cumulus.ini_(Cumulus_1) article in this wiki has had read-only parameters added to it now, but it is impossible to know if all have been covered there.
Equally, if you had any times not using a ":" as separator, you will make the migration to MX easier, by an edit of each ".ini" file to change those characters into colons.


== Station connections==
====MX releases at versions 3.6.x onwards====


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 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 screen, but that is stored within Cumulus.ini_(Cumulus_1) in the station section as Comport=tttttttt. If your old number was 3, and you are still using Windows, the new setting would have value of COM3, for other devices it might be /dev/ttyUSB0.
Migration from the legacy Cumulus to MX has become harder as MX has been developed for two reasons:
# It appears that releases at versions 3.6.x onwards have become more fussy about existing content in these files due to changes in the source code.
#* Effectively, the format of existing entries is expected to be same as any newly created entries, i.e. matching current locale settings
# The addition of Feels Like temperature and Canadian Humidity Index (Humidex) to the .ini files
#* Neither of these was stored by the legacy software or by earlier MX releases
#* The technique for adding this is described on [[Calculate Missing Values]] page


== web pages==
Despite this, most people migrating from Cumulus 1 to the newer MX releases, are doing so successfully, so it works for at least some old files.


There are differences in how to upload the standard files between Cumulus 1 and MX.
====Historical background to dates/times====


It is best to work through the Internet settings screen in the MX admin interface. '''INFORMATION HERE MIGHT BE MADE OBSOLETE BY MX DEVELOPMENT AFTER 3.7.0'''
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 logging files (both those ending in '''.ini''' and those ending in '''.txt''', and only adding extra fields to the end.


Consequently, there is a difference between the entries in Cumulus.in,  
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.
* for example remove the IncludeSTDImages=1 used in Cumulus 1
*and replace it with IncludeGraphDataFiles=1 used in MX.
*whilst the former included the moon image for Cumulus 1, the latter does not affect the moon image for MX


If you have been using the Cumulus 1 supplied web pages, you will find they do not work with MX, there is a new set provided with MX that work slightly differently.
When Steve Loft designed Cumulus MX, he was able to learn from his experiences with both Cumulus 1 and Cumulus 2, so he decided to use dates to an ISO specification (ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times), but in the local time zone of the particular user, and therefore log files are not [https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=15167 backwards compatible].
Cumulus 1 uploads a number of images, these include a couple of images that combined show the moon phase, and a number of graphs are also uploaded as images (used on Cumulus 1 trends page).
*Prior to release 3.6.0, Cumulus MX does not upload any images
*From release 3.6.0, Cumulus MX can upload a moon image (again derived from another base image), as an option (2 settings, one to generate, another to upload)
* Cumulus MX uploads a series of .json files that hold time and value pairs that can be used to draw graphs. (Hence the difference in settings mentioned above). Thus the trends web page works totally differently.
* The gauges page provided with MX is based on Mark's implementation of steel series, so it is different to the old "Web Dashboard Components for FreeWX and FreeWX-Wi " that Cumulus 1 used.
*  The other web pages look the same, and indeed are effectively functionally same. You might see some derivatives on MX pages that were not seen on Cumulus 1 pages.


= What I did to Install MX=
===dayfile.txt===


I have used Cumulus 1 for a decade or so, and been very happy with it, but I wanted to give MX a go without affecting my Cumulus 1 installation.  
MX (except early releases) reads the whole of this file as it starts running, so all lines must use exactly the same format.  


Here is exactly what I did on my ex NHS Windows 10 Pro PC, step by step; I am hoping this list might help some readers.
====date format issue====


Can I just stress I downloaded version 3.4.5 (build 3069), there may be some changes that affect what I record below in more recent versions, I just noted what I had to do at that moment in time (March 2020).  
For MX (from release 3.5.4 onwards), the date separator specified for the locale when you run MX must be used in all lines of this file.  Please see [[Amending_dayfile#Date_Separator_in_MX]] for more detail of what MX expects.


Do check, as the version of MX you choose to move to may have more or less, folders and files, included in the package.
Cumulus 1 allows the date that appears in the first field of each line to use any character (except space) to separate the day of the month, from the month, and from the last two digits of the year. Consequently "29/03/88", "29-03-88", and "29.03.88" are all acceptable in the legacy software (and indeed in some early MX releases).


== Download and unzip==
   
 
*See [[MX_on_Windows_OS#Parameter_for_changing_Locale]] for how to specify locale if you are running on Microsoft Windows (by default the locale settings are taken from the standard Windows settings application or Control Panel).
#I downloaded the CumulusMXDist3069 zip from the Current Release section on the downloads page. Although 3069 is no longer the latest distribution, still use the same link as it will always give you latest available.
*If you are running MX in a Linux operating system, the locale parameter can be used, but the default locale is determined by the mono-complete package, and that in turn depends on your device settings.
# I unzipped the contents into a partition I use just for software downloads.
#* You don't have to have somewhere separate to the installation, but many people will want to download on a separate device to the device where they will install MX
#* Downloading to somewhere other than where you will install it, also makes it easier if you do any customisation of particular files and wish to keep copies of originals.
# I used a package (no external software tools named here) that verifies the files it copies to duplicate the folder CumuluxMX within the zip onto the drive where I wanted to run Cumulus MX.
#  As I was not intending to use the web pages that come with MX, so I selected to exclude in this verified copying everything from the "\CumulusMX\webfiles\*.*" folder, and its sub-folders in the download.
#* If you intend to use the standard MX web pages, then you will need to:
#** Ensure you do copy these files from download into where you are installing MX.
#** You will also need to FTP all files and sub-folders within the webfiles folder (not the actual folder itself), to whatever folder on your web server you specify as the directory in the Web/FTP site part of the settings for MX.
 
== Copying Cumulus 1 files into MX folder==
 
The locale I used for Cumulus 1 is going to be the same I will use for MX (same PC!) so my copying across of my existing files was easy:
 
# First, I copied my \Cumulus\strings.ini to \CumulusMX\strings.ini. This preserves any tailoring I have done of terminology.
#* Remember, "\Cumulus\web" and "\CumulusMX\web" have different content, so don't do any copying between these.
# Next, I copied my existing Cumulus 1 alarm sounds in "\Cumulus" across to MX folder "\CumulusMX\interface\sounds" as these were referenced in my main Cumulus.ini_(Cumulus_1) file (I will edit that file next to reference the new location of these files).
#  Now, I copy my \Cumulus\Cumulus1.ini (don't worry why my file had a "1" in its name, just remember that yours probably won't) to \CumulusMX folder as "Cumulus.ini_(Cumulus_1)". I then edit the MX "Cumulus.ini_(Cumulus_1)" file:
#* In the [Alarms] section (your Cumulus.ini_(Cumulus_1) may have sections in a different order to mine) I edit all the parameter lines where the attribute ends in "File" to reflect their MX location in the sounds folder (there is no such folder in Cumulus 1).
#* I checked that I had a "[FTP site]" section (yes, mine was named correctly with second word all lowercase, but if your has [FTP Site] you will need to edit that section title to put second word entirely in lower-case)
# I now had to decide whether
## I would use the Extra web files settings page in the MX admin interface to make the changes, in the local file column, necessary to define which web templates I wanted MX to process
## Or I would make the changes myself by editing the appropriate lines in this [FTP site] section. (I decided on this option).
#* Although my web templates are stored in a folder "Templates for Cumulus to Process" outside the Cumulus 1 or Cumulus MX folder structure, I had to reference a new set of template files to cope with differences in the output parameters of MX web tags.
#* Next where I want a transfer done only at end of day, I added lines like "ExtraEOD19=1" (when you run MX it will add a ExtraEODnn for each of the 100 possible values of nn that you have not created) and changed the previous "ExtraRealtime19=1" to "ExtraRealtime19=0" (I previously used realtime as that was only way in Cumulus 1 to ensure a template file was processed so it held correct values as close to end of day as possible, but it inefficiently also made huge numbers of unwanted transfers during the day). I had 9 such files being copied far too often, so those 9 changes will cause a huge reduction in processing load! I know I could also do this later using the MX admin interface, but it makes sense to me to do it as I am working through the file.
#* I have a few files that are PHP scripts written as Cumulus templates; each PHP script has a number of PHP variables being set equal to a Cumulus web tag. You can find out about these scripts at Php webtags.
#* I also have a few Cumulus templates that, like the standard ones I don't use, generate web pages and embed a lot of Cumulus web tags. I have had to edit these templates as in some cases the web tags have date/time output format parameters.
#*  I mentioned some of my web pages are generated from my own Cumulus templates. Despite now having Cumulus 1 and Cumulus MX templates with different names, these still both generate remote web pages given the same names, so I don't need to alter any navigation between pages on my web server.
#*  In the "[NOAA]" section I had MonthFileFormat="NOAAMO"MMMyyyy".txt" on a line, I checked at Webtags#The_format_used_for_naming that 'MMM' and 'yyyy' were valid in Cumulus MX as well as in Cumulus 1, they were, so no edit needed either to that line or to "YearFileFormat="NOAAYR"yyyy".txt" line.
# In the download, there is a file "\CumulusMX\Reports\.gitignore" provided. In this same MX folder, I copied in the 200 or so report files I currently have in "\Cumulus\Reports". Remember you don't need to rename these files, it is only how that naming is specified in the settings that might need changing.
# Next I see there is a "MXdiags" folder, so I don't copy across the Cumulus 1 "diags" folder. Equally I don't change anything in the new MX "webfiles" folder, but I do copy across to my web server the "cumuluscharts.js" and "logoSmall.png" files I see there that I have not seen before.
#  So left to last is the "data" folder:
#* I have copied all files from "\Cumulus\data" to "\CumulusMX\data" (except log.xml as MX uses a different file and MX does not provide a way to read the XML file into its diary.db).
#* Some of my .ini contain date-time entries like "12/03/2019 14:50:45". I'm assured MX can read these, although it changes a date time like that to "2019-03-12T14:50:45", but I am waiting to see if that is true. I use the full stop character for all my decimal points, but if you use decimal commas, you might find you need to do some editing of your .ini files in this data folder before MX can read them.
 
== Aside on .ini files in data folder==
 
I find after running the CumulusMX engine, that it edits those .ini files it needs to, and the new versions contain date-time entries in the "2019-03-16T12:45:00" style, but despite what I worried about from reading on the forum, I found you don't need to edit beforehand these entries in log files like month.ini as Cumulus MX can read the old formats like "12/03/2019 14:50:45" as well as the new year first formats.
 
== Creating the shortcut to run MX==
 
I right clicked on the "CumulusMX.exe" entry in the top level folder and selected Send to ... desktop (create shortcut).
 
*    Ensure that your shortcut has a Start in: defined as the folder where your executable is stored. This is the most vital setting.
*    You can optionally change other shortcut properties. I selected to use different settings in the colours tab, so when I have that terminal/console window open I don't confuse it with any other command window I might open. I selected to change options in the layout tab to position the terminal/console window on my second (smaller) screen. I also selected the Start minimised option, as I don't need the window for this MX engine taking up screen space all the time.
*    I have renamed my shortcut to "MX_run" so I can recognise it as different to the folder name, as I have also created a shortcut for the folder.
*    On the same right click menu I also selected Pin to taskbar.
*    When I am happy with MX, I will copy the shortcut into C:\Users\Personal\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\ and then MX will start automatically after I (or Windows Update) reboot my PC.
 
== One-off extra installation steps==
 
#  I clicked on one of my new shortcuts. Windows Defender popped up, so I told it allow all for Cumulus MX.
#    I opened my Internet Security premium package, in the "unrecognised files" section I selected CumulusMX.exe then right clicked and selected Change File Rating to Trusted
#    In the "Firewall" section of the Internet Security package I added port 8998 as one that was permitted.
#    I viewed my hub (router) to see the IPv4 address allocated to my Cumulus MX computer (192.168.1.64), that told me that I would find the user interface by typing "http://192.168.1.64:8998/" into my browser while the MX engine command window remains open (so MX is actually running), so I typed that and I saw the user interface and navigated around it.
#    I right clicked on my desktop (you may need to right click on the windows symbol at bottom left), selected command prompt as administrator that opened a command window where I typed  <tt>netsh http add urlacl url=http://http://192.168.1.64:8998/ user=\users</tt>
 
and I got the response "URL reservation successfully added", so I know it worked. This command is apparently to allow all users to bind to port 8998 (i.e. that used for the Cumulus interface). This also means you don't have to run the engine (CumulusMX.exe) in an administrator user, nor select "Run as administrator" from right click menu on the shortcut, nor set the properties for any shortcut to run in any special way.


IMPORTANT NOTE: I don't use "localhost:8998" for two reasons, first I already have a web server on my PC at IPv4 "127.0.0.1" using "localhost" as an alternative name (and port 81, selected because something called 'Skype' that I don't use had reserved port 80 that I had expected to use), and second using the IPv4 exact "http://192.168.1.64:8998/" address as a bookmark, I can view the Cumulus Admin Interface on my mobile phone which shares bookmarks with my PC and connects to my LAN via wifi.
So when you migrate "dayfile.txt", run it through an editor designed for programmers. Many such editors (e.g. Geary, NoteTab Light, Brackets) are available.


== End of my test of MX actions==
For example "Notepad ++" is one that is popular. That editor has a "Search" menu, with a '''Replace...''' option within it. In that option, there is a "Find what" box, a "Replace with" box, and a "Regular expression" selection.


When I am happy to stop using MX, I type Control + C into that MX command window on my PC and MX closes.
Suppose your latest lines use either "." or "-" as separator, and that is what MX expects, but you have some older lines using "/" as date separator. Since you know "/" does not appear anywhere but in the dates with an older format, putting "/" in '''find what''' box and either "-" or "." (as required) in '''replace with''' box will sort you out after you hit "Replace all".  


== Testing MX while still using Cumulus 1==
It is all a bit technical, if MX expects "/", but you have "-" in some older lines. The complication comes because "-" may be used in value fields too, so you need to find a way of specifying a minus with two digits before it and two digits after it. For this correction you need to select '''Regular expression''' and then set  '''Find what''' to "^([\d]{2})-([\d]{2})-" and '''Replace with''' to "$1/$2/".  Please check this, as this was copied from a forum post by Mark Crossley and I have not verified it.


Obviously, you cannot have Cumulus 1 and Cumulus MX running at same time, accessing same weather station.
====time-stamp format issue====


If you (like I was to begin with) are just experimenting with MX you may sometimes run one flavour (say MX) and sometimes the other (Cumulus 1).
The dayfile.txt contains time-stamps following any value that represents a highest or lowest in the day.


Each time you swap, you must copy all the updated log files from the just used data folder to the data folder you are about to use when you close one favour before you start the other flavour, or you must have both executables in same top level folder to force them to share the data folder.
All such time-stamps must be expressed quoting hour and minutes, with a separator. The use of seconds is not accepted.


Please note, today.ini is a special case, the time-stamp line has a different format in Cumulus 1 (C1) and MX; while MX can read the format that C1 uses, C1 cannot understand the format that MX uses. Remember today.ini determines which stored entries in the weather station console need to be read to "catch-up" and it also holds the various figures that will inform what gets stored in dayfile.txt at the end of the day. So to have this file being read and updated correctly is vital.
The legacy Cumulus was not fussy on the character separating the minutes from the hour.


If you don't do ensure both flavours use the same log files (.txt and .ini), various derivatives (e.g. Chill Hours) will become wrong and you may have conflicting rows in dayfile.txt (because its content is generated from what that flavour saw when it was running the previous day) and generally this will be particularly evident in any weather parameter that varies a lot like the wind vector (speed and direction). It also affects what is stored for any derivatives that rely on averaging (temperature, wind run, rain rate) as these are calculated biased towards the actual times when that flavour of Cumulus was actually running, so you can have issues if you run the 2 flavours in different folders/devices as if the other does not exist.
MX will only accept colon ":" separator, all dayfile.txt time-stamps must be in "HH:mm" format.  You will need to edit your old lines if any use a different separator.


I have some batch scripts that Cumulus initiates, and a number of Cumulus templates, and in my case I had to be happy these were working before I stopped using Cumulus 1, and got MX as the flavour that auto-started on switching on my PC.
====value format issues=====


I also use output modifiers on a lot of the web tags I use in my custom web pages and it took me a long time to work out the necessary changes to get these templates correctly edited so that MX could process them and produce the web page content I wanted. I am not going to explain all the problems nor give the solutions, because you probably don't have web pages as complex as mine.
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.
2.4.8 My migration from Cumulus 1 to MX


My installation of Cumulus MX has succeeded, and as the experiment did help me find a mistake in one of my Cumulus templates where I had not defined input parameters for "Recent History", it has been useful. Initially, I am continuing to use Cumulus 1 for the moment, until I am absolutely sure MX can do everything I want.
=web server=


I believe MX will do some tasks better, but there is a lot more to learn about how to use MX. MX does lack some features that I used in Cumulus 1. I found the View Period screen in Cumulus 1, where you could look at any day, week, month, season, or year in the past extremely useful. MX does not have such functionality yet.
Some people have been slow to migrate from the legacy Cumulus to MX because any web pages designed using a [[Cumulus template file]] that works with the legacy software will not work with MX.  It is not appropriate for this page to explain how to edit your [[Customised templates]], but it can briefly cover the different approaches for default web pages.


While I was using Cumulus 1, I found with my Chas Olsen Fine Offset I had to define EWpressureoffset=x.y otherwise Cumulus 1 frequently failed to read the correct pressure. In implementing MX, I decided to try without that line in the new Cumulus.ini_(Cumulus_1) file; I have not had any problems either when I first ran MX or indeed 2 months later when it is more than a month since I last ran Cumulus 1. Consequently, if you used to have pressure reading problems, you might find you don't with MX.
From release 3.10.1, the new default web pages have a totally new look (designed by Neil Thomas), and include responsive code allowing them to look better on wide screens and on narrow screens (such as those on smart mobile phones). MX creates a number of [[:Category:JSON Files]] that are used to convey the data from your local MX installation to the web pages installed on your web server. Mark Crossley's [[SteelSeries Gauges|Steel Series]] is used for the MX gauges page. A single "use default web pages" setting sets up the settings required, see [[New Default Web Site Information]] page.


Some days after I first started trying MX, I have tried out more MX features, been happy with those, and as MX is now doing all I want I have stopped using Cumulus 1.
Steve Loft's Cumulus 1 came with a set of example template files (designed by Beth Loft) that could generate web pages to upload to your web server.  It also produced a set of images representing standard graphs that could be uploaded to your web server and shown on the default "trends.htm" page, a set of images representing wind speed and direction that could be shown on the default "gauges.htm" page these were based on'''Web Dashboard Components for FreeWX and FreeWX-Wi''' (no longer available) and mixed images generated by Cumulus with plots drawn using JavaScript routines (before "Canvas" functionality)., and a moon image that was shown on one web page.


I still use my own PHP script to update my database tables, I tried the custom SQL and it does not do all I want.
=Library software=


I have done a little editing of the user interface, partly to discover how easy it is to edit, partly to understand better how it works. For each file I have edited (HTML or CSS) I have kept copy of original and made a second copy of my edited version, so I cam easily go back to original and if I download a new release I won't lose the copies of my edited versions of files.
Any non-technical person can skip this sub-section!


You can judge my progress with trying features, because elsewhere in this Wiki I have expanded the text for those features I have tried and therefore understand.
MX uses a number of library software utilities like Highstock, jQuery, boot strap, and others, see [[MX_Basic_info#Library_software_for_your_web_server]].  Be aware that MX determines the versions of these it seeks, and they may not match the versions needed for anything on your web server that is not supplied in the MX release distribution.  A browser tries to reuse components that are already loaded, so there is a possibility of the wrong version being loaded.

Revision as of 03:09, 29 August 2021

Like other longer pages in this Wiki, the content is divided into sections, if you are interested in a particular issue, find it in the table of contents, rather than reading whole page!

Introduction

This page was inspired by this update from Cumulus 1 forum topic. That post was made in January 2020, and therefore relates to Version 3.3.0, which was the MX release that was in use at the time.

Crystal Clear info.png This page was last partially updated for the MX release available in June 2021; that is no longer latest!

Appeal to contributors: Please work out any updates needed for this page, so it is kept correct for more recent releases!


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?

The legacy Cumulus will never be updated, and as more people migrate to MX there will be fewer people to help you if the legacy cumulus software gives you a problem. MX has a major advantage it runs on more devices, and for example a Raspberry Pi computer is far cheaper to leave on all the time to run MX (knowing it will never be rebooted by Windows updates). The current developer of MX offers support, and other people are also gaining expertise, so if you have a problem you will get help.


Of course MX started with very little of the functionality that the original Cumulus offered, but over time MX has gained more and more functionality. Features in the original Cumulus have been gradually added to MX, but also MX offers a lot that is not in the original Cumulus. See Compare C1and MX page for more on this. Unfortunately, there is no list anywhere of all features in Cumulus 1. About_Cumulus does not cover all features. Nor is there a list of features still to be introduced into MX. Therefore it is hard to help you understand whether functionality changes between the flavours will suit you.

There are Cumulus users who tried MX, then have migrated back (from MX) to the legacy product; either on a temporary basis (to use a missing feature before they return to MX) or in a very few cases decided to stay with Cumulus 1 (because they prefer it). It is worth noting here that the legacy Cumulus is a stable product with very few bugs, but MX is constantly being developed and thus likely to contain bugs (these obviously vary depending on release as some are fixed and others appear). To put this in context, MX now has a huge amount of functionality and it is difficult for the developer to test all the different features.

Cumulus 1 creates a special log containing just temperature and humidity values, this is NOT available in MX.

Although from version 1.7.5 onwards the original Cumulus counts air frosts and gale days, this feature is not in MX.

The This Period screen that is a popular feature of the original Cumulus software as it tabulates data simply, is not available in MX.

Migrating from original Cumulus to beta MX

The beta builds (version 3.0.0) of MX were designed to make it easy to migrate. This section is based on Steve Loft's wording taken from the support forum with minimal alteration for its new context.

You can move between [Cumulus flavours] fairly easily, but you should really read all the guidance.

  • In particular if you use decimal commas with Cumulus 1, then you MIGHT have issues when MX tries to read existing log files.
  • [For separator characters in dates and lists] whilst Cumulus 1 only takes settings from the control panel in Windows,
    • MX running in a Windows environment, takes settings from the locale you specify in a parameter when starting MX, or the Control Panel in Windows,
    • MX running in a non-windows environment takes settings from the locale you specify in a parameter when starting MX, or the default locale in your Mono installation
    • MX [may] take some [settings from] interaction between the two [the specified locale and the default locale], and MX may struggle to read file [lines] created by Cumulus 1 if the MX locale is not precisely same as settings when that file [line was] created.

While MX was in beta, there was limited documentation about what features were included and why, there was some fault reporting and a tracking list that showed when some of those issues were fixed, also initially the documentation on how MX had implemented features it did have was very sparse. The lack of a list of features in Cumulus 1, meant it remains difficult to track which Cumulus 1 features are or are not implemented in MX. Steve Loft said parts of MX were simply machine code level copies of parts of Cumulus 1 functionality, and parts were trying to offer better functionality, but he never said what was included in these two categories.

There was a list of enhancements requested by users for Cumulus 1, but that list was deleted before work on MX started. Despite that, it does seem that some features that were on the now lost list of enhancements for Cumulus 1 that never got implemented in Cumulus 1, have been implemented in MX, although again there is no definitive documentation.

How to install MX

The basic instructions for installing MX (see MX on Linux, MX on Windows OS, or Raspberry Pi Image, as appropriate for fuller instructions):

  1. Download the MX distribution (from Software for latest version or from https://github.com/cumulusmx/CumulusMX/releases if you want an earlier release version)
  2. Unzip into the location where you are going to install MX.

'Engine' and 'Admin Interface' for MX

When you run the original Cumulus software it displays a screen (see Cumulus_Screenshots#Main_Screen, and from there you navigate to other screens to view data or change settings.

MX is different, it consists of a stand-alone 'engine' which performs the reading and logging of data, uploading to a web site etc. This 'engine' is a command-line/terminal/console application which has no user interface. It does write diagnostic information to a diagnostic log, but many people run MX on a device that has no monitor and so the terminal output (if any) is not monitored.

When you successfully start MX, the engine is running, and it continues, until it is terminated by control C (or its equivalent in a Mac environment). (You can also run MX as a service, that has different ways to start and stop, discussed in the links given in previous section).

The separate admin interface(unfortunately this is called various names in the support forum, including "user interface", "dashboard interface", and "admin interface") is provided by virtue of the engine acting as a web server. You can view the admin interface by typing the URL of the built-in web server into your browser, either on the same machine, or on a separate machine sharing the same local network.

If you install MX on Microsoft Windows, then a few extra one-off steps are needed to allow this web server functionality:

  1. Windows Defender has to be told to allow all for Cumulus MX.
  2. Typically for other security packages, select "CumulusMX.exe" then right click and select "Change File Rating to Trusted"
  3. In any "Firewall" package, add port 8998 as one that was permitted.
  4. Using "command prompt as administrator" type netsh http add urlacl url=http://http://192.168.1.64:8998/ user=\users, the response "URL reservation successfully added" means it worked. This command is apparently to allow all users to bind to port 8998 (i.e. that used for the Cumulus interface). This also means you don't have to run the engine (CumulusMX.exe) in an administrator user, nor select "Run as administrator" from right click menu on the shortcut, nor set the properties for any shortcut to run in any special way.

The default URL if the browser is on the same machine as MX is http://localhost:8998/. Newer releases of MX will tell you an IPv4 address to use, such as by typing "http://192.168.1.64:8998/".

Equally, if "localhost" is already in use for another web server (that you already run on your device), unless you can differentiate purely by port number you may need to use the correct IPv4 address as above, even on the same device.

For security reasons, the admin interface should not be accessible via the public internet.

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 quite a bit to read, taking up most of the rest of this Wiki page. The Cumulus configuration files for Cumulus 1 and for MX share the same name, but their content is very different, so these are discussed at length in subsections below.

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 is recorded in the configuration file
    • In the legacy software, this date is purely used as something to appear on one of the 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 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
    • .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, so do check carefully if that wiki page is describing a file name that must be all lower-case.

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 every file you move from Cumulus 1.

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.

With MX on a Mac, each line should end with just a Carriage Return.

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 Hypertext Pre-processor anywhere on your installation, normally that is written for "Line-feed" as line terminator and any "carriage return" in your files may mess up the content unless you code in a "trim" function to remove it. Hopefully, if you use PHP, you are technical enough to realise you may need to edit the code depending on which device it is being run on!

Configuration file

MX's Cumulus.ini has different content to the legacy 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 settings pages in MX, work differently to the 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.

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.

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.

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.

More changes were made in 3.10.0, and subsequent releases, as settings that previously had to be made directly in file were gradually moved to be advanced settings controlled in the admin interface. In addition, these releases, have added many new settings never encountered in your legacy software.

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 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. This is because many settings are only written to configuration file, not yet to internal code, and such settings are only read from configuration file when MX starts. The developer is changing the code, so that in more cases edits on the settings pages do update the settings used by the code, as well as the file, but at time of writing there is no list of which settings work like that, and which require a restart.

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 data file to start reading from, it will ignore any data files for earlier dates, it will also ignore any lines with an earlier date in the first data file. Thus if you were to migrate your Cumulus 1 configuration file into MX, you should check the StartDate=xxxxx parameter in the '[Station]' section is correct for your earliest data before you let MX read this configuration file for first time. If you need to make any edit, ensure you stick to exactly the same date format.

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, because of the importance of sticking to exactly the right date format when you edit it!

Station connections

You can skip this subsection if your weather station connects to MX either by USB or by wireless connection.

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/ttyUSB3" where the final digit will change depending on the new connection. You can search for posts on the support forum that talk about how to find out what connection is being used, depending on what hardware you are using.

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

This is another configuration file, but it is an optional one. Please remember that the Microsoft Windows Operating System is case insensitive for file names, so "Strings.ini", "STRINGS.INI", and "strings.ini" are all treated as the same file by any Cumulus software.

If you install MX on another operating system, then the file system is case sensitive, in this case MX will only recognise "strings.ini".

If you have not created a strings.ini file in your (leagacy) Cumulus top level folder, then you have no file to move to your MX installation, and you should skip the rest of this sub-section.

The contents of the 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, but as mentioned earlier there are some complications:

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 another optional set of files.

Weather Diary

As explained on weather diary page, the Cumulus 1 weather diary uses a different file to MX, and indeed takes a very different model for how to store the information.

Therefore don't copy Log.xml file into the data folder of your MX installation. You will need to manually use the admin interface Edit menu to access the new diary and add your previous entries one by one.

Please note the editing interface has been changed from release 3.10.1, but the page linked to above may not have been updated. A major change in the upgrade relates to handling of time-zones.

Please also note that the Cumulus 1 weather diary permitted multiple entries to be stored for an individual day, but the MX implementation only permits a single entry per day. Also the configuration file defines a time when the entries stop applying that may not match the rollover time for other weather measurements.

Extreme Record files

The Correcting_Extremes page explains how extreme records are stored in the Category:Ini Files discussed below, with the changes to all-time records being tracked in Alltimelog.txt.

You will find that MX creates at least one file that was not in the older Cumulus (monthlyalltimelog.txt).

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.

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:

  1. 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).
  2. 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)
  • MX releases from version 3.0.0 to 3.5.4 can read all the date/time entries in any file whether in the Cumulus 1 format or in the MX format.
  • MX will change any dates to the ISO format only when it needs to update that particular date/time.
  • Consequently, within a single file both formats will co-exist, you may see lines using Cumulus 1 format for the extremes that have existed for a while, and Cumulus MX format for any new extremes.

If you used decimal commas in your Cumulus 1 installation, you will make the migration to MX easier, by an edit of each ".ini" file to change those commas to full stops.

Equally, if you had any times not using a ":" as separator, you will make the migration to MX easier, by an edit of each ".ini" file to change those characters into colons.

MX releases at versions 3.6.x onwards

Migration from the legacy Cumulus to MX has become harder as MX has been developed for two reasons:

  1. It appears that releases at versions 3.6.x onwards have become more fussy about existing content in these files due to changes in the source code.
    • Effectively, the format of existing entries is expected to be same as any newly created entries, i.e. matching current locale settings
  2. The addition of Feels Like temperature and Canadian Humidity Index (Humidex) to the .ini files
    • Neither of these was stored by the legacy software or by earlier MX releases
    • The technique for adding this is described on Calculate Missing Values page

Despite this, most people migrating from Cumulus 1 to the newer MX releases, are doing so successfully, so it works for at least some old files.

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 logging files (both those ending in .ini and those ending in .txt, and only adding extra fields to the end.

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.

When Steve Loft designed Cumulus MX, he was able to learn from his experiences with both Cumulus 1 and Cumulus 2, so he decided to use dates to an ISO specification (ISO 8601 Data elements and interchange formats – Information interchange – Representation of dates and times), but in the local time zone of the particular user, and therefore log files are not backwards compatible.

dayfile.txt

MX (except early releases) reads the whole of this file as it starts running, so all lines must use exactly the same format.

date format issue

For MX (from release 3.5.4 onwards), the date separator specified for the locale when you run MX must be used in all lines of this file. Please see Amending_dayfile#Date_Separator_in_MX for more detail of what MX expects.

Cumulus 1 allows the date that appears in the first field of each line to use any character (except space) to separate the day of the month, from the month, and from the last two digits of the year. Consequently "29/03/88", "29-03-88", and "29.03.88" are all acceptable in the legacy software (and indeed in some early MX releases).


  • See MX_on_Windows_OS#Parameter_for_changing_Locale for how to specify locale if you are running on Microsoft Windows (by default the locale settings are taken from the standard Windows settings application or Control Panel).
  • If you are running MX in a Linux operating system, the locale parameter can be used, but the default locale is determined by the mono-complete package, and that in turn depends on your device settings.

So when you migrate "dayfile.txt", run it through an editor designed for programmers. Many such editors (e.g. Geary, NoteTab Light, Brackets) are available.

For example "Notepad ++" is one that is popular. That editor has a "Search" menu, with a Replace... option within it. In that option, there is a "Find what" box, a "Replace with" box, and a "Regular expression" selection.

Suppose your latest lines use either "." or "-" as separator, and that is what MX expects, but you have some older lines using "/" as date separator. Since you know "/" does not appear anywhere but in the dates with an older format, putting "/" in find what box and either "-" or "." (as required) in replace with box will sort you out after you hit "Replace all".

It is all a bit technical, if MX expects "/", but you have "-" in some older lines. The complication comes because "-" may be used in value fields too, so you need to find a way of specifying a minus with two digits before it and two digits after it. For this correction you need to select Regular expression and then set Find what to "^([\d]{2})-([\d]{2})-" and Replace with to "$1/$2/". Please check this, as this was copied from a forum post by Mark Crossley and I have not verified it.

time-stamp format issue

The dayfile.txt contains time-stamps following any value that represents a highest or lowest in the day.

All such time-stamps must be expressed quoting hour and minutes, with a separator. The use of seconds is not accepted.

The legacy Cumulus was not fussy on the character separating the minutes from the hour.

MX will only accept colon ":" separator, all dayfile.txt time-stamps must be in "HH:mm" format. You will need to edit your old lines if any use a different separator.

value format issues=

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

Some people have been slow to migrate from the legacy Cumulus to MX because any web pages designed using a Cumulus template file that works with the legacy software will not work with MX. It is not appropriate for this page to explain how to edit your Customised templates, but it can briefly cover the different approaches for default web pages.

From release 3.10.1, the new default web pages have a totally new look (designed by Neil Thomas), and include responsive code allowing them to look better on wide screens and on narrow screens (such as those on smart mobile phones). MX creates a number of Category:JSON Files that are used to convey the data from your local MX installation to the web pages installed on your web server. Mark Crossley's Steel Series is used for the MX gauges page. A single "use default web pages" setting sets up the settings required, see New Default Web Site Information page.

Steve Loft's Cumulus 1 came with a set of example template files (designed by Beth Loft) that could generate web pages to upload to your web server. It also produced a set of images representing standard graphs that could be uploaded to your web server and shown on the default "trends.htm" page, a set of images representing wind speed and direction that could be shown on the default "gauges.htm" page these were based onWeb Dashboard Components for FreeWX and FreeWX-Wi (no longer available) and mixed images generated by Cumulus with plots drawn using JavaScript routines (before "Canvas" functionality)., and a moon image that was shown on one web page.

Library software

Any non-technical person can skip this sub-section!

MX uses a number of library software utilities like Highstock, jQuery, boot strap, and others, see MX_Basic_info#Library_software_for_your_web_server. Be aware that MX determines the versions of these it seeks, and they may not match the versions needed for anything on your web server that is not supplied in the MX release distribution. A browser tries to reuse components that are already loaded, so there is a possibility of the wrong version being loaded.