Updating MX to new version: Difference between revisions

Please be aware that if you want to move from Cumulus 1 to MX, you should read [[Moving_from_Cumulus_1_to_MX]] article instead.

HansR on support forum is developing an installer as this is being typed, see [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=18893 this topic]. He proposes to start a new topic when his installer is ready for general use, and I hope he will update this section appropriately.

One would assume that, skipping minor releases in an update (from 3.x.y to 3.x.z, i.e. only final digit of version number changing is a minor release) would always be simple, even if several intermediate builds are skipped. Most developers would not introduce a new feature in a minor release that requires a one-off extra action for a successful upgrade. Unfortunately, some minor releases of MX have required you to do special actions.

 

One might assume that the ease of doing a major update (i.e. where middle part of version number changes) involves greater difficulty.  Most developers would only classify a new release as a major update if there was new functionality being introduced that, depending on what functionality you use, might involve a one-off extra action to prepare for upgrade to that version. It is harder to understand why some MX releases are classified as major version number change, and some as minor version number change.

 

You may be using an old version of MX that is actually several versions behind, or even still using a beta version released by Steve Loft, don't worry because this article covers upgrading however old a version you are using. You can update skipping some major updates, but as that can be more complex, there is a separate section later with advice on how to update in stages from an early build to a recent build.

If you are skipping some intermediate builds, then you will need to read each of the formal release announcements for builds after the build you currently use. You need to apply the cumulative actions recommended. Otherwise, most of the advice above for updating from immediately preceding build still applies.  The other sources of release information mentioned above may be consulted as an alternative.

*Additions to fields in log files

*Additions or removals in configuration file

*New pages in Administrative Interface

*Catering for new weather station sensors, or new ways of communicating

*Any interface functionality changes

*Additions to files being generated for web server

*Schema changes for database tables

====If you use 3.0.0 (the MX original beta) now====

====If you use 3.1.x, 3.2.y, 3.3.z, and 3.4.w releases====

As above, update to 3.5.1 by downloading it at https://github.com/cumulusmx/CumulusMX/releases/tag/b3072.

====If you use a 3.5.x release ====

My advice is to update directly to 3.7.0 or any subsequent release available at [[Software]].  This is because several 3.6.y releases have bugs in them and you want to avoid those problems (the bugs vary in severity between mistakes in calculations done by MX to particular functionality not working).

***At 3.6.0 the SQL was provided as a separate attachment to the release announcement (UpdateMYSQL-b3076.zip)

***At 3.7.0 the SQL was provided as part of the main zip (AlterSQLTables3098.sql)

Some people upgrade by just copying in the files that the release announcement says have changed, others copy in all files from the downloaded zip. The first should only be used with caution, files like '''CumulusMX.exe.config''' can change between versions, but not be mentioned in a release announcement, and the developer will have been making edits to files since the previous release, and might forget exactly which files have been edited between releases. Also you may be upgrading from an earlier version and therefore be skipping several intermediate releases. You may be able to see the dates when files were changed within the zip and therefore be able to decide for yourself if you compare those dates with the previous release you were using if you have kept the download for the version you were using.

#The popular approach recommended by many forum contributors in many different posts (including at [https://cumulus.hosiene.co.uk/viewtopic.php?p=141763#p141763 this post by Mark Crossley for example] is to rename your current install directory, then unzip the new release, letting it create a new '''CumulusMX''' folder (or whatever name you prefer and specify in unzip options).  

#Copy across '''Cumulus.ini''' and '''string.ini''' into that new directory, and then copy the contents of the '''data''' and '''Reports''' directories from your ''current install'' to the new install.   

#Check again that you copied across strings.ini, twitter.txt, Cumulus.ini, and similar files in the same folder level as CumulusMX.exe, as well as all the files in the '''data''' and '''Reports''' sub-folders. Then, provided you are happy, you can delete the old release when you want to reduce clutter on your storage discs.

#* if you have a lot of set-up files, or other custom files, (i.e. files not part of release), or

#*if you are downloading on a different device, or on a different disc to where you are running MX,

#then David [https://cumulus.hosiene.co.uk/viewtopic.php?p=140355#p140355 (see this post)] recommends this different approach. After downloading a new release unzip it on the device/disc where you down load it. Next simply copy the files (optionally only those that have newer dates because they have changed) into the existing MX directory on the device where you run MX. Then you know all your existing files are there, and you can choose to only copy in files that have been updated.

#'''The problem with this approach is that in some releases files are removed from the distribution''', yet unless you check carefully, this approach may ''leave files that are no longer required'' in your installation, which you can continue to use instead of the intended alternative. This can cause you problems if those files are then still used by you, giving you a non-standard installation that it is difficult for others to support. So do check through file by file to ensure you only have files in the distribution and files that either configure your system or are log files.

#*The updated files can be tracked by their modification date, or by seeing which are specified in the release notes (find them on [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 this forum] or in [[Cumulus_MX_formal_release_versions|Wiki here]]).

#*In general, especially if updating a major release, it is best to overwrite with all files in zip, whether they are listed as changed or not.  This ensures you have a consistent set of files.

====Example downloading on PC and installing on pi ====

#On your pc: Use Filezilla (or similar file transfer program, or it might even be a copy over network depending on way set up) to transfer zip to pi  e.g. <tt>FileZilla CumulusMXDist3089.zip to /home/pi</tt>

#On pi go to directory where zip now is <tt>cd /home/pi</tt>

# Unzip the installation over your existing installation <tt>unzip -o CumulusMXDist3089.zip</tt>

== After an update if you use the standard web template files ==

=== web folder from zip ===

The new web template files will be in your '''web''' folder and MX will process the new files and upload the web pages produced as before with no further action by you.

You do need a further action, if any files in this folder have been updated.  The updated files must be uploaded to your web site.

This may be easy to forget if you use the standard web templates, because you thought that upload was a one-off and maybe you cannot remember what you did.  

Certain third-party web-pages still use files from that folder, if one of the files they use has been updated, then ensure you have a backup of your web site before you upload the updated file, it should work, but it might not, and you might need to regress.

Let me go through the files currently in webfiles folder:

*subfolder '''images''' contains 2 pictures that have stayed same since MX launch

*subfolder '''js''' contains one file. The file '''\CumulusMX\webfiles\js\cumuluscharts.js''' has changed in a lot of releases.  The standard web page '''trends.htm''' will only work if the correct version of that file has been uploaded to your web site and placed in a sub-folder "js" of where "trends.htm" is installed.  BCJKiwi's user interface '''charts.php''' also requires the same JavaScript file, so upload the file anytime it is updated in a MX release.

**'''highstock''' - this folder is no longer needed on your web site

**'''jquery''' - this folder is needed for "trends,htm" to work, but it has not been updated since 2014. Both the files included are obsolete packages, no longer officially available, and there are no plans to replace them.

**'''steelseries''' - this folder has 3 sub-folders, and I can only think of 2 MX releases when anything was changed here, and I don't anticipate any further changes.

== Updating when files within release might overwrite your own edits ==

If you have edited any files that sit on your '''web site''', to give the look you desire, or the content you want (e.g. adding rain this month to this month page, or combining this month and this year page), see if the release notice says that file has been revised, if it has not then it is easy to keep your edited file by not copying in the replacement file from within the zip. If the release revises any file you previously edited, take a backup of your edited file, before you copy the new file into your folder. You can then use a file comparing tool to see what has changed in the release and what you changed and hopefully manage to merge to a new file that keeps any functionality change in a new release and keeps your customisation.   

If you have done major customisation to the standard website then you probably have followed the guidance and stored your new web page templates in a different directory and you use '''Extra Files''' to specify where they are, so they cannot be overwritten and the new MX will still find them.  

=== admin interface files ===

If you have done any customisation to the '''interface''' (perhaps you don't like seeing solar in the tables when you don't measure that) then again you can skip over these files when copying. Hopefully you will have copies of the files that you have customised of the ''interface folder'' so you have ability to copy them back into installation if you do overwrite with the release version.

You do have to be careful, as many releases change the interface in some way and all the various components of the interface have to work together as a coherent unit. For instance when feels like was added to MX, the api used for sending data from the MX engine to the admin interface was updated. In another release, adding a new web page, all the navigation menus were adjusted in all web pages. A HTML page may be edited to refer to a different styling page (so it and the .css file must be updated together) or to a different script (so the .HTML and the .js file must be updated together.  Many web pages are dependent on the correct pair of json files to define the options or values that appear on that web page.  So files are interdependent, and you cannot always update some but not all of the admin interface pages.  

Be prepared to go back to the standard file for whatever you customised if something it depends upon has changed, after all you must not lose any vital functionality.

On my site, my own versions of interface files have a "_" (underline character) added to the standard MX file name (before the "." and the relevant extension). This applies to both HTML pages, and JavaScript files that I have edited. I edit the menu items within my edited pages so those all go to my versions where I have a HTML customised page, leaving unchanged the menu items that can still go to a standard MX web page where I don't have my own version of the .HTML page.  This makes it easy for me to navigate between my pages, as all of them link to my other pages.  If I am on a standard MX page and want to go to one of my customised pages, I select the equivalent standard page, then edit the URL to add the underline and get easily to my page.  This naming means I can always use a standard page instead of my customised page when I need to and I never miss out on any new features.

== After update - checking for bugs in MX or mistakes in your installation ==

Start the new installation of MX and watch out for any errors - If the device you run MX on has a monitor, then look in the terminal/command window. In all cases look at the latest file in the MXdiags folder to see if any errors are reported.

Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.

You may find that virus checkers such as Windows Defender reject your new version of MX. They need to be told it is safe.

== Updating if you use the start/stop management script ==  

<pre>cd /tmp

wget https://github.com/cumulusmx/CumulusMX/ ... .zip</pre>

2. Once that download is complete, start cumulusmx.sh with option -u

<pre>/home/pi/CumulusMX/cumulusmx.sh -u</pre>

3.When asked for the zip file, enter

<pre>/tmp/CumulusMXDist</pre> and hit the TAB Button

4.Choose the zip file with the CumulusMX update and hit return.

5. Follow the on screen instructions

6. With each update component .....you can choose: [y]es, [n]o, [A]ll, [N]one, [r]ename

I would recommend select '''A''' as that will simply replace all files without further action.

CumulusMX will be restarted after update completes.

You can check if the update was successful by using option -s:

<pre> /home/pi/CumulusMX/cumulusmx.sh -s</pre>