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.

== 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>