Category:Cumulus MX: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
mNo edit summary
 
(193 intermediate revisions by 4 users not shown)
Line 1: Line 1:
This category lists all the pages that are relevant to MX, so is a good starting point.
{{TOCright}}
* There are pages in this category for all folders and files, used by MX
<big>'''If you have any suggestions for improving this article'''</big>, either edit this page yourself, or put your suggestion in the correct [https://cumulus.hosiene.co.uk/viewforum.php?f=38 Support Sub-Forum]. Thank you.
* If you contribute a new page, add it to this category by quoting '''<nowiki>[[Category:Cumulus MX]]</nowiki>''' on your new page.
* ''[[Migrating_from_Cumulus_1_to_MX|How to migrate to MX]]'' - For those still using the original Cumulus software


SOME KEY INFORMATIVE PAGES (FOR NOVICES):
= Introduction =
* [[New Default Web Site Information|MX's Default Web Site Information]]
* [[What to do when I have a problem with MX]] - read this before you seek advice in the Cumulus Support Forum
* [[Raspberry_Pi_Image|Setting up Raspberry Pi using a pre-built Image]] - install MX on a Raspberry Pi computer, (with all access to the rPi done from another computer on same network).
* [[Samplestring.ini]] - configuration samples for customisations you store in [[strings.ini]]
* [[Cumulus.ini]] - comprehensive guide to settings and configuration file


REFERENCE PAGES (FOR EVERYONE):
== What does Cumulus MX do? ==
* [[MX_on_Linux|MX on Linux]] - MX is really easy to install, and run, on any simple computer running any UNIX derivative
* [[MX_on_Windows_OS|MX on Windows Op Sys]] - you can install MX on a Windows PC, or laptop
* [[Updating MX to new version|How to upgrade to new MX release]] - comprehensive guide
* [[MX Administrative Interface|The Interface]]- all about the pages used for settings, correcting log files, and viewing your weather derivatives locally
* [[:Category:Ini Files]] for all pages that deal with the files storing highs and lows
* [[:Category:MX txt Files]] for all pages that deal with the files logging your Cumulus data
* [[Weather Diary]] for information about the diary feature
* [[Recent history]] for information about database storing minute by minute data for rolling 7 days


SPECIALIST GUIDES (NOT FOR NOVICES):
Before you read this article any further, read [[About Cumulus|the article that introduces Cumulus]] first, as that will explain what Cumulus software can do for you, then you will be linked back to this page.
* [[:Category:JSON Files]] for all pages dealing with files used to get data to your web site
* [[Webtags/Parameters]] - see this page if you want to vary how data appears on web pages
* [[Cumulus_MX_Local_API|MX application programming local interface]] - the developer explains how data is made available for local interfaces
* [[MX Basic info]] - contains details like the library functions used by MX, and how the end of day process works.
* [[Cs Code Modules]] - quick guide to the components compiled up to make the MX executable


PAGES THAT WERE CREATED FOR MX BETA:
== This article ==
These were created in a rush when there was a threat that the support forum would close, they need a willing contributor to sort them into useful pages:

* [[MX Issues]] Detailed known issues with 3.0.0 beta releases
This Wiki article was originally exactly what Steve Loft said in the [https://cumulus.hosiene.co.uk/viewforum.php?f=39 MX early builds support forum] when he first started experimenting with Cumulus MX and access was restricted to those willing to experiment with his tests.
* [[Cumulus MX FAQ]] Was intended to be quick reference answers to frequent questions

If you visit this page again, you may find more has been added since your last visit, I am adding more as I explore more of the functionality of MX; and as I learn more from posts in the forum. If you can correct anything I write, add anything I have not yet covered, or know something that I might not know, then please remember, anyone can update this article, I don't have any special access in the Wiki and any page I edit can be edited/corrected by anyone else. During a period of my time in employment I was responsible for approving documentation on a large computerisation project, and later for supplying updated information for a public faced web site, and in both cases there were house style, so I may be using a style not the same as your natural one. But as long as you use short paragraphs or bullet points, with lots of headings, then your contribution can blend in.

= Cumulus MX =

*When this article was first created, Cumulus 1 was still recommended for most users.
*It had extensive help screens built into the package, it had an installation package, and produced a main screen when it was running that summarised the weather and gave access to all the settings and editors.
*At that stage Cumulus 3 also known as MX was experimental and it had limited functionality, much less that was available in Cumulus 1.
*Consequently, at that time, most Cumulus users were using Cumulus 1, and just those wishing to take part in beta testing used MX.
*Steve Loft who wrote and developed Cumulus 1 and MX, no longer offers any support.
*The source code for Cumulus 1 is not available, and it was developed using a coding environment that is no longer available.
*Consequently, Cumulus 1 functionality can not be changed, and without knowledge of how it was written, there is no ongoing support, just the experience of those who have used it, or are still using it.
*Cumulus 1 was designed to work with weather stations that were available when it was written, the technology used by stations, and models available, have changed since then.
*The ongoing development is adding lots more functionality into MX, it can do a lot more with the the numbers it reads from weather stations, and it can be updated when weather station features change.
*Therefore, the advice to newcomers is to use Cumulus 3, normally called MX. Similarly, the advice to established Cumulus 1 users is you are now missing out on features unless to move to MX.
*Consequently, this is the Cumulus flavour that most users will select to install and run.
*However, there are no instructions built into the MX package, so it is hoped that the update of this article will help people to understand MX sufficiently to use it both more easily and to maximum capability.
*Currently, Mark Crossley who has been responsible for all recent MX releases is able to answer questions in the support forum [https://cumulus.hosiene.co.uk/viewforum.php?f=40 for recent MX releases], but this article will hopefully allow him to spend less time answering questions and more time improving MX (and more time for everything else in his life)

It would be wrong not to say here - '''MX is still not bug free, there is a lot more to correct as well as all the enhancements to cope with new weather station hardware'''

== Restrictions on who can use MX ==

MX makes extensive use of library packages like bootstrap (cascade styling), datatables (display and manipulation of tables), JQuery (JavaScript package that provides code supports for multiple browsers and other libraries to work together), high stock (for drawing charts), datepicker (a JavaScript based routine for making date selection possible using a calendar type interface as not all browsers directly support that), handlebars (templates for generating HTML), alapaca (JavaScript from Gitana Software that generates interactive HTML5 forms), Steelseries (provides the gauges used), dataTables (displaying the log files), altEditor (for editing the log files) and a few more. Most of these are open software and free for personal use, but some have restrictions on commercial use requiring a licence. Consequently, MX does have to declare it is not for use on a commercial web site.

=== Message from Steve Loft ===

Note: The graphs used in Cumulus MX are drawn using Highcharts and they are free for non-commercial use only, i.e. you may not use them on a company web site, see http://shop.highsoft.com/faq/non-commercial for clarification. '''For this reason, and others, use of Cumulus MX in a commercial environment is expressly forbidden.'''

''Please include a link to the Highstock web site (as the supplied web page does) if you use the charts under the terms of the non-commercial licence.''

== Documentation for MX ==
=== Message from Steve Loft ===
There's quite a lot to read before you start - please do read all of this page and all the references it mentions, most of it is very important.

Note that most of the Cumulus 1 documentation also applies to Cumulus MX. MX specific documentation is currently in very early stages and some settings may not be obvious. Looking at the [[FAQ|Frequently Asked Questions for Cumulus 1]], [[Cumulus MX FAQ|Frequently asked questions for MX]], and articles elsewhere in this wiki will help, as will looking at the Cumulus 1 help file, it is available on the [[Software#Resources|Software Resources page]]. If you already use Cumulus 1, the help is part of the standard installation.
If MX is your first encounter with Cumulus, you will be at a disadvantage regarding documentation of many of the features, while those who have previously been familiar with Cumulus 1 will find most aspects of MX easier to pick up.

=== Update ===

The update made to this page draws on what has been said spread over lots of posts on the support forum and attempts to make it more accessible by repeating it on this page. Consequently, you don't need to search as Steve Loft implies above any more.

In writing this update, I have drawn on my own experience of moving from Cumulus 1 to MX, and thus my knowledge of Cumulus is from over a decade of experience with this software and a detailed study to check MX could do all I used to do with Cumulus 1 and much more. Before I add items to this article I play around with MX experimenting with what works and what does not work, but I have saved you the pain of where I went wrong, just telling you what is correct. I do need to add, that I don't have a separate testing environment, and therefore I am not will to attempt anything that might muck up my collecting of weather information, plus currently I only have a PC and a simple smart phone, so my technology places restrictions on what I can do.

If this page, and those other Wiki pages it links to (e.g. [[Cumulus MX FAQ]]), do not answer all your questions then see [https://cumulus.hosiene.co.uk/viewforum.php?f=40 the support forum for current Cumulus MX] as that will let you see what other people have asked about, any posts I have not yet incorporated into this page, and there you get the opportunity to post your own query.

== What to do if you have a problem ==

The [[Cumulus MX FAQ]] page is (as I type this) being updated to answer a lot of the questions you might have.

If that does not help...

<big>If your question relates do an ongoing problem with using MX, then please follow these instructions, don't just post "Help me":</big>
#) In admin interface Settings tab, station settings, Options section, select '''debug logging'''. This adds a lot of extra information to the log designed to help answer questions when someone has a problem.
#) ''If your problem relates to uploading to your remote web server'', then in admin interface, settings tab, internet settings screen, Web/FTP settings section, about 2/3 way down, select '''FTP logging'''
#) Leave MX running for a while, hopefully long enough for several instances of your problem to reoccur
#) Stop MX
#) zip the latest file updated in '''CumulusMX/MXDiags''' folder. Add into zip, any log files that seem relevant to your question, and any other files you have modified from their content in the MX distribution if those files are relevant to your problem.
#) At this point you can optionally try restarting MX
#) Now ask your question in the correct sub-forum [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus MX Current (releases since b3043)]
#) Use the attachment tab below the posting window to upload your zip. In the post explain your problem, and quote any settings (do not disclose passwords) that might be relevant. Also state what device you are running MX on, and on what device you view the admin interface.
#) If your problem relates to uploading, some information on your web server structure can help.
#) If your problem relates to the admin interface say so.
#) If your problem relates to web pages on your own web server (not server generated for the admin interface) say so, and which web pages you are using, and (if relevant) PHP version being used.
#) Given the right information, as listed above, permits other people to answer your question easily.

If your question does not directly relate to using MX, then there are other sub-forums available at [https://cumulus.hosiene.co.uk/index.php Cumulus Support Forum] where you can post your question giving relevant supporting information, that might include a link to a web page relating to your problem.

== Comparing Cumulus 1 and MX ==

Cumulus MX aims to be as compatible with Cumulus 1 as possible with 3 exceptions:
* Like Cumulus 2, MX separates:
*# the engine (reads weather station, calculates derivatives, creates web server for user interface, and sends updates to various external web sites), and the
*# administrative (shortened to admin hereafter) interface (displays basic information, allows you to vary settings, contains editors for highs and lows and for log files).
* Like Cumulus 2, MX runs on Linux and OS X as well as (like Cumulus 1) Windows.
* Like Cumulus 2, MX learns from some of the mistakes made in early part of design of Cumulus 1, that limited further development.

Because the development environment for Cumulus 1 is no longer available, it cannot have any extra functionality added. MX uses standard language C# (pronounced "C Sharp"), an object-oriented programming language created by Microsoft for use with the .NET Framework. It also works with Mono an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
=== Features and functionality ===

Initially MX, as written by Steve Loft, [https://cumulus.hosiene.co.uk/viewtopic.php?f=27&t=13298#p104138 lacked a lot of features] that were available in Cumulus 1, but subsequent developments headed by Mark Crossley have now added the majority of the missing features. There are also many features that have been added to MX that were '''either''' on the now lost list of enhancements for Cumulus 1 that never got implemented, '''or''' are extra functionality to reflect recent changes in weather station features. All quotes below are from the release notes issued by Steve or Mark. Only significant changes to functionality are noted below (for fixes see support forum for full release announcements). There is also version change information [[Cumulus_MX_formal_release_versions|here for MX versions]].


==== Version 3.0.x ====
*build 3023 - you can now control the output format of <#tomorrowdaylength> using an entry in '''strings.ini''' like this example:
<pre>[Solar]
MoreDaylightTomorrow=Il y aura {0} minutes {1} secondes plus la lumière du jour demain
LessDaylightTomorrow=Il y aura {0} minutes {1} secondes moins la lumière du jour demain</pre>
*Build 3025 - new MySQL (6 options) and custom HTTP uploads (can invoke a PHP script) facilities
** Also introduces a second pass to read archive records in catch up '''for Davis stations only'''
**Debug logging, diagnostic data logging, and ftp logging can now be set in the UI
** Changes for reading from Fine Offset and Davis stations
**Improved console messages at start up to indicate whether station has been connected successfully
**Makes sure dayfile.txt entry is always logged to MXdiags to help in case has problems writing file
**'Stop second instance' option now implemented (there were problems with this, see later versions)
**Graph periods can now be configured

*build 3035 - archives the [[month.ini]] and [[year.ini]] file at the end of the month/year as monthYYYYMM.ini and yearYYYY.ini.
*Build 3041 - Support for FTP over SSL/TLS (FTPS) - enable in Internet Settings
*build 3046 - added [[Weather_Diary|weather diary]] database (Note the MX diary file is different to the Cumulus 1 diary file).
*build 3047 - Web token parser updated to cope with html tag characters "<>" in the format string (see [[Webtags#Using_HTML_tags_within_format_parameters_.28MX_only.29|web tag page]]).
*build 3049 - This build enables ability to upload data to Windy.com.

==== Version 3.1.1 ====
This release is mainly part of my attempts to add some of the Cumulus 1 features that are missing from CMX.
* build 3054 - Adds a Current Conditions editor and an All Time Records editor to admin interface
* Build 3056 - Fix for the All Time Records editor

==== Version 3.2.5 ====
adds editors for files that track extremes previously missing from MX
*Build 3061 - that completes all the missing record editors from Cumulus 1

==== Version 3.4.0 ====
The big change for this release is adding historic data "catch-up" for Davis WeatherLink Live devices.
*Build 3064 - fixes bug in Monthly Records editor for dry/wet periods.

==== Version 3.4.5 ====
This release continues attempts to add some of the Cumulus 1 features that are missing from CMX.
** Build 3069 - Adds Editors for: Dayfile, Monthly Logs, Extra Logs

==== Version 3.5.0 ====
adds the generation of a Moon phase image, and the ability to push data to MQTT brokers.

=== Accessing Admin Interface ===
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. 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. The separate admin interface is provided by virtue of the engine acting as a web server.

When you successfully start MX, the engine is running until it is terminated. 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/'''.

If you are using the browser on a different device on your local network to the device running MX, you cannot use '''local host'''. 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).

Equally, if "localhost" is already in use for another web server (that you already run on your device), you will 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.'''

=== Operating Systems ===
MX runs on:
* Microsoft Windows operating system (Cumulus 1 only runs on this)
**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

As mentioned in the comparison between Cumulus 1 and MX [[#Comparing_Cumulus_1_and_MX|section earlier]], Mono is the open source version of the propriety .Net. Both are sponsored by Microsoft.

=== Configuration, Log, and Web files ===
Both Cumulus 1 and MX both use the same basic files: [[Cumulus.ini]], [[dayfile.txt]], [[today.ini]], [[month.ini]], [[year.ini]], [[alltime.ini]], [[monthlyalltime.ini]], indexT.htm, todayT.htm, yesterdayT.htm, thismonthT.htm, thisyearT.htm. But there are differences in content in all these, and the web pages not mentioned there are totally different.

The configuration file Cumulus.ini has some differences between Cumulus 1 and MX, see that wiki page for more information, but essentially each flavour will ignore the parts they don't understand, and add the additional parts that they need but the other did not use.

While Cumulus MX can read the '''today.ini''' produced by Cumulus 1, you probably need to edit the date format in the date at the start of that file before Cumulus 1 can read a '''today.ini''' produced by MX. MX uses ISO format dates with year first, Cumulus 1 uses the date format defined on your PC system that might have year last. Look up in this wiki pages for the Log Files [[:Category:Log Files|index page]] or the individual file pages just referenced to see the differences between file content, and what you ''may'' need to edit to use Cumulus 1 files with MX.

Both Cumulus 1 and Cumulus MX supply a number of ''templates that are processed into web pages'', although the end produce web pages are (except for trends.htm) identical, '''the templates are not interchangeable'''. However, there are files that Cumulus 1 uses (for example it uses several image files for the trends web page and a weather diary in a XML file) that are not used by MX and also many files that MX creates (for example json files and a weather diary in a SQlite file) that were not part of Cumulus 1.

= Installing and Running Cumulus MX =

There is no automatic installer (this may change). Cumulus MX is supplied as a zipped package on a link from [[software|download page]].

When running Cumulus MX, you either have a package that runs it for you, or in your command type interface you type '''CumulusMX.exe''' or '''sudo mono CumulusMX.exe''' depending on device, (or click a shortcut). There is a second exe file in the package. <tt>ExportMySql.exe daily</tt> or '''sudo mono ExportMySql.exe daily''' depending on device will populate a newly created database table to hold daily summary values with past rows. Replace "dayfile" with "monthly" in the run instruction for this exe to update all rows in a newly created table to hold values from all the monthly log files.

You can also add parameters to the normal MX run instruction e.g. '''CumulusMX.exe -lang en-GB''' (to select the GB locale), '''CumulusMX.exe -port 8002''' (to change the port where the user interface runs), or '''CumulusMX.exe -debug''' (to have full debugging turned on as MX starts), '''CumulusMX.exe -Logging=1''' (for the Davis specific logging).



== Optional parameters to add to the instruction to run the MX engine ==

The port, locale, logging, and debug switch have just been mentioned, here are some more details for the first two.

=== Parameter for changing Port ===

When Cumulus starts, it will display the URL of the user interface. It runs on port 8998 by default; if this is not suitable for some reason you can over-ride it using the '-port' parameter on the command line, e.g. to use port 9999 instead:
<pre>sudo mono CumulusMX.exe -port 9999</pre>

=== Parameter for changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
<pre>
sudo mono CumulusMX.exe -lang en-GB
</pre>
Other local examples: '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''', '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.

Note that you ''may'' need to supply your administrator password after typing the 'sudo ...' command line. The system will prompt you for this if it is needed.

== Running Cumulus MX ==
# Make sure your weather station (and any extra sensors) is connected to the device on which you have installed Cumulus MX, before you try to run Cumulus MX.
# Start '''Cumulus MX engine''' (command to do this varies between operating systems, so see sub-heading for your device below
# Start '''Admin Interface''', it runs in a browser, by default on port 8998, see [[#User_Interface|section]] below.

If you are running MX for the first time, without a configuration file (none is included in download package), see [[Cumulus.ini#Cumulus_MX|here]] for screen shots and instructions.


'''The software currently (this is early 2020) called .NET was originally for all operating systems, but Microsoft then decided to restrict it to just Windows, mostly to encourage greater dominance by Microsoft software and hardware. Mono was then born based on .NET to work with all operating systems, Mono subsequently changed independently from .NET. More recently Microsoft launched an alternative called .NET Core that took out of .NET the parts that were Windows specific. Perhaps confusingly, in November 2020, there will be change around of names, and the multi-operating system .NET Core product will take over the .NET name. I don't pretend to understand the technical details, but the impression I get is that the new .NET in November will be similar to Mono, so apps designed for that will still work, but apps using .NET to make code designed for windows will stop working'''


=== Requirements for running on Windows ===

To run MX on Windows, you need .Net version of at least 4.5.2 installed. This is only available for Vista SP2, Windows 7 SP1, Windows 8, Windows 8.1.

For Windows 10 you need version 4.8 or later, this should already be installed by your windows update feature. The .Net download for version 4.8 should be here https://dotnet.microsoft.com/download/dotnet-framework/net48.

Cumulus MX initiates a web server, to do this it may need administrative access, consequently to avoid having to run MX as an administrator you can issue a command that allows all users to bind to port 8998 which is the web server it initiates (this is used for the Cumulus MX user interface). Note that if you plan to change the interface port by using the port parameter in your launch of MX, you should change the 8998 to whatever port you are planning on using. To enter the command, first open a command window as administrator. One way to do this is to right click the windows symbol at the start of the windows task bar. The option to choose there (on windows 10) is '''Windows PowerShell (admin)''', but an option called '''Command Prompt (Administrator)''' will also work. Once that opens a new window type:
<pre>
netsh http add urlacl url=http://*:8998/ user=\users
</pre>

You only need to do that once. After than you can initiate MX from any user, you don't need to run as administrator.

Talking about command windows, if you want to check that the port is open for listening (when MX is running, the port is used for the administrative interface) type <tt>netstat -an | findstr 8998</tt> into the command window.


After you have done this you can run CumulusMX.exe normally without Administrator rights and therefore you can create a short-cut to run MX when your PC starts (put your user name where I have put ...), the shortcut should point to T:\CumulusMX\CumulusMX.exe (where T is used here only to denote the drive on which you have installed MX as it does not need to be the same as where your operating system is):
C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\CumulusMX.exe
With this you might want to right click on that shortcut, select properties, then you can set the starting position for the command window, the colours and font it will use, and even choose to start minimised, amongst many other selections.

Look at your hub or router (this should have come with instructions on how to do this in your browser) and on one screen it should show what devices are connected to your LAN and wifi. Look for the IPv4 address (w.x.y.z) of the device you have installed MX on, for example 192.168.1.64. Then give your Computer a fixed address for MX user interface by finding the network card via Network and Sharing Centre (Control Panel), click on Change Adapter Settings, then Right click on Ethernet or WiFi Adapter, select Properties and in the window that opens right click on Internet Protocol Version 4 (TCP/IP 4), and select properties and on that pop up screen tell the computer to "use the following IP address and fill it out with a subnet mask of 255.255.255.0 and gateway address between 192.168.1.1 and 192.168.1.254 (depending on the address of your hub/router).
==== Setting up for either manual or automatic running ====

There are 3 ways on Windows to create a way to run MX
#Create a shortcut on your desktop (and/or the taskbar) for the '''CumulusMX.exe''' executable <tt>cmd.exe /C start CumulusMX C:\CumulusMX\CumulusMX.exe -debug</tt>, the "-debug" is ''optional'', it starts the logging in debugging mode so the log created in MXDiags folder has more information. There are other optional parameters all listed later.
#*In that shortcut define the path where the executable is located as the path to start in.
#* '''Remember, if you have not done the <tt>''netsh http add urlacl url=http://*:8998/ user=\users''</tt> command mentioned above, you must run as administrator.'''
#* Add any of the parameters that can be used with the executable, as listed later, such as specifying a different port for the admin interface , or starting with debugging.
#*Choose whether to start as minimised or as a command window
#*You can also choose text colour (foreground) and background colour, you can choose where the window appears (so if you have two monitors you can choose which one it appears on), and how big that window is. There is a forum post by water01 about this.
#*Now you can click the shortcut to start the engine
#OR place the shortcut as defined above in the start up folder for the user account so MX automatically starts when you connect/log in (see a later section for how to find that start up folder).
# OR declare a task in the scheduler to start MX; in the '''Actions''' tab fill in fields as follows (the other tabs should be obvious):
#**'''Action''' <tt>Start a program</tt> from drop-down
#**'''Program/script''' <tt>cmd.exe</tt> (this is standard Windows environment to run something)
#**'''Add arguments''' <tt>/C start Start_MX \CumulusMX\CumulusMX.exe -debug -port=nnnn</tt> (the "/C" means this task will close once it has started the task, the "Start_MX" is how the task will be labelled as it is running, the next argument "\CumulusMX\CumulusMX.exe" actually starts the executable and it does not need a drive prefix as that is in next box.
#**Note in this example I have included next two optional parameters that can be used after the .exe call in that same box, here '''-debug''' (only include if you want full debugging logging) and '''-port=nnnn''' where nnnn is the port to be used for admin interface (only include if want to change from default 8998),
#** all optional parameters are listed later
#**'''Start in''' <tt>\CumulusMX</tt> (include a drive specifier if necessary)

==== Each time you want to run Cumulus MX on Windows: ====

#First '''start the engine''' in one of the 3 ways from last sub-section
# Next '''start the admin interface''', it does not need to run all the time, but only when you need it (when you first use MX you will need it to access the settings where you tell MX what type of station you have and what units you want to use, and set various timing options), it normally runs on port 8998 (to vary that there is a '''-port''' parameter that is followed by required port and that port parameter has to be entered every time you start MX if you are not using the default port).

Try '''start /min C:\Cumulus\CumulusMX.exe''' to run MX as a minimised package (although in Windows you can change the properties of the shortcut you use to start minimised).

==== Stopping Cumulus MX on Windows pc ====

The recommended way is to click into the command window in which MX is running, ''hold down Control key'' and press '''C'''. It is normal for there to be a short wait, then a message "Cumulus Terminating" and then after another short wait, it will say "Cumulus Stopped" and immediately after that the command window will close.

Some people, click in the task bar and select close, or click the '''X''' button on top right of command window. Although these are not official advice, they do seem to work.

There are packages that can be programmed to send a control C to a running task, and to not continue until the task window has closed. Remember to also program in a subsequent delay in that package, to make sure the package waits for MX to close, or do a check that MX has released all the files it might need to update.

''You should not'' issue a '''TASKKILL''' instruction, as that will prevent MX correctly writing out to all the files it should update on exit. Consequently, it will not restart correctly and may actually lose settings and data.

=== Requirements for running on Linux and OS X ===

You will need to install the '''Mono-complete''' runtime (the latest version of Mono should work with all functionality of latest MX in all locales). Mark Crossley says "There shouldn't be any outstanding issues with Mono, afaik they are all resolved - except for the Moon image rotation in the southern hemisphere which does not work with Mono 6.0 thru to the latest 6.8.0, only version 5.x works correctly atm for System Drawing."
* For OS X, you can download this here - http://www.mono-project.com/download/.
* How you install on Linux depends on the flavour of Linux you are running. There are download links for Linux at the same URL, but it is often easier to use a package manager, which will download and install it automatically.
**For example, in 'Raspbian' on the Raspberry Pi, you can install mono with these commands:
<pre>
sudo apt-get update
sudo apt-get install mono-complete
</pre> or
<pre>sudo apt update && sudo apt upgrade
sudo apt install mono-complete</pre>
Make sure that you have the '''mono-complete''' package installed.

The "sudo" prefix gives the command 'root' privileges, that allows administrative commands like update and install to run.
==== To actually run MX ====

Open a terminal window, change to the Cumulus MX directory, and then type:
<pre>sudo mono CumulusMX.exe</pre>

Next start the administrative interface, basically same as described for Windows above. More information on admin interface later.

==== Other issues ====

There are lots of topics in the MX sub-forum about a multitude of issues about commands to use to install and check mono, how to stop MX and differences between different devices (including Mac) and different Linux versions. At the moment, there seems to be some uncertainty, and consequently, I have not attempted to include/summarise all the material I have found.

'''APPEAL''' - Please could any readers who have experience of running MX in a Linux or Mac environment please consider writing advice into this article. I want it to be a comprehensive accurate article.

==== Notes by ExperiMentor (in Switzerland) ====

These comprehensive notes describe how to install Cumulus MX on a Pi Zero, using a PC to do some of the work:

'''Buy equipment'''
* Raspberry Pi Zero W
** A faster Pi is NOT needed for running Cumulus. Pi Zero W has WiFi and one USB port which is all that is needed for headless running.
** Using a faster Pi might speed parts of the installation process, but are overkill for actual ‘production’ running. A faster Pi will work fine though if you have one going spare and don't mind the extra power use.
** Case if desired
* Micro SD card eg 16 GB, decent quality. Adapter if needed to put Micro SD card in PC
* OTG cable (micro USB plug to standard USB socket) to connect a USB weather station to Raspberry Pi [you may have got one free with a mobile phone or tablet] if it's a USB weather station. Not needed if you have a WiFi or ethernet weather station. An Ethernet weather station will need connected to your router, not the Pi.
* Suitable Micro USB power supply (it does not need to be a high power 2.5A version for Pi Zero W with only the weather station attached; it will be powered on 24/7, so a low power consumption ‘switched mode’ type is preferred – ie one that does not become warm when plugged in with nothing attached. You may have a suitable one from a mobile phone.
'''
Download useful PC software and install on your PC'''
These instructions are for a Windows PC. Steps would be similar on a Mac, but programs and details would differ. Should also be possible with an Android tablet.
* SD Formatter (the Windows Format facility will NOT do)
** https://www.sdcard.org/downloads/formatter_4/index.html
* balenaEtcher (for unzipping and burning images to SD cards) [Previously named 'Etcher'] <tt>https://etcher.io/</tt>
* Win32DiskImager (for backup & restore of SD card images) <tt>https://sourceforge.net/projects/win32diskimager/</tt>
* PuTTY (an SSH client for Windows) <tt>https://www.putty.org/</tt>
* FileZilla (an FTP file transfer program for Windows) <tt>https://filezilla-project.org/download.php</tt>

'''Download Raspbian Pi Operating System'''
* Save it on your PC, from https://www.raspberrypi.org/downloads/raspbian/
* "RaspBIAN Buster Lite" is probably OK, but other than small file size it offers no advantage over installing the full version of RaspBIAN Buster. These instructions are being tested using "Raspbian Buster with desktop and recommended software", the largest of all, which could allow you to do other things more easily.
* Just click on “Download Zip” (torrent might be faster if you have the ability, but not worth installing just for this)
* Do not unzip it
* These instructions have been tested with kernel version 4.14, released 18 April 2018 and with kernel version 4.14, released 13 November 2018 [March 2019] and kernel version 4.19 released 10 July 2019

'''Install Pi Operating System onto Micro SD card'''

''Format the SD card''
* Put Micro SD card in PC (use adapter if needed)
** If re-using a previous Pi SD card, click ‘Cancel’ on the warning about needing to format the card
* Run SD Card Formatter (click Yes to ‘Allow to make changes to your device’).
** Need to use this program rather than the Format tool in File Explorer, because Pi SD cards end up with a very small ‘Windows accessible’ partition and a large partition containing Linux. SD Card Formatter allows reclaim of the large partition.
* Your SD card should automatically populate in the ‘Drive’ box. In case you have another SD card in your PC, ensure the correct card is selected!
* Click ‘Format’ and check and accept the Warning messages

'''Copy the Pi Raspbian Operating System onto the card'''
* Run '''balenaEtcher''' on your PC
* Click ‘Select Image’ and choose the ‘Raspbian Buster’ operating system zip file that was downloaded earlier
* SD card should be automatically populated. In case you have another SD card in your PC, ensure the correct card is selected!
* Click ‘Flash!’. The operating system will be copied to the card. This takes about 10 minutes, followed by another 8 minutes to ‘Verify’
* Cancel any messages about needing to Format the card - they are just indicating that Etcher has installed the partition that cannot be read by Windows
* On completion, the card is ‘ejected’ from the PC. Physically remove it and then straight away reinsert it so that the content can be viewed in File Explorer
* TWO drives will now be visible for the SD card. You will likely see a warning that one of the drives needs to be formatted before it can be used. ‘Cancel’ that warning and ignore that drive.
* View the other drive, which is named ‘boot’ in File Explorer
* On the View tab, ensure the ‘File Name extensions’ is ticked
* Right click and select ‘New’, ‘Text document’. Change its name to SSH (deleting the .txt extension; you need to make an empty file called SSH not SSH.txt). Click ‘Yes’ to ‘Are you sure you want to change the extension?’
* Right click and select ‘New’, ‘Text document’. Change its name to wpa_supplicant.conf (deleting the .txt extension; you need to make a file called wpa_supplicant.conf not wpa_supplicant.conf.txt). Click ‘Yes’ to ‘Are you sure you want to change the extension?’
* Right click on this new file and select ‘Open with Notepad’ or ‘Open with …’ then select Notepad. Enter the following content exactly as below (copy and paste) then edit your country code (if needed), WiFi network’s SSID and password: NOTE: Change GB as needed to be the code for your country. The quote marks should appear in the file, that is ssid="YourNetwork" not ssid=YourNetwork . Same for psk.
<pre>ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
ssid="YourNetwork"
psk="YourNetworkPassword"
key_mgmt=WPA-PSK
}</pre>

* Not essential, but I like to keep copies of both those files for future use. They can be on the SD card with different names eg ‘SSH - Copy’ and ‘wpa_supplicant.conf - Copy’ as well as on your PC
* The function of these 2 files is to connect your Raspberry Pi to your network as soon as it boots, and allows you to connect to and control it from your PC by SSH using PuTTY. This avoids needing to connect a keyboard, mouse and monitor to the Raspberry Pi. It is particularly useful for Pi Zero W (or Pi Zero) which hasn’t got enough USB connections and no Ethernet (wired network) connection. This is called ‘Headless operation’.
* Right click on the ‘boot’ SD card in left pane of File Explorer and ‘Eject’ it safely.

'''Setting up the Raspberry Pi'''
* With nothing plugged into the Raspberry Pi, take the Micro SD card from your PC and put it in the Pi.
* In a later step, you will need to find out the Raspberry Pi’s IP address by looking at your network router’s web interface. I can’t help you with doing that. If you don’t know how to, an alternative is to connect a keyboard, mouse and monitor to the Raspberry Pi at this stage
* Plug the power supply into the Raspberry Pi. It will boot up (note flashing red and/or green LEDs depending on model).
* On your PC, log into your network router’s web interface and identify the Pi’s IP address, which will be in the form xxx.xxx.xxx.xxx, for example 192.168.1.123
** NOTE: If you will be switching from a faster “build” Raspberry Pi to a “production” Raspberry Pi Zero W, the IP address will change, so you’ll need to repeat this step later
** While in your network router for the ‘production’ Pi you will be using, set up some port forwarding that will be needed later.
** Forward port 8998 to your Pi’s IP address for TCP protocol if you want to be able to access the Cumulus web interface from the external internet (this brings potential security risk though). [Forwarding port 8002 as well was previously needed].
* Start PuTTY on your PC. In the box for ‘Host Name or IP address’, enter the Pi’s IP address from above. In the adjacent ‘Port’ box, enter 22. Connection type should be SSH. Click ‘Open’.
* A window opens. The first time you do this you will probably see a long message asking to confirm it is OK to connect to a not-previously-known device. Click ‘Yes’.
* Login to the Pi. Username is pi [lower case] and password is raspberry [lower case]
* You will see a warning that SSH is enabled but the password has not been changed, which is a security risk. We will change the password in a moment
* Type
<pre>sudo raspi-config</pre>

* Note, to copy from here (usually need to do 1 line at a time), select it then CTRL-C. To paste into the PuTTY window, right click.
* As needed, adjust the following settings:
** Change the password to something you will remember. Leaving it at raspberry is a serious security risk – exposes your whole network to hackers
** In Network Options,
**#change the name of your pi to ‘Cumulus’ or something you prefer
**# WiFi network and password have already been set by the wpa-supplicant.conf file added earlier
** In Boot Options, Desktop / CLI, select ‘Console Autologin’
** In Localisation Options,
**# change ‘Locale’ if you need something different to en_GB.UTF-8. [Changing this takes quite a while on a slow Pi]. [As of Sep/Oct 2019, there is some kind of incompatibility between RaspBIAN Buster, mono v6.0.0.314 and locales other that en_GB - so unless you NEED another locale, it would be better to leave it as en_GB. The alternative is to force load an older version of Mono, for example v5.18]
**# Change Timezone.
**# Change Keyboard Layout if needed
**# WiFi country has already been set by the wpa-supplicant.conf file added earlier
** In Interfacing options, SSH server has already been set to be enabled by the empty SSH file added earlier
** Select ‘Finish’. There is no need to reboot at this stage. But until you do, you will see messages "sudo: unable to resolve host raspberrypi", but these can be safely ignored (it's just because you renamed the Pi - will disappear after next reboot)

In the steps below, you will need to press '''y''' to agree to proceed at various times

If you have been building the Micro SD card on a fast Pi, now is the time to switch to the 'production' Pi, for which a slower Pi Zero W is more than adequate.
Shut down the Raspberry Pi safely.
<pre>sudo halt</pre>

'''Move the micro SD card to the Pi Zero W'''.
Power on the Pi Zero W. Your SSH (PuTTY) session will close out and you'll need to reconnect after the Pi has rebooted. Use username pi and the new password you chose earlier.

'''Add the ‘Mono’ package'''
* Simplification: Mono is a package which allows programs to be written cross-platform so that they will run on Linux (including Raspberry Pi), Windows and Mac OS, similar to the Windows ‘.NET Framework’.
* The previous anomaly with the USB library not working with later versions of mono, affecting Fine Offset stations and the later Oregon Scientific stations (WMR88/100/200 etc) has been fixed (''in CumulusMX build 3044 onwards'') and these and other stations should now be fine with later/current versions of mono. I am currently using a Fine Offset with mono v5.18
* Process is to install a security certificate, add the mono server to the list of software sources [sources.list] that the Pi searches, then install the mono-complete package:
<pre>sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update
sudo apt-get update && sudo apt-get upgrade
sudo apt-get install -y mono-complete
sudo apt autoremove</pre>

At the time of writing (''18 Sep 2019''), this gets Mono v6.0.0.334, which works with Buster (RaspBIAN 10). However, there have been reports of incompatabilities which require use of an older version of Mono. These may have now been fixed, or alternatively may be related to use of locales other than en_GB.UTF-8 . Please see other threads in Support Forum for discussions.
NOTE: ''29 Feb 2020'': added '''-y''' into the line '''sudo apt-get install -y mono-complete''' . This makes the install bypass the usual 'Continue Y/n?' prompt¨which was causing strange problems for some, e.g. worked if just pressed 'Enter' to accept default 'Y', but aborted installation if pressed 'Y Enter'. Bizarre.
'''
Reboot your Raspberry Pi'''
This would be a reasonable time to reboot your Pi:
<pre>sudo reboot</pre>

Your SSH (PuTTY) session will close out and you'll need to reconnect after the Pi has rebooted. Use username pi and the new password you chose earlier.
'''
Install Cumulus MX on the Raspberry Pi'''
Download it [[Software|from here]] to your PC, unzip on your PC which makes a directory named CumulusMX. Remember where that directory is located then on PC run FileZilla
# In the ‘Host’ box, enter the Raspberry Pi’s IP address eg 192.168.1.123
# In Username, enter pi
# In Password enter your pi’s password
# In Port, enter 22
# Click ‘Quickconnect’. Raspberry Pi’s directory structure appears on the right and your PC’s directory structure is on the left.
# In the LEFT window, navigate to where you unzipped the download of Cumulus MX earlier. Ensure can see the folder name ‘CumulusMX’ in the lower left window
# In the RIGHT window, ensure that the folder /home/pi is shown (see top right window; contents in bottom right window include .cache, .config etc)
# Drag the folder ‘CumulusMX’ to an empty area in the lower right window (not onto one of the existing directories). Watch progress as this copies the whole CumulusMX folder and contents to directory ~/CumulusMX on the Pi
# Close FileZilla

'''On Raspberry Pi PuTTY window:'''
<pre>sudo halt</pre>

Plug your USB weather station into the Raspberry Pi – USB cable into the OTG connector (probably via an adaptor lead) if using Raspberry Pi Zero W.
If you have an ethernet or WiFi linked weather station then you won't need to do this - I don't have one so I don't know exact details. Steve below says you need to enter the IP address during Cumulus setup, but then also adjust a disconnect period if you are also using Weatherlink software.

'''Running Cumulus'''
On PC, run PuTTY again and log in to the Pi as before (note you can save the IP address between sessions)
<pre>cd ~/CumulusMX
sudo mono CumulusMX.exe</pre>

The next thing you will want to do is access Cumulus via its '''user interface''' from your PC, so that you can update the '''settings'''. Using the IP address for your Pi, in your internet browser, enter: 192.168.y.z:8998 (where y and z are numbers you will need to find from seeing how your router connects to your Pi. You’ll first see a dashboard page, then can access the Settings menu.

To make Cumulus run each time the Pi is rebooted (and force reboot in the early hours each day)
On the Pi, type:
<pre>sudo crontab -e</pre>

On first run select the text editor you prefer (defaults to #1, nano, the easiest)
Then add the following lines at the end of the file:
<pre># Start Cumulus as background task 30s after reboot (delay to allow WiFi to startup)
@reboot (sleep 30;cd /home/pi/CumulusMX;sudo mono CumulusMX.exe) &

# Reboot each day at 0253
53 02 * * * sudo reboot</pre>

'''To stop the Pi and restart it without CumulusMX running'''
(eg you need to do that if upgrading the CumulusMX version) type the following
<pre>sudo crontab -e</pre>

'''edit to put a # at the start of the line''' "@reboot..."
Ctrl-X to save the change to crontab and reboot using
<pre>sudo reboot</pre>

When your pi restarts, CumulusMX will no longer be running. You can then do your version upgrade or other task.

To revert to normal auto-running of CumulusMX, go through the same again, but this time edit crontab to remove the # from the start of the line "@reboot...". Save changes and reboot - CumulusMX will be running.

Updating a version of CumulusMX is easily done as follows:
1. Stop CumulusMX running (it locks files while it is running)
2. Install the updated CumulusMX version into a new directory - I call mine CumulusMX3xyz (where xyz are the last 3 digits of the build number) so that I can easily see which build it is
3. copy the following from the old CumulusMX directory to the new CumulusMX3xyz directory:

- your CumulusMX/Cumulus.ini file

- your CumulusMX/data directory

- your CumulusMX/twitter.txt file (if you have personalised it)

- your CumulusMX/web directory (if you have personalised any web files)

4. Change your startup instruction to use the version in the new directory eg cd /home/pi/CumulusMX3050;sudo mono CumulusMX.exe

With that method you can easily revert back to the old version if something has gone wrong. If all is well, you can delete the old directory after a few days/weeks/months/if you need the space.

'''Updating mono version'''
*First, stop CumulusMX as above by editing crontab.
*Then remove the present version of mono:
<pre>sudo apt-get purge libmono* cli-common mono-runtime
sudo apt-get autoremove</pre>

*Then install the new version
<pre>sudo apt-get install mono-complete</pre>

*Finally re-enable auto running by editing crontab to remove the # and finally
<pre>sudo reboot</pre>

Above Instructions: Last edited by ExperiMentor on Sun 01 Mar 2020 8:17 am,

=== Notes by Steve Loft ===

''please note these notes ARE now obsolete, library routines have changed a lot since this was written in 2014''


**If you have a Raspberry Pi 2, there is a later version of Mono available, which you may find works better that the one in the standard distribution, particularly if you use decimal commas. Mono 3.2.8 (which is the default in some Linux distributions) will not work if you use commas for decimals, as in some countries.

**On Linux you will need library '''libudev.so.0''' which may not be installed by default. Installing '''package libudev0''' may resolve this. There may be issues if you are using a 64-bit version of Linux. I'm not sure what the resolution is at the moment, if this is the case.

You need to specify something like '''/dev/ttyUSB0''' for the connection for your weather station. This is set in the "station settings" and stored in the [[Cumulus.ini#station|ComportName attribute]] in Cumulus.ini configuration file.

In some builds of MX you have to run as "root", there are ways of giving "root" like permissions when running MX as another user, see forum for details until this section has been updated.

=== Library software ===

Cumulus MX uses library software for a lot of the standard functionality. The library software is largely included in the distribution zip.

==== Library software for admin interface ====

#'''Alpaca'''
#*Found on github, alpaca software is effectively a programming language extension, and you really don't need to worry about it.
#*It is used for most settings screens.
#'''Bootstrap'''
#*Also known by some as ''Twitter Bootstrap'' which gives a clue as to its origins as an internal tool for those building Twitter
#*The simplest way to think about this package is as a standard set of styling promoting easy responsive web site design.
#*To give just a few examples, it defines a standard way to represent buttons, form components, lists, navigation, and breadcrumbs.
#*Currently, MX uses very little of its functionality. Amongst, what is not implemented are colouring text according to what it represents (primary, secondary, information, warning etc.), and providing for screen readers and other accessibility aids.
#'''dataTables'''
#*When MX sends out multiple lines of a log file to view or edit, the application programming interface (api) that transfers the information from the MX engine sends it in dataTables format for display on the web page in the admin interface.
#*Thus dataTables does all the work of splitting a log file with lots of lines into pages of just 10 lines, and providing the ability to move between these pages.
#*The free version of dataTables lacks the most useful functionality that needs a subscription licence.
#'''altEditor'''
#*This is an editing tool that can read what is in dataTables, create what it calls a modal (a pop-up dialog) where rows can be added, edited or deleted individually.
#*The result of whatever is done on the modal is sent back via another api to the server (the MX engine in our case) and that then regenerates the dataTables in the state after whatever action was done.
#'''datepicker'''
#*Although modern browsers generally will generate a calendar type interface when they meet an entry filed defined as a date, this date picker software ensures all MX users see exactly the same interface for date selection. It is used for picking which standard (monthly) log or extra (monthly) log is to be viewed by selecting a month and year only.
#*It is also used for selecting individual days in the weather diary editor.
#'''editable grid'''
#*As the name perhaps suggests MX only uses this for the extra web files screens where you can make selections within a grid like interface.
#*I suspect it could enhance some other functionality in the future.
#'''handlebars'''
#*Put simply this is a simple HTML generator based on templates.
#*I have not found any file in the admin interface actually using this, but I am scared to delete it just in case it stops something working.
#'''jQuery'''
#*The admin interface uses version 1.9.1 of this javaSript based library. At the time of typing this, the current jQuery is version 3.5.1.
#*Of all the old versions of jQuery, only one version, 1.9.1, has a serious error in its code, because it tries to load another script that does not match, and therefore the authors of jQuery strongly advise all 1.9.1 users to move to a later version.
#*Unfortunately, there are interdependencies between all the library code used by MX, so you cannot simply update this component.
#'''SteelSeies'''
#*MX uses a hacked version of the [[SteelSeries Gauges|steel series]] library described elsewhere for all the gauges (see dashboard and gauges tabs) in MX.
#'''x-editable'''
#*Put simply, this allows in-place editing of web pages using bootstrap.
#*In MX it is used for the record editing screens where you adjust the extreme values.

== Operating a web site with uploads from MX engine ==

*If you want to operate the 'standard' web site, then just the same as with Cumulus 1, you will need to upload the ''contents'' of the '''webfiles''' folder from the zip file (don't upload the containing '''webfiles''' folder itself).
**Note that the MX web files are not the same as the ones for Cumulus 1, so make sure you upload the MX files if moving from Cumulus 1 to MX.
**The standard gauges are now the SteelSeries gauges. The default versions do not display a graph when you hover over a gauge as happened when you added the stand-alone Steel Series gauges to Cumulus 1.
**The trends web page in Cumulus 1 relied on that software generating graphs as images. In MX, the software generates files with time and value pairs, these are stored in json format, the trends page then uses a library package (Highstocks) to draw graphs from those data pairs.
*Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*#MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*#MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed by MX that initialise script variables with values obtained from web tags and MX can upload the resulting script files at any of those intervals. You then have a set of web pages using a combination of HTML and script content that bring in the script with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

== Completely new MX installation ==

Create a new directory (recommended name CumulusMX) and unzip the contents of the download package into it. See notes above for extras required in various operating systems.

The package contains everything else you need to read from your weather station (if it is a supported model), to load up the user interface (for settings and some simple web pages to see on a device connected to your home network). You might want to read topics on the MX support forum to discover about other people's experiences.

=== The provided web pages ===

Setting up a web site is covered in [[Website_setup|this wiki page]] and the pages linked from there. I won't repeat that, but will try to explain below the MX context of the various files involved. MX will produce web pages locally even if you don't have a remote web site to display them on. You can view the web pages created in the web folder using a browser.

Cumulus MX provides a set of web templates, images, and json files, in '''\CumulusMX\web'''. The first of these are called templates (and have a 'T' at the end of the file name before the extension) because they include both text and web tags. MX will '''process''' these templates as it creates a web page (file name without a "T" in same web folder), during that processing, any text in the template is copied into new file without change, any web tags found in the template are parsed and the correct value is placed in that position in the output file. If you have a web server, then MX can process these files and upload them for you (by default using File Transfer Process) providing you specify the host, port, protocol, directory, username, and password, for the upload process to use. If you don't understand any of these terms, then this is not the place for explaining them, but generally if your web space is supplied by a provider, they will be able to tell you most of these settings, and you will choose the directory name. If you have set up a web server yourself, then you should know the required settings.

The web templates included are based on designs by Beth Loft used for Cumulus 1. Remember, Steve Loft (who wrote the original Cumulus software) said "''They exist because they're our web pages, and they're really only included with Cumulus as examples of how the web tags work. It never occurred to me that most people would simply use the supplied examples instead of creating their own pages!''"

The templates are written in fairly simple Hyper-Text Mark-up Language, designed to help people see how to write their own web templates. Here is a list of web templates provided:
*indexT .htm
*todayT.htm
*yesterdayT.htm
*thismonth.htm
*thisyear.htm
*recordT.htm
*monthlyrecordt.htm
*gaugesT.htm
*trendsT.htm

All these templates (except gaugesT.htm and trendsT.htm) include a table for showing values and styling that gives a graded background colour. The tables include a navigation row with links to the other pages in the set. '''That navigation line fixes the width of the table''', and you will realise it was designed in the days when all monitors were a standard shape. Therefore the standard web pages as provided cannot adapt to the range of devices we use for viewing web pages nowadays. There are a selection of alternative web page sets available [[:Category:User_Contributions#web_template_complete_set_replacements|on the User_Contributions page]], and some of these are responsive and adapt to the width of the device they are being viewed on.

The gaugesT.htm is a template similar to [[SteelSeries Gauges]] although the latter is designed to work with a range of software and the former is specific to MX. '''As supplied in MX if you mouse over the provided gauges appearing on your web site you will see a box with figures, not a graph as is seen with the general steel series gauges''', but there are some other differences such as how the figures are supplied for the displays. The remaining template '''trendsT.htm''', creates a structure that can display graphs. The data for all the graphs that can be displayed is contained in the various '''json''' files in '''\CumulusMX\web''', these files are also processed by Cumulus so latest values are added, and then uploaded so the web page produced by this template can use them.

The image that is provided in '''\CumulusMX\web''' is ''MoonBaseImage.png'', MX can be set to use that to generate (on MX start-up and on the hour) "moon.png" which it then can FTP to your web (also on the hour).


==== To set up your web server for the first time ====

When you first want to use Cumulus web pages on your web server, you need a number of static (unchanging) files to be put onto your web server. The web pages that MX uploads for you reference that static files and will not look right without them. The files that only have to be uploaded once are found in '''\CumulusMX\webfiles''' and its sub-folders. You don't create a folder called webfiles on your web server, but you put the files and sub-folders into position relative to where MX will upload the htm files.

To do this, you will must invoke a FTP process outside of Cumulus, MX does not include any functionality to do this one-off upload for you. The filezilla client is a popular choice as it has probably the most friendly graphical user interface, although other software to do this is also available. You may prefer a tool that lets you do the uploads from a command line without requiring working with a graphical interface.

#The static files to be uploaded include the standard styling file '''\CumulusMX\webfiles\weatherstyle.css''' which you place in the directory specified for the uploads.
#Next you have three sub-folders, each of those sub-folders need to be replicated '''within''' the directory specified for the uploads.
#*For example '''\CumulusMX\webfiles\images\picture.jpg''' will be stored in a "images" sub-directory of the upload directory and is used as the background image for web pages.
#**There is nothing to stop you creating your own "picture.jpg" (instead of uploading the supplied one) and then Cumulus web pages will use that for the background image on each page.
#*Similarly '''\CumulusMX\webfiles\js\cumuluscharts.js''' needs to be stored in a "js" sub-directory of your upload directory (this is the script that allows you to change the chart shown on the trends page and uses the appropriate json file to populate it with data).
# The "lib" sub-folder contains further levels of sub-folders all to be replicated on your web site.
# The '''trends.htm''' web page also loads some library software from an internet Content Delivery Network (cdn) to invoke the JavaScript based Highstocks library.

== Changing from Cumulus 1 to MX ==

Remember, that depending on the operating system, MX may require you to install extra components, such as Mono, not included in distribution, see above for details.

=== Files to copy from Cumulus 1 into where you are installing MX ===

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", plus any other tailoring set-up files, batch processes etc. you might use.

You may be installing MX on a different device to the Windows PC that Cumulus 1 ran on, in that case follow first alternative below.

If you are installing MX on a PC that has been running Cumulus 1, then there are actually 2 alternatives to choose between:
#Just create a new directory (recommended name CumulusMX) and unzip the contents into it. Then copy over your existing data files and your [[Cumulus.ini]] file, and any other configuration files that you may have created (e.g. '''[[strings.ini]]''', twitter.txt etc). In this case you will need to edit that copied across "Cumulus.ini" so any lines that referenced the old folder are changed to reference the new folder, and you may need to edit a few other items either now, or via the settings functionality in MX user interface. 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).
# Alternatively, to run Cumulus MX with your existing Cumulus data, take a back up copy of your existing Cumulus directory, and then unzip Cumulus MX into the original Cumulus folder. This saves you from copying Cumulus 1 files, and removes the need to edit any reference to folders. However, using same folder stops you going back easily to Cumulus 1 if you have an issue, because MX changes the date formats in some files, so that Cumulus 1 can no longer understand them.

==== Editing files ====
#If your "Cumulus.ini" was actually called "cumulus.ini" you should rename it to start with a capital letter. There are some differences in how the contents of this file are used in the 2 flavours, one to remember now is to check the '''"StartDate="''' line in the [[Cumulus.ini#Section:_Station|'[Station]']] section is correct for your earliest data before you let MX read this configuration file for first time, as MX uses that to find the first log file to start reading from, it will ignore any log files for earlier dates; whilst Cumulus 1 always looks at all log files it finds in the data folder. There are several other differences in settings stored in "Cumulus.ini", but you can address those later through the MX settings screens.
#See individual log file pages already referenced (access from [[:Category:Log Files|Log Files index page]]) where there is more information for how to edit your '''.ini''' files to work with MX.

=== Station connections ===

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 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 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'''.

===web pages ===

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. Cumulus 1 uploads a number of images, these include a couple of images that combined show the moon phase, and a number of graphs (used on Cumulus 1 trends page). Cumulus MX does not upload any images (prior to Release 3.5.0, from then on it uploads a moon phase image), instead it uploads a series of '''.json''' files that hold time and value pairs that can be used to draw graphs. 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.

== What I did to Install MX ==
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. 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. 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 example from version 3.5.0 the obsolete Highstocks I mention below is no longer included in the MX package, instead MX uses the online latest version.
=== Download and unzip ===
#I downloaded the '''CumulusMXDist3069''' zip from [[Software#Current_Release|the Current Release section]] on the downloads page. N.B. 3069 is no longer latest distribution, but the same link will always give you latest available.
#I unzipped the contents (on my Windows PC) into a partition I use just for software downloads. You don't have to have somewhere separate to the installation, but it is useful if you want to download on a separate device to the device where you will install your MX, or if you do any customisation of particular files and wish to keep copies of originals.
#I used a package that '''verifies the files it copies''' to duplicate the folder '''CumuluxMX''' within the zip onto the drive where I wanted to run Cumulus MX.
#I am not intending to use the web pages that come with MX, so I selected to exclude some download files: the ones from the "'''\CumulusMX\webfiles\*.*'''" folder, and its sub-folders in the download.
#* If you intend to use these 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 and sub-folders 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 should be fairly easy:
#First, I copied my '''\Cumulus\strings.ini''' to '''\CumulusMX\strings.ini'''. This preserves any tailoring I have done of terminology.
#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 file.
# I copy '''\Cumulus\Cumulus1.ini''' to ''\CumulusMX'' folder as "Cumulus.ini". I then edit the MX "Cumulus.ini" file:
#* In the '''[Alarms]''' section (your Cumulus.ini 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).
#*In the "'''[FTP site]'''" section (yes, mine was named correctly with second word all lowercase), I had a number of edits to make:
#*# I change any references to any web pages within "Cumulus" folder to say within "CumulusMX" folder. The approach I am taking is to continue to use my customised web pages, but I am editing the template files as required to cope with differences in the output parameters of [[Webtags#Output_.28format_modifier.29_parameters_for_times_and_dates|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 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.
#*# 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.
#*In some cases the web tags have date/time output format parameters.
#*Ages ago when Steve Loft first released the MX beta, I edited [[Webtags#List_of_allowed_modifiers|this table]] for Cumulus 1. Consequently, where Cumulus 1 allowed lower case or upper case for modifiers, I had changed to the case that suited MX for my Cumulus 1 templates. For example I had edited any "mm" representing a month into "MM", any "mmm" into "MMM" and any "mmmm" into "MMMM". This was in line with what I recommended in that wiki page. That left "nn" for minutes in Cumulus 1 where I could only change it to a MX equivalent "mm" in those cases where Cumulus 1 would have not taken it as month, I was too lazy to check every individual cases (I prefer to use global edits across all my files).
#*Now I had to do lots more editing of these web tags. I created a new version of each PHP script that used "nn", changed it in each new script to "mm" and changed each reference in the MX '''Cumulus.ini''' to the old files to refer to the new files. While in Cumulus 1 you can use tags like 'H' and 'M' on their own, in MX a single modifier on its own often means something different to when that modifier appears with other modifiers. Consequently, I edited any "h" or "H" on its own into "%h", any "hh" into "%H". Next all my "am/pm" references had to be changed to "tt". There were other changes I had to make and there was quite a lot of work here, despite being able to use the Search ... Replace option in Notepad++. As a result I have done some edits to [[Webtags#List_of_allowed_modifiers|this table]] hopefully making life simpler for the next person faced with this.
#* 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 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#List_of_allowed_modifiers|List of allowed date/time modifiers]] 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.
#The file "\CumulusMX\Reports\.gitignore" provided in the mX package at download, is joined in the '''\CumulusMX\Reports''' folder by copying in the 200 or so report files I currently have in "\Cumulus\Reports". These are another "Cumulus.ini" (''I am certain this is not used'', but I am playing safe by coping it in) and the existing monthly and annual NOAA reports. I don't need to change those file names as I will continue to use the same format (see change to main Cumulus.ini mentioned above).
#Obviously "\Cumulus\web" and "\CumulusMX\web" have different content, so there are not any Cumulus 1 files to copy across to MX (not that I am using the standard web files).
# 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 will see what edits I need to make later. 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.

=== Almost "Ready to run" ===
# 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 picked up from reading on the forum, you '''don't''' need to edit beforehand these entries in log files like '''month.ini''' as Cumulus MX can read the old ones.
# I right clicked on the "CumulusMX.exe" entry in the top level folder and selected '''Send to ... desktop (create shortcut) '''. 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 can 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].
# I clicked on one of my new shortcuts. '''Windows Defender''' popped up, so I told it '''allow all''' for Cumulus MX. For the shortcut in the "Startup" folder, I righ-clicked and set up on the layout tab the necessary parameters to place the window that opened on the smaller of the 2 monitors I have connected to my PC, so when it is not minimised (another setting on the shortcut tab) it does not interfere with whatever I am doing on my larger main monitor.
# 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''' (I will need to repeat this every time a new version is installed) and 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
netsh http add urlacl url=http://http://192.168.1.64:8998/ user=\users
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.

When I am happy to stop using MX, I type '''Control + C''' into that MX command window on my PC and MX closes.

Obviously, you cannot have Cumulus 1 and Cumulus MX running at same time, accessing same weather station. 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). 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. 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.

If you don't do either of those alternatives, 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 wind vector. 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.

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

=== Success ===
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. I am continuing to use Cumulus 1 for the moment, until I am absolutely sure MX can do everything I want. I believe it will do some tasks better, but there is a lot more to learn about how to use it. While I was using Cumulus 1, I found with my Chas Olsen Fine Offset I had to define [[Cumulus.ini#Introduced_for_problems_with_Fine_Offset_family:|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 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.

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. 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. 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. You can judge my progress with trying features, because I have expanded the text for those features in this article.

=== ASIDE ===

You don't need to read this, '''it is not part of the migration from Cumulus 1 (C1) to MX for those using standard C1'''. However, this is a bit of a warning if you already use some of the library packages that MX uses because your web site is not based on standard C1 web pages.

The MX package at version 3.4.5 that I downloaded contained some very obsolete copies of some external packages:
#The latest MX package does NOT include Highstock in the distribution, so MX will automatically use the latest version, and you can miss out this first updating step I had to do.
#*However, the MX 3.4.5 (this was latest at time I wrote these notes) package I downloaded contained obsolete vintage version 2.1.4 (2015-03-10) of Highstocks and Highcharts within both the interface folder "'''\CumulusMX\interface\lib\highstock'''" and the webfiles folder '''T:\CumulusMX\webfiles\lib\highstock'''. I am already using version 8.04 released 10 March 2020 on my web server because I have additional charts on my web pages, and I was worried this clash of versions might cause a problem.
#**I created a new folder '''obsolete''', I moved the various highstock and highchart files from existing folder "\CumulusMX\interface\lib\highstock\js", and the folders "modules" and "themes" that were in the existing folder into my new folder.
#**I had downloaded the 8.04 versions from [https://www.highcharts.com/blog/download/ the Highstock link] and saved that on my partition I just use for software downloads. So I copied the files and folders from that download to "\CumulusMX\interface\lib\highstock\js" to replace the ones I moved out. So now (in March 2020) my admin interface is also using Highstock version 8.04 released 10 March 2020 to match the version I use with my own web pages on my web server.
#The MX package also contains jQuery, again within both the interface folder "'''\CumulusMX\interface\lib\jquery'''" and the webfiles folder '''T:\CumulusMX\webfiles\lib\jquery'''. I was using version 3.5.0 on my web server, it is used by several of my existing web pages and I was worried a problem might result from the MX package including an old jQuery version 1.9.1, that is 2014 vintage and very obsolete.
#* As the admin '''interface''' is an integrated set of files, I had no guarantee that no guarantee that the MX admin interface (the screens showing settings and the screens showing weather information) will work fully with latest jQuery version so I decided '''I would not update the admin interface'''.
#*I am not ''using MX web pages'', so I can't tell you if they do work with a more modern jQuery, anyway I did not worry about updating folder '''T:\CumulusMX\webfiles\lib\jquery'''.
#*If you need the latest jQuery version you can download from '''https://jquery.com/download/'''. You will find it is called '''jquery-3.5.0.min.js''' (when you read this, it might be an even later version). If you download that, you need to rename that new jQuery to "jquery-latest.min.js" to match the name that MX uses. It is easier to edit the name of the file that you download, than to try to work out which MX files use jQuery and edit the name in all those each time there is a new jQuery release.
#**With my own web pages, the only ones that use jQuery are those generated from Cumulus templates using web tags, and I include "jQuery" in the name of all those templates to remind me which files to edit (and I use a batch editor that edits all the files with one instruction) when I want them to use a new jQuery version.
#The MX package also included "alpaca" old version 1.1.3 which predates 29 July 2014 in "\CumulusMX\interface\lib\alpaca", looking at ['''http://www.alpacajs.org''' is the alpaca home page] the latest version is 1.5.27 released on 14 May 2019, again there is no guarantee that the MX user interface will work fully with these new versions, so I stayed with what MX provides.

= Updating to a new MX release =

== Knowing when a new release is available ==

=== Using forum notifications ===

As new releases are announced in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic, you can use the spanner tool to '''subscribe''' to this topic to receive notifications of a new post announcing a new release (or any other release-related announcement).

=== MX installations will output message ===

If ...
#...you have a monitor to see the output from the Cumulus MX engine (Windows call this a console window, for Unix-based implementations this is the output window when using terminal), AND
#...your device running MX is connected to internet, AND
#...your MONO (if not Windows) is not obsolete (SSL certificate out of date), AND
#...you restart MX
... then you will see a prompt when a new version is available.

=== MXDiags ===

In addition ...
#...if you can view the MXdiags file for the current session of MX, AND
#... that is running with connection to the internet, AND
#...you restart MX
... if a new version of MX is available, the MXDiags file will say so (the message is not easy to spot as there is a lot output before it, but here is an example):
<pre>
2020-05-27 04:18:48.326 Calculating sunrise and sunset times
2020-05-27 04:18:48.326 Sunrise: 04:58:11
2020-05-27 04:18:48.326 Sunset : 21:19:54
2020-05-27 04:18:48.326 Tomorrow sunrise: 04:57:08
2020-05-27 04:18:48.326 Tomorrow sunset : 21:21:11
2020-05-27 04:18:48.388 You are not running the latest version of CumulusMX, build 3080 is available.
2020-05-27 04:18:48.763 Station type:</pre>

There is no message in either place above ...
*... if you are using latest version, OR
* ... if you are not connected to the internet, OR
*... if you do not restart MX!

=== Start/Stop script ===

When the '''Status''' option of this script is used, when a new release of MX is available, it will output a message.


== What to read before updating ==

*If your update is from the immediately previous build, then just check the release announcement in[https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic, or the précis style entry at [[Cumulus_MX_formal_release_versions]] in this wiki (if that is up to date) for which files have been affected.
**The actual release announcement will be more informative telling you if the upgrade requires one-off actions (like changing the schema if you use a database, or editing your web pages to take advantage of new web tags).
**The release announcement may sometimes include scripts to download and run to perform one-off actions.
*If your update is skipping some intermediate versions, then check the corresponding release announcements or Wiki entries for every version since the one you have been using before planning your upgrade.
**Again there may be one-off actions required at particular in-between versions.

== Back-ups ==

It is always best to take a backup of your existing MX installation before you do an update, this allows you to regress back to the earlier version if either you mess up installing the new version, or the new version has a issue that prevents it working with the versions of other software (like MONO) that your installation uses.

== The two approaches ==

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. Don't forget to copy any other set-up files across too. The advantage (as Mark says) is that you ensure you do use all the files in the new release, and don't miss out any he may have forgotten to mention in his release announcement. Another advantage (as PaulMy says [https://cumulus.hosiene.co.uk/viewtopic.php?p=140262#p140262 here for example]) is that you retain your old set-up intact and can easily restore it should you have a problem with new release.
#However,
#** 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 as mentioned you can choose to only copy in the minimum number of files as 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]]).

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

If you have edited any files, 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.

This includes any standard web pages you might have edited 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). 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 the new MX will still find them.

If you have done any customisation to the '''interface''' then if you have followed the guidance in this article 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 - but be careful with this one, as many releases change the interface in some way and the various components of the interface have to work together as a coherent unit. 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.

== After update ==

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.

Finally, don't delete your old installation for a week or so as you may notice something from the older version that you haven't copied across! 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.

== Updating if you use a virus Checker ==
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 ==

1. look on [[Software|Software download page]], find the link to latest version, and fill out the '...' below appropriately as you run these 2 commands on your device where you do downloads:
<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>

= Administrative Interface =

#Type the URL which is displayed (when MX starts running) into your browser (replace the * with the IP address, or use 'localhost') and the '''admin interface''' should appear. You will be viewing your admin interface on the same network as the the MX engine is using, so what you type might be something like <tt>http://192.168.1.x:y/</tt> and you may need to look at your hub or router to see what to use for x and y as they represent the device where MX is running.
#*If this is a 'clean' installation, ''i.e. you don't have an existing [[Cumulus.ini]] file defining station type and units to be used'', the first thing you will need to do is to go to the '''settings''' screen.
#When that page is displayed it always shows the options to set the station type and units.
#Before you leave this page, you can make any other configuration settings by picking a section and clicking it to show the selections within that section.
#Now go to bottom of this page and click the 'Save' button.

Having set the station type, and other settings, you will need stop Cumulus MX and start it again.

== The API interface ==

The current data is transferred from the MX engine to the Admin interface as a JSON string accessed via a Application Program Interface (api). To see the full content type into your browser the same IP reference as for the admin interface and add a few more items i.e. something like <tt>http://192.168.1.x:y/api/data/currentdata</tt> and you may need to look at your hub or router to see what to use for x and y as they represent the device where MX is running.

Many browsers (e.g Firefox) allow you to specify the type of a file you want to view. So if you specify json as the type this will make the browser show it in a long but fairly readable format. This api is how the current data (now.html) page in the admin interface gets its data. Each table cell contains a span element and each span element is given an id attribute whose value matches one of the items in the json stream coming via the api.

This same api can be used to get weather data into another device, although you may prefer to use MQTT instead as that is more easily customised to just share the few weather values you might want.

== The MQTT interface ==

Until this section is written, please see [[Cumulus.ini#MQTT]] for the information you can put into settings, and where to enter it.

== The Data Log Viewing and Editing interface ==
[[File:Data Logs Options.png|right|800px]]
The '''Data logs''' tab in the admin interface, as shown in image to right (which is taken from an experimental version, the released version of mX has different headings), gives access to screens that can display the contents of [[Monthly log files|Detailed log files for any month]] with menu item '''Data logs''' (yes same name as tab), the [[Extra Sensor Files|Extra Sensor Log Files]] with menu item '''Extra Data Logs''', and the [[Dayfile.txt|daily summary log (dayfile.txt)]] with menu item '''Dayfile'''.

All screens use the datatables library to access the application programme interface (api) generated by MX for representing the selected log file, and to produce the formatted output that you see. In the api the schema used is based on that defined in the version of MX you are running, with nulls added for any fields in the current schema, but not in the schema when the line being read was created.

Version 3.6.1 changes the wording on the pop up dialogs for editing a single row; Earlier versions used "Close", "Edit" buttons. Later versions use the more meaningful "Cancel" and "Save" buttons respectively for '''Edit''' on main screen. All versions use "Cancel" and "Delete" respectively on the pop up dialog when selecting "Delete" on main screen. The new terminology takes precedence in the following sub-sections.

<big>WARNING: In any of the log files, if you choose to Edit a row, when you then save it, if that row that was originally shorter because it was created by an earlier version, MX will have generated nulls for the extra fields, thus datatables will store the row with the length defined in the MX version you are now using, so extra commas (and any values you set) will be added to end of just any line that has been edited, leaving other lines in the log file unchanged in length.</big>

=== Data logs ===

This screen can be used to display any monthly log file in the '''CumulusMX/data''' folder. None are displayed until you select date (defaults to current month) and click '''Load'''. The selector will find any file in the folder, including those those for dates before when MX believes is earliest date (StartDate= xxxx, in Cumulus.ini). The only proviso is that the file naming must obey that currently defined in the current locale supplied to MONO (or defined in Control Panel for Windows operating system). Obviously, if you choose to load the default (the current) log file, what you see loaded from the api mentioned above is how the file was at time of creating that api, more lines may be appended to the file while the screen is open, but as far as I can tell the contents shown are not refreshed, so you can only edit those available at time of load.

Highlight any one row and the ''datatables'' software used here will offer '''Edit''' and '''Delete''' buttons that operate on that row. The Edit button pops up a dialog showing all fields available in the version of MX you are using. If the log file has fewer fields because it was created by an earlier version of Cumulus, the excess fields will not show any value. Make any edits, click the '''Save''' (prior to MX version 3.6.1, it was "Edit") button and hopefully you will see a ''Success'' message.

(Aside: From version 3.6.1, the <tt>\CumulusMX\interface\js\datalogs.js</tt> uses a
<pre>language: {
altEditor: {
modalClose: 'Cancel',
edit: {
title: 'Edit record',
button: 'Save'
}
}
},</pre> construct to rename button names in <tt>CumulusMX\interface\lib\datatableseditor\dataTables.altEditor.free.js</tt>, although I would advise against editing any admin interface files, those who want to tinker with the admin interface could use this approach to get button names in their own language, the messages for "success" and "error" are set to use that wording in the functions later in the first script).

=== Extra Data Logs ===

As I am typing this, a new release (3.6.4) has just been announced with a new version of this screen, so I'm not going to talk about this moving target.

=== Dayfile ===

For displaying and editing the dayfile.txt file. Like the others, highlight any one row and the ''datatables'' software used here will offer '''Edit''' and '''Delete''' buttons that operate on that row.

Please don't start to use this option either when MX has only just started, or within 10 minutes either side of your rollover time, because in both cases MX needs exclusive access to the file. Since the file being edited is provided via an api (see above) I don't believe its use by the datatables software ''could'' cause a conflict, but let us play safe.

Note, when you click the Edit (table) button, it pops up a window that shows all the fields (in the highlighted row) vertically with cancel (previously "close") and save (previously "edit" or "edit row") buttons visible when you scroll down. It does not show any values from any other files. MX does not provide within this screen any way to read the monthly data logs for a particular day and recalculate the value to place in any field of this dayfile log. In the future it is possible that there might be a separate executable, outside the admin interface that could do this (similar to separate executable mentioned for MySQL functionality, later on this page), but at the time of writing that is no more than a possible very low priority project with the developer.

== Changing Settings ==
All settings are stored in [[Cumulus.ini]], so when you stop and restart MX, it can continue without you entering settings again.

Adjusting the majority of them is best done using the MX "admin interface" screens, you will see that '''Settings''' is the penultimate option in the navigation bar, and it has a drop down for the various settings screens that are now described. [[File:Settings Menu.png|right]]
For most screens a HTML form element is used, there is a '''Save''' button to send the contents of that form for processing, and that must be clicked (and an acknowledgement displayed that the form processing has completed) before the edited settings are accepted. To make it easy to change settings, such setting screens uses tick boxes, radio buttons, and drop down selection boxes, so the choices available are clearly laid out. These form based MX settings screens do some validation, and if you make an error the contents change to a red colour (red text and red boxes), that means invalid data is present which must be corrected before the form can be sent by pressing '''Save''' button. One or more items on the page will have an error message added by the form processing in those validation fail cases.

If you attempt to set these settings by directly editing the file where they are stored, there is a danger of either making a typo or of choosing an illegal value for a particular attribute.

There are however some settings that can not be found in any of the setting screens, for these you need to edit the [[Cumulus.ini]] file directly, and the referenced Wiki page gives details of which settings can only be adjusted by adding parameters in the file, and tells you what values are accepted for those attributes, and also explains some of the differences in the settings available between Cumulus 1 and MX.
'''Note that if you change settings''', that '''some''' settings do not take effect while MX is running, while other settings do take effect instantly (I have not found a definitive list anywhere) - anyway, you ''may'' need to restart Cumulus MX to get the new setting picked up. When you exit MX, it saves the settings in [[Cumulus.ini]], and when you restart it it uses the settings it reads from that file.


(Aside: The "Success" message (with all possible alternatives) is defined in <tt>CumulusMX\interface\lib\datatableseditor\dataTables.altEditor.free.js</tt>, I am unsure whether this is used with the settings pages, but it is possible you can edit that script to make messages like "Success" appear in a different language).

=== Station Settings ===

Each setting has a hint beside it (with a small 'i' for information before each hint). If you have used [[Cumulus_Screenshots#Station|Cumulus 1]], the layout and section headings will be familiar. No settings take effect until '''Save''' button pressed.

Like all the settings pages, the headings are collapsed and need to be clicked to see the items under them.

The table [[Cumulus.ini#Section:_Station|here for the [Station] section]] will explain how MX stores the selections you make here, and give a bit more detail about each item and the values it can take. Please note that, in the '''Options''' section, there are two settings that take effect immediately '''Save''' is pressed, but are not written to '''Cumulus.ini''' and will be reset when MX is restarted; these two exceptions are to use '''Debugging logging''' and to use '''Data Logging'''. The first adds extra output to the log file created in "CumulusMX/MXDiags" folder reporting in detail each output task MX does. The second adds extra output to the log file created in "CumulusMX/MXDiags" folder reporting in detail each input received from the weather station.

=== Internet Settings ===

This has a lot of similarities with the [[Cumulus_Screenshots#Sites.2FOptions_Tab|Cumulus 1 settings]], except that this screen only covers what was on the main tab in Cumulus 1. Again there are hints, MX has more options than Cumulus 1 had, and some defaults are different in the two flavours. No settings take effect until '''Save''' button pressed.

[[File:Include graph data files.PNG|right]]

In Cumulus 1, you had one setting to upload the standard files and that included web pages, moon image, and the graphs. MX has separate selection settings for the uploading the standard files (web pages), the include graph files (JSON files used by charts), for generating the moon image, and for uploading the moon image. See image where the graph file option is arrowed.

All settings entered here are stored in [[Cumulus.ini]] and all (including '''FTP logging''' in '''Web/FTP settings''' section, it is not in the image as it is further down) retain their settings when MX is restarted. No settings take effect until '''Save''' button pressed.

Each section for an external web site has a number of parameters to set, once set MX will automatically upload to that site the weather values in the correct format. Windy has been added to the external web sites that can be automatically updated. No settings take effect until '''Save''' button pressed.

The main new feature within this settings page is a '''Custom Http''' section. Within here you can define commands to be executed either at some multiple of seconds interval, and/or at a selected intervals in minutes, and/or at end of day (in [[#MX_End_of_Day_Process|EOD sequence shown below]], the Custom HTTP is run before external programs are run, and that is before upload of Extra Files at EOD). In each of these you can use web tags to supply values for parameters to the command. Typically this would be used to send information to a remote web server. Here is a Custom HTTP example <pre>https://the_URL_here/your_api_here?winddir=<#avgbearing>&windspeedmph=<#wspeed>&windgustmph=<#wgust>&tempf=<#temp>&rainin=<#rhour>&baromin=<#press>&dewptf=<#dew>&humidity=<#hum>&uv=<#UV>"</pre> No settings take effect until '''Save''' button pressed. You need to turn on enhanced debug logging to see any confirmation that the http has run:
<pre>
2018-07-21 16:05:00.821 Custom HTTP Minutes update
2018-07-21 16:05:01.037 Custom HTTP Minutes response: OK: ok! (24.2)</pre>

=== Extra Web Files ===
This is an extension of the Cumulus 1 facility on the "Files" tab of its Internet Settings. How to use these settings is explained for both Cumulus flavours on [[Customised_templates#What_to_select_on_the_.27Files.27_tab_of_the_Internet_Settings_screen_within_the_.27Configuration.27_menu|this wiki page]], MX has an extra "end of day" (EOD) option, but otherwise you fill it out exactly the same way. Settings in one table cell are stored when you click in another table cell. Although, there is no Save button as clicking in another cell stores previous edit, the "Enter" button on many keyboards can optionally be used to be sure you have saved all edits made before you leave the screen.

Although to tick both real-time and EOD seems nonsensical, MX will let you for any selected file(s) do the processes and uploads at both intervals. I don't see why you should do that for normal running, but you might tick both to test a template without waiting for EOD, and after it has been processed once, remove the unwanted real-time tick, so from then onwards it just happens at EOD.

'''If you have moved from Cumulus 1''', and are therefore using an existing Cumulus.ini, these screens may be partly pre-populated, despite that you might need to:
# change some paths in local column, as you may be referencing some files moved when you installed MX
# untick one column, and tick another, now that EOD is an option for the timing as well as real-time and normal logging/ftp interval.
# edit some templates (local files) where the process column is ticked because of [[Webtags|Web tags differences]] meaning that some output modifiers are interpreted differently.
# you should not need to change remote file names, providing that you have not changed any directories on your web site as (like in Cumulus 1), for extra files, the remote path/file name required ignores any directories specified on Internet Settings screen for FTP settings.

=== Calibration settings ===
This is identical to [[Cumulus_Screenshots#Calibration|Cumulus 1 screen]] functionality, already explained in [[FAQ#I_get_very_large_amounts_of_rainfall_shown.2C_or_other_high_readings|Cumulus 1 FAQ here]] and [[Dayfile.txt#Dealing_with_rogue_measurements|"Dealing with rogue measurements"]] in this wiki.

=== NOAA report settings ===

[[File:NOAA settings.png|right | 200 px]]

This is identical to Cumulus 1 functionality, the various settings available on this screen are already explained [[Cumulus.ini#Section:_NOAA|for the settings file here]].

Just a quick reminder here that while Cumulus 1 is case insensitive for the code for the different ways to specify a month, MX only accepts upper case ('MM' for digits, 'MMM' for 3 letter month etc.), read more about [[Webtags#NOAA_style_Report_Naming|the naming here]].

=== MySQL settings ===

Cumulus MX includes functionality not in Cumulus 1, and this is one example of a new feature. It is designed to automate updating of MySQL databases whose schema has each table based on one of the Cumulus log files. This MX feature was developed from [[ImportCumulusFile|this script]] for Cumulus 1.

==== Brief background on SQL ====
It was IBM who first invented the concept of Relational Databases in the 1970s and they needed a language for all aspects of interaction with the new database and they called it Structured (English) Query Language. The brackets indicate the word was later removed. You may find when SQL is talked about, it is either pronounced "sequel" (as if there is still a "E" after the "S") or the 3 letters are simply spelt out.
*SQL is not '''Structured''' in the modern computing usage of that word concerning languages that can implement decision trees; instead the word structured here comes from the ability to make a query from a main query and a sub-query, although you might believe it relates to how the key words must appear in a particular order.
*SQL is not just for running '''Queries''', it can give and revoke access permissions, create and drop tables, and do many more tasks than just query a database to get results.
*SQL is a '''Language''' as it does have a set vocabulary, a defined sequence in which key words must appear, and it is used for describing tasks to a database.

A relational database has to satisfy a number of conditions, but the basic one is that all data appears in a table with rows and columns. The columns have a particular order, but there is no control over the order of rows, so you can't specify a row number, you '''either''' specify a primary key that identifies a particular row, '''or''' you specify a sort by the value in any column in a particular order and which row (or rows) you want out of that sorted order.

Like happened with video recorders and browsers, there was a relational database war, and thus division in language adoption, in the 1980s between 2 big players IBM's SQL and Ingres' QUEL, each gaining popularity in different ways, but the latter lost out, with newcomer Oracle taking the lion share of the commercial usage of SQL soon so very widely adopted, it achieved world dominance. There were a number of minor players who implemented their own relational databases, and initially their own languages, but SQL obtained a ISO definition in 1985 and was then widely adopted, surviving the invention of the internet, and the move from mainframes to small devices. MySQL is one of the rivals, but all versions of SQL are related and the dialect differences are comparatively minor compared to the commonality of the majority of the language. SQL is designed to be largely independent of how data is stored, so from 2000 as per newer standard SQL now works with [[Xml_webtags|XML]] as well as relational databases.

==== Implementation ====
Mono and .Net implement SQL capability, and this is utilised by Cumulus MX in the queries it generates. However, for SQL to work on your web site, you need to have a relational database available on your web server that accepts the MySQL that MX generates. It is worth saying that one difference between MySQL and the SQL standard is the former can insert multiple rows in one MySQL statement, but in the standard for SQL the specification says only one row can be inserted by one statement. Having made that clear, the SQL that is generated by the MX engine does only insert one row at a time, so the SQL MX generates is standard SQL.

MX does not include a database to install on your web site. Note, this does not mean your web server must have a MySQL database, as other products will understand the updating SQL (because of the dialect, commonality, and standard-meeting points I have just made), so the automatic updating should always work. One common difference between products is which data types available, so ''it is just possible that you might'' have a database that does not understand the column definitions in the '''MX option to create a table for you''' using MySQL dialect, so do be prepared in case you have to create each table yourself using a different method, the SQL to create a table is fairly simple, it even starts "CREATE TABLE table_name", but it is the list of columns with their data types and sizes that follows that is tricky if you don't know what is allowed on the database you are using.

Equally, the separate application, '''ExportMySQL.exe''' mentioned in its context below, includes SQL to create a table (with MYSQL data types) and add multiple rows in one instruction, so it is only able to work with databases that use MySQL (the clue is in the name of the application).

====Mandatory section====
* Server Details - expand this drop down as it is used for essential information for any access to the database on your web server:
*# Enter your host name or a IPv4 address for your web server. If you host your own server, it might be something like 127.0.0.1. It will be the same as you enter for host in the "internet settings" screen.
*# Enter the port for communicating with database server e.g. 33106. (Your web server provider should tell you whether the port is this or another number)
*# Enter the User Name for updating your database. (You may be able to set up user names on your database with different permissions, you need to state here one with updating permissions)
*# Enter the password for updating your database. (This will be set up for each user name)
*# Enter the name of the database that holds the tables you wish to update. (You probably have set this up, ask your provider if you need help)

====Optional Sections====

The remaining 6 drop-down sections are optional, you choose which you want to use, they appear on the screen in a different order to how I explain them below.

*Some of the optional settings described below, allow you to choose which log file to use for such automatic updates and what to call the table uploaded to (uploads will not work before the required table has been created).
*Alternatively, you can devise your own schema, create that table, and then write the SQL to update your table using web tags to supply all the values.
*You need to turn on enhanced debug logging to see any confirmation that the standard or custom SQL has run. With enhanced logging you will see messages like:
<pre>2020-04-09 10:00:01.047 MySQL: 2 rows were affected.</pre>


* 1.''Dayfile.txt upload''
** This section is about uploading to a database table that contains one row for each day.
** This feature takes the set of values that MX has just used for the line added to this [[dayfile.txt|log file]] at the end of the day, and soon afterwards inserts those same values into a new row (with columns named as per SQL example below) in a database table.
#If you don't have a table in your database for this upload (skip to step after SQL if you do), first
#* Choose Table name - the default table name is "Dayfile", but you can choose any other name
#*Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message
# Now find "Create database table" section below the Save button and click '''Create Dayfile'''.
#* MX will confirm when table has been created.
#*This will create the table using the following SQL (here using default table name) (the feels like columns were added in MX version 3.6.0):
<pre>CREATE TABLE Dayfile (LogDate date NOT NULL ,HighWindGust decimal(4,1) NOT NULL,HWindGBear varchar(3) NOT NULL,THWindG varchar(5) NOT NULL,MinTemp decimal(5,1) NOT NULL,TMinTemp varchar(5) NOT NULL,MaxTemp decimal(5,1) NOT NULL,TMaxTemp varchar(5) NOT NULL,MinPress decimal(6,1) NOT NULL,TMinPress varchar(5) NOT NULL,MaxPress decimal(6,1) NOT NULL,TMaxPress varchar(5) NOT NULL,MaxRainRate decimal(4,1) NOT NULL,TMaxRR varchar(5) NOT NULL,TotRainFall decimal(6,1) NOT NULL,AvgTemp decimal(4,1) NOT NULL,TotWindRun decimal(5,1) NOT NULL,HighAvgWSpeed decimal(3,1),THAvgWSpeed varchar(5),LowHum decimal(4,0),TLowHum varchar(5),HighHum decimal(4,0),THighHum varchar(5),TotalEvap decimal(5,1),HoursSun decimal(3,1),HighHeatInd decimal(4,1),THighHeatInd varchar(5),HighAppTemp decimal(4,1),THighAppTemp varchar(5),LowAppTemp decimal(4,1),TLowAppTemp varchar(5),HighHourRain decimal(4,1),THighHourRain varchar(5),LowWindChill decimal(4,1),TLowWindChill varchar(5),HighDewPoint decimal(4,1),THighDewPoint varchar(5),LowDewPoint decimal(4,1),TLowDewPoint varchar(5),DomWindDir varchar(3),HeatDegDays decimal(4,1),CoolDegDays decimal(4,1),HighSolarRad decimal(5,1),THighSolarRad varchar(5),HighUV decimal(3,1),THighUV varchar(5),HWindGBearSym varchar(3),DomWindDirSym varchar(3),PRIMARY KEY(LogDate,
'MaxFeelsLike', 'decimal(4,1)' ,'TMaxFeelsLike', 'varchar(5)','MinFeelsLike', 'decimal(4,1)','TMinFeelsLike', 'varchar(5)' ) COMMENT = "Dayfile from Cumulus"</pre>
#With the table existing, all you need to do is:
#* Enable - tick here when you are ready for this action [using the schema (set of column names) in the SQL quoted above] to happen at end of day
#* Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message.
# Now, to populate your table with past rows:
#* If you are using Windows, open a command window in the folder where "CumulusMX.exe" is found. Type <tt>ExportMySql.exe dayfile</tt>
#*If you are using another operating system, send the following instruction to the terminal in the folder where you installed MX. <tt>sudo mono ExportMySql.exe dayfile</tt>
#At the end of the meteorological day, MX will now automatically run the SQL to add a new row with the daily summary values as mentioned at the start of this section.


*2. ''Custom upload - at rollover''
** In the previous option, you have no ability to vary the schema, it will update a column for Total Evaporation even if your weather station cannot calculate that. It will update columns for total hours of sunshine, highest solar radiation level, and the maximum UV in the day even if you cannot measure these. It will not record whether snow was falling or lying, or the depth of snow if you wanted to be recording those.
** MX provides this alternative option, again doing an upload as part of roll over to next day ([[#MX_End_of_Day_Process|sequence shown below]], the Custom EOD SQL is run after the day reset to new date, but before the dayfile.txt update with existing values and so before today.ini to yesterday.ini processing).
**In this section you can specify the schema, and say which columns are to be updated with three selections:
**# Save - a button after all option sections, until you click it any changes you make in this section have no effect
**# A tick box to enable or disable this upload (so you can leave the SQL recorded, but stop running it when you like.
**# The SQL you want to run, what you type in this small text box should include INSERT IGNORE (or REPLACE) to insert a row, or include UPDATE to change columns in a row that already exists, like any SQL it must include the name of the table, the columns to be updated, and the values you want to insert into the columns are either expressed as web tags, as SQL functions on web tags, or as a sub-query reading the values from somewhere else.
**#* Here is an example of a suitable query that MX can process for you [note I have had to include some yesterday tags e.g. for primary key ('''<#metdateyesterday format=yyyy-MM-dd>''', and I have used the SUBSTRING function at one point, but I don't have a sub-query in this example):
<pre>INSERT IGNORE INTO `test_daily_summary` (`MaxRainRate`, `TMaxRainRate`, `HighHourRain`, `THighHourRain`, `TotRainFall`, `SnowFalling`, `SnowLying`, `SnowDepth`, `CumChillHours`, `LogDate`, `RollOver`, `MinTemp`, `TMinTemp`, `HeatDegDays`, `AvgTemp`, `MaxTemp`, `TMaxTemp`, `CoolDegDays`, `LowDewPoint`, `TLowDewPoint`, `LowHum`, `TLowHum`, `HighHum`, `THighHum`, `HighDewPoint`, `THighDewPoint`, `GreatWindChill`, `TGreatWindChill`, `LowAppTemp`, `TLowAppTemp`, `HighAppTemp`, `THighAppTemp`, `HighHeatInd`, `THighHeatInd`, `MinPress`, `TMinPress`, `MaxPress`, `TMaxPress`, `HighAvgWSpeed`, `THighAvgWSpeed`, `StrongestWindGust`, `TStrongestWindGust`, `BearStrongestWindGust`, `BearStrongestWindGustSym`,`BearDomWind`, `BearDomWindSym`, `TotWindRun`) VALUES ('<#rrateTM>', '<#TrrateTM>', '<#hourlyrainTH>', '<#ThourlyrainTH>', '<#rfall> ', '<#snowfalling>', '<#snowlying>', '<#snowdepth>', '<#chillhours>', '<#metdateyesterday format=yyyy-MM-dd>', '(1 * SUBSTRING(<#rollovertime>,0,2))', '<#tempYL>', '<#TtempYL> ', '<#heatdegdays> ', '<#avgtemp>', '<#tempTH>', '<#TtempTH> ', '<#cooldegdays> ', '<#dewpointTL>', '<#TdewpointTL>', '<#humTL>', '<#ThumTL>', '<#humTH>', '<#ThumTH>', '<#dewpointTH>', '<#TdewpointTH>', '<#wchillTL>', '<#TwchillTL>', '<#apptempTL>', '<#TapptempTL>', '<#apptempTH>', '<#TapptempTH>', '<#heatindexTH>', '<#TheatindexTH>', '<#pressTL>', '<#TpressTL>', '<#pressTH>', '<#TpressTH>', '<#windTM>', '<#TwindTM>', '<#wgustTM>', '<#TwgustTM>', '<#bearingTM>', '<#directionTM>', '<#domwindbearing>', '<#domwinddir>', '<#windrun>');</pre>
** Again before you enable this option, there is a facility lower down this setting page (under the heading '''Create database table''') where you can type some SQL to be run immediately, that can create the table you want this option to update, (although it could even populate any table with historic data, it is only intended for a small query). I am using a table that already exists as I have used it for testing changes to my PHP scripts, so I did not need to create a table before I enabled the query shown above.


*3.''Monthly log file upload''
**Cumulus starts a new log file for each new month, that is why this is called the monthly log.
**This database table has one row for each line in any monthly log and therefore the same table contains all months.
** This feature takes the set of values that MX has just added to the monthly log file, and soon afterwards if this feature is enabled, MX inserts those same values into a new row in a database table.
#If you don't have a table in your database for this upload (skip to step after SQL if you do), first
#* Choose Table name - the default table name is "Monthly", but you can choose any other name
#*Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message
# Now find "Create database table" section below the Save button and click '''Create Monthly'''.
#* MX will confirm when table has been created.
#* The SQL used to create the table is (columns marked NOT NULL have been in use for all Cumulus versions, the other columns have been added from various different versions) <pre>CREATE TABLE Monthly ('LogDateTime', 'DATETIME NOT NULL', 'Temp', 'decimal(4,1) NOT NULL', 'Humidity', 'decimal(4,1) NOT NULL',
'Dewpoint', 'decimal(4,1) NOT NULL', 'Windspeed', 'decimal(4,1) NOT NULL', 'Windgust', 'decimal(4,1) NOT NULL','Windbearing' 'smallint(3) unsigned zerofill NOT NULL',
'RainRate', 'decimal(4,$rainDec) NOT NULL', 'TodayRainSoFar', 'decimal(4,$rainDec) NOT NULL', 'Pressure', 'decimal(6,2) NOT NULL', 'Raincounter', 'decimal(6,2) NOT NULL',
'InsideTemp', 'decimal(4,1) NOT NULL', 'InsideHumidity', 'decimal(4,1) NOT NULL', 'LatestWindGust', 'decimal(5,1) NOT NULL', 'WindChill', 'decimal(4,1) NOT NULL',
'HeatIndex', 'decimal(4,1) NOT NULL', 'UVindex', 'decimal(4,1)', 'SolarRad', 'decimal(5,1)', 'Evapotrans', 'decimal(4,1)', 'AnnualEvapTran', 'decimal(5,1)',
'ApparentTemp', 'decimal(4,1)', 'MaxSolarRad', 'decimal(5,1)', 'HrsSunShine', 'decimal(3,1)', 'CurrWindBearing', 'varchar(3)', 'RG11rain', 'decimal(4,1)',
'RainSinceMidnight', 'decimal(4,1)', 'WindbearingSym', 'varchar(3)','CurrWindBearingSym', 'varchar(3)', 'FeelsLike', 'decimal(4,1)') COMMENT = "Monthly logs from Cumulus";</pre>
#With the table existing, all you need to do is:
#* Enable - tick here when you are ready for this action [using the schema (set of column names) in the SQL quoted above] to happen automatically.
#* Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message.
#* The upload you select here will happen every time MX creates a new line in the monthly log file, it might be every 10 minutes, but you may have configured a different interval.
#Separately, to populate your table with past rows:
#* If you are using Windows, open a command window in the folder where "CumulusMX.exe" is found. Type <tt>ExportMySql.exe monthly</tt>
#*If you are using another operating system, send the following instruction to the terminal in the folder where you installed MX. <tt>sudo mono ExportMySql.exe monthly</tt>


*4. ''Custom upload - minutes interval''
** One way you could use this option, is to replace the monthly log file upload if you wanted to change the schema, by leaving out some columns if your weather station is not able to measure all the derivatives included in the standard schema.
** This feature allows you to specify your own SQL for an upload to be repeated every NN minutes. Unlike the Monthly log file upload option you choose what schema (columns) are in the table that you are uploading a new row to and indeed exactly what SQL is used.
**Apart from the need to press the Save button that follows all the options, there are 3 items just for this option:
**# A tick box to enable or disable this upload (so you can leave the SQL recorded, but stop running it when you like.
**# The SQL you want to run, it should include INSERT IGNORE (or REPLACE or UPDATE) to insert/replace/update a row, include (as all SQL needs) the name of the table, include the columns to be updated and include the values either expressed as web tags or derived from a sub-query.
**# A drop down for the number of minutes between runs, the default is 10, but if your weather station updates less frequently, maybe you will choose 15, 20, 30, or 60 as the interval out of the 11 available in drop down.


*5. ''Realtime.txt upload''
** Cumulus MX can be set to recreate a file called [[Realtime.txt]] on a very frequent basis. The real time interval defines the time from the end of doing one real time update until the start of the next real time update. The file is recreated, in that unlike other log files, MX does not add new rows in each update, the file only ever contains a single line of values.
***MX does not use this realtime.txt file in any of its supplied components, so that file by default is not available on your web server.
***There is the ability elsewhere (Internet Settings screen) to upload this log file to your web server, should you wish to use it. The most common use is as a source for Ajax (JavaScript based) updating of web pages on the same very frequent basis.
**The option being described here is an alternative to having that log file on your web server, instead MX in this option MX updates a database table, adding a new row at the same very frequent interval.
***In this standard option, where you cannot specify which columns to include, MX will put into a database table row, the same set of values it would put into that log file on recreation.
***It is important to stress, this database table has rows added, so it is not equivalent to the uploaded file that contains a single line.
#If you don't already have a table in your database with the right columns for this upload, first
#* Choose Table name - the default table name is "Realtime", but you can choose any other name
#*Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message
# Now find "Create database table" section below the Save button and click '''Create Realtime'''.
#* MX will confirm when table has been created.

#With the table existing, there are 3 steps left:
# Enable - tick here when you are ready for this action of creating new rows to happen automatically.
# Enter in the text box a retention string in format '''retainVal=NNN retainUnit=XXXX''' where NNN is a number from 1 to 3 digits long, and XXX is a time unit e.g. second, minute, hour, day, week, month, quarter, or year.
#* Because the updates are so frequent this database table grows very quickly, and you need to say when it should delete the older rows so the table never has too many rows. If you think about it, after a few days, you probably do not need to look at this very detailed level of values information within a day. In that case set retention to delete after a few days ''retainVal=3 retainUnit=day''.
# Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message.


*6. ''Custom upload - seconds interval''
** This feature allows you to specify your own SQL for an upload to be repeated every NN seconds. This caters for when you want something like the values in "realtime.txt" but want to specify your own schema (set of column names) or your own interval between updates (independent of what has been selected for real-time interval). Like the other custom options, this might be because you have extra sensors or do not have sensors for all items in standard log file.
**Apart from the Save button below all options, there are 3 items specifically for this option:
**# A tick box to enable or disable this upload (so you can leave the SQL recorded in Cumulus.ini for when you want to use it again, but start/stop running it as and when you like).
**# The SQL you want to run, it should include INSERT IGNORE (or REPLACE or UPDATE) to insert a row, the name of the table, the columns to be updated and the values you include in your SQL are expressed as web tags. You can have more than one SQL statement in this box (end each with semi-colon) so you might want to add a delete "DELETE FROM YourTableName WHERE LogDateTime < DATE_SUB(NOW(), INTERVAL 7 DAY);" after your update/insert command to replicate the retention option of the previous feature, in this case deleting rows over a week old.
**# The number of seconds between runs, the default is 10, but if your weather station updates less frequently, maybe you will choose 40 or 60 as the interval. In theory the number of seconds specified here might represent anything between how frequently your weather station reports readings and several hours.

=== Alarms ===
This is identical to Cumulus 1 functionality, apart from using a new default location for the files "\CumulusMX\interface\sounds", the alarms available are already explained [[Cumulus.ini#Section:_Alarms|elsewhere]] in this wiki.

The alarms are shown at the bottom of the Dashboard page of the user interface. They also feed a set of [[Webtags#Alarms|Webtags]].

=== FTP Now ===
This is similar to the option in the file menu of Cumulus 1 to do an update now. Depending on which build of MX you are using, the functionality varies. On latest build it does whatever updates are set up to happen at normal updating interval whether these are by FTP to your web site, or by copying files between local and remote filenames with path (although both could be on same device).

== Editing the Admin Interface ==

=== Caution against editing Admin Interface ===
The general advice is do not change any files that are part of the MX package, they are a package and therefore there are interdependencies. Also updating to a newer release is more complicated if you have edited any files. The files as provided in the MX package are a compromise, for example they include reporting on solar measurements but not all weather stations include such measurements. Given that the admin interface is not shared with anyone else, it could be argued its look and content is not that important. In particular this interface is the only way to change settings, so do not change anything that stops those setting screens from working!

Finally, if you don't like the look of the admin interface, then why not look at your web pages, apart from settings, they should show you the same information, and you can edit your web pages to show information in whatever way suits you.

=== Caution when updating if you have edited Admin Interface ===
Remember, if you decide to download a new release to not overwrite any file(s) that you have edited, or your edit will be lost. It is less likely that a new release will change the interface files than other files, but some releases do change these files. Remember, each release zip contains all MX files, even those not changed since previous release. The release notice will usually give some idea of whether interface files have changed, but it may not list which interface files have been added, modified, or removed.

=== General points for editing ===
If you do decide to change any file, I suggest you maintain a back-up copy of the original elsewhere (so it can be gone back to) and you save the edited file under a new name (so you can't lose my edited file by installing a new release).

If you are editing files, use Notetab lite, notepad++ (for windows), or BB-edit on a Mac, i.e. use an editor designed for code, do not use a word processor, a Microsoft or Google editor or Dreamweaver or any other web editor. The encoding that should be used is UTF, if your editor does not mention encoding, it is the wrong sort of editor!

=== Changing the look ===
You need some understanding of Cascading Style Sheets (CSS) to do this, but all you need to do is to edit the relevant style sheet either in '''\CumulusMX\interface\css''' or in the relevant folder within the lib folder.
You may feel that the default look of grey, black, and white, is either boring or does not offer sufficient contrast for you, perhaps you feel certain font sizes are too small, or you want to change the page background. Well, you can change the look, it is all defined in .css files. However, because MX makes use of standard libraries (bootstrap, datatables, alcapa etc.) there are a multitude of .css files used and it might not be easy to work out which one to edit. Each HTML page has links to a number of css files. You will probably make use of developer functions in your browser to inspect any element whose look you wish to change to see where its different properties are defined. It is better to make any such edits at a high level, rather than on any CSS just for that particular element. As always when editing, keep a copy of original so you can go back to it; keep a copy of your edited file, so installing a new release does not lose you edited file.

=== Removing Solar Figures ===
If your weather station does not have solar instrumentation you might wish to remove some of the display elements that relate to that. You need some understanding of Hyper-Text Markup Language to do this correctly, but here are simple examples.
# Navigate to '''\CumulusMX\interface''' folder.
# Open the file '''now.html''' in an editor designed for code (e.g. Notepad++ for Windows, Notetab Lite)
# Near the bottom of the file edit it by inserting HTML comment delimiters (opening after &lt;/thead>, closing before &lt;/table>) so it looks like this:
<pre><table id="SolarTable" style="width:100%">
<thead>
<tr>
<th>&nbsp;Solar</th>
<th></th>
<th></th>
</tr>
</thead>
<!--
<tr>
<td>Solar Radiation</td>
<td><span id="SolarRad">--</span></td>
<td>W/m<sup>2</sup></td>
</tr>
<tr>
<td>Sunshine Today</td>
<td><span id="SunshineHours">--</span></td>
<td>hrs</td>
</tr>
<tr>
<td>UV</td>
<td><span id="UVindex">--</span></td>
<td></td>
</tr>
-->
</table> </pre>
IMPORTANT NOTES:
#The above approach works on "now.html", but it does not work on other pages where table rows are dynamically created by an external script, so the existing rows in the table body are dummies whose content is ignored.
*An alternative technique is to delete the whole table and any "&lt;div> .. &lt;/div>" that surrounds only that table, that will work on all the HTML pages.

=== Adding derivatives not shown on the existing admin interface page ===
It is a JavaScript file '''\CumulusMX\interface\js\dashboard.js''' that reads the real-time file and inserts particular content into position indicated by values of the HTML attribute "id" on the admin interface screens. The standard '''\CumulusMX\interface\now.html''' does not include temperature trend for example, but because there is a '''temptrend: inp.TempTrend.toString()''' defined in the JavaScript file, you can easily add it to the "now" page by a simple insert of the middle row here:
<pre><tr>
<td>Outdoor Temperature</td>
<td><span id="OutdoorTemp">--</span></td>
<td><span class="TempUnit">--</span></td>
</tr>
<tr>
<td>Trend</td>
<td><span id="TempTrend">--</span></td>
<td><span class="TempUnit">--</span>&nbsp;hour<sup>-1</sup></td>
</tr>
<tr>
<td>Dew Point</td>
<td><span id="OutdoorDewpoint">--</span></td>
<td><span class="TempUnit">--</span></td>
</tr></pre>
You can't add any derivatives into any table unless the value (for the derivative you want to add) is already defined in the related files.

There is a section of the support forum devoted to [https://cumulus.hosiene.co.uk/viewforum.php?f=28 Cumulus MX interface customisation], so you can see what other people are doing. There is also [https://cumulus.hosiene.co.uk/viewforum.php?f=36 another sub-forum] for making suggestions on what you would like added to MX.

= MX End of Day Process =
I have added this section, because this process has given me some headaches. If you write custom SQL, or have a template being processed at end of day, then what I find strange is that web tags related to system date report the new date, but other web tags report weather derivatives from the old day. Put another way, the date changes at start of rollover, but the weather web tags change at end of rollover. However, it is not quite as simple as that, the month and year are reset after any Custom SQL is run (so that SQL can use monthly and yearly web tags related to previous day), but before the extra files are processed (so they cannot use monthly web tags at end of month, nor yearly web tags at end of year). See why I found it hard to digest, and why I wanted to write it here to make it easier for others.

Mark Crossley says the MX day reset does this...
<tt>
Reset midnight rain
Entering Day Reset (message about current day of month, at this stage web tag <#metdate> changes to new date)
Day Reset (message about date ending, time shown as 00:00:00 because time not defined, not because it is midnight, it might be 9am or 10am)
Run EOD custom SQL
Save dayfile entry (uses what is still in today.ini that includes old date, i.e. what is now in web tag <#metdateyesterday>)
Write monthly & yearly file entries
Write any new daily extreme records
if day of month = 1 then: copy month.ini to saved file, reset monthly figures
if day of month = 1 and month = 1 then: copy year.ini to saved file, reset yearly figures
Copy todays high/lows to yesterdays
Reset todays high/lows to current
Write today.ini & yesterday.ini
Create NOAA reports
Execute user daily external program
Process Extra EOD files
</tt>
But independent of above EOD thread that occurs on the rollover hour, the '''normal interval''' and '''hourly processes''' thread is seeking to run at same time, whether that happens at same time depends on processing capability and whether it can process multiple threads.

What actually happens in above list depends on your settings, and if your FTP interval is synchronised with the logging interval.

= SPECIAL CONSIDERATIONS - Text by Steve Loft =
== Restrictions in MX for decimal separators ==
On the subject of decimal and list separators, there are a couple of issues which users of decimal commas may encounter.
#The first is that there may be an issue with some of the user interface not working correctly. Please report these issues and I will fix them. There may be aspects of the displays that I cannot change (because the package used does not support decimal commas) but it should be possible to at least get it working.
#The second issue with decimal separators only affects the Raspberry Pi (as far as I am aware). There is apparently an issue with a version (3.2.8) of the Mono package on Raspbian 'hard float' where it cannot parse values using decimal commas. If this does turn out to be an issue, there are a number of possible workarounds until the Raspbian package gets updated. One workaround is to use the 'soft float' version of Debian instead. Obviously, this will have performance issues, but is probably the easiest. The second workaround is to build Mono from the latest sources, see http://www.mono-project.com/docs/compiling-mono/linux/. I am told that this fixes the problem. Another possible workaround would be to find an already fixed binary package, but I don't know if one currently exists.

''PLEASE NOTE: The issues that Steve describes seem to have gone away with currently available versions of Mono; update your Mono if you are using an old version and encounter problems.'' Like any software, Mono might have bugs at a particular version, and sometimes you might need to swap to an older version if the current version has an outstanding issue.

== If you want to use your Cumulus 1 data with MX ==
If you use decimal commas in your Cumulus 1 data, you will need to edit the .ini files to change the decimal commas into periods/full stops, because '''Cumulus MX always expects periods/full stops in .ini files''' ''regardless of the locale in use''. The other data files will be OK - assuming you are using the same decimal and list separators in MX as you used in Cumulus 1 (i.e. the same locale). If you try to switch to a different locale, then your data log files will of course no longer be in the correct format, so you would need to edit all of your files. You can select the locale for MX to use as a switch parameter when it starts up, see earlier on this page.

== A note to Davis owners ==
I am experimenting with the use of the LOOP2 packet. The current code uses this for two purposes. First, it uses the 'peak 10-minute gust' value, to avoid the problem where a gust might be missed (although hopefully this will not be such an issue with Cumulus MX as it does not use the Davis DLL), and secondly it uses the 'absolute pressure' value to make calculation of 'altimeter pressure' easier and more accurate. This is mainly used if you upload to CWOP.

The LOOP2 packet is supported on the VP2 with firmware version 1.90 or later, and on the Vue. If you have a Vantage Pro (i.e. the original 'VP1'), or a VP2 with pre-1.90 firmware, or if you are using Virtual VP, none of these support the LOOP2 packet. In these cases, you should edit cumulus.ini and add a line to the [Station] section:

UseDavisLoop2=0

With this setting, Cumulus will revert to calculating the 10-minute gust value itself from the individual wind speed readings, but it will not currently attempt to calculate altimeter pressure correctly, it will simply use the sea-level pressure instead. This is likely to be an issue if you are at high altitude and you upload to CWOP using Cumulus MX.

Also for Davis stations, I have assumed that people using millimetres in Cumulus have a metric rain gauge (0.2 mm per tip), and those using inches have a 0.01" rain gauge. This can be over-ridden by adding a line to the [Station] section of Cumulus.ini:

VPrainGaugeType=0

or

VPrainGaugeType=1

Where 0 is a 0.2mm gauge and 1 is a 0.01" gauge. Note that changing this after MX has already read some data may cause your rainfall reading for today etc to change considerably, so you will need to correct that.

= Web Tags and related features =

Almost all of the [[Webtags|web tags for all Cumulus flavours on this Wiki page]] that you could use in Cumulus 1 are also supported in Cumulus MX.

Each new build of the beta MX has increased the range of web tags it supports. Since MX has come out of beta, new versions have not only implemented the remaining tags from Cumulus 1, they have also added new tags not previously available. For full details see the [[Webtags#Differences_between_Cumulus_1_and_Cumulus_MX_.28Cumulus_3.29:|web tags]] article, but a quick précis follows in next few sections.


== All builds of MX ==
The ''''format' parameter''' on the date/time output modifier for web tags is unfortunately different, because many of the characters used are different. See [[Webtags#List_of_allowed_modifiers|the modifiers list]] page of this Wiki.

Note that this difference in date/time modifiers also affects how you specify the '''NOAA report''' file names. For example in Cumulus 1 you can specify a 2 digit month number by either 'mm' or 'MM', but MX (later versions) has to change the former to the latter as MX uses 'mm' for minutes. The same applies to using 'mmm' or 'MMM' for 3 letter month abbreviation in Cumulus 1, only the latter works in MX, so MX (later versions) will adjust that. If you are using an older MX version, you should upgrade to latest as you are missing a lot of functionality, but while you use that old version, ensure that your file names for NOAA reports do use the correct modifiers for MX.

== Beta builds of MX ==
The following web tags were not available or worked differently:
*The individual 'record set' tags such as <#TempRecordSet> etc did not work (because the interface then had no indicators for new records and no way to reset them).
*The <#newrecord> tag does work, but works differently, it turns itself off automatically after 24 hours.
*Some of the 'system status' web tags do not work: <#CpuName>, <#MemoryStatus>, <#DisplayMode>, <#DiskSize> and <#DiskFree>
*The <#txbattery> web tag has no content currently. Using it with a 'channel' parameter causes a 'token error'.
*The snow tags were not available as there was no '''Weather Diary'''

== Current builds of MX ==
The web tags you have depend on which build you are using:

From beta version 3.0.0 - Build 3046 of 2 Jan 2019
* added <#snowdepth> tag processing
* added '''diary.db''' file

From beta version 3.0.0 - build 3047
* Web token parser updated to cope with html tag characters "<>" in the format string e.g. <#TapptempH format="dd'&nbsp;'MMM'&nbsp;'yyyy'<span class=\'xx\'> at 'HH:mm'</span>'">
*All record Value tags should now return '---' and Date tags '----' until they are first set.
*<#MoonAge>, <#MoonPercent>, <#MoonPercentAbs> - all given new 'dp' and 'rc' parameters.

From version 3.1.1 - build 3054
*Adds new web tags <#snowlying>, <#snowfalling>, both provide 1|0 responses

From version 3.2.0 - build 3056 of 19 November 2019:
* Enables alarms as per Cumulus 1
**New Alarm page under Settings
**Alarms are shown visually on the dashboard
**Due to browser restrictions, alarm sounds on the browser page may require you to click a button on the first alarm in order to hear it.
***You can add the MX admin site to your browsers list of sites allowed to play sound automatically. Your browser should "learn" that you want to allow sounds to play automatically.
*** Alarm sound files should be placed in the /interface/sounds folder, they must be a browser compatible format (mp3 are good). The alarm settings for the sound file should be just the filename without any path
*Lots of new web tags not available in Cumulus 1, see release announcement for details

From Version 3.2.2 - build 3058
*Implements the missing <#txbattery> web tag

From version 3.5.1 - build 3072 of 10 April 2020
*Implements the tags that indicate when records are broken
* You configure whether if a record is set it turns off after 24 hours or a different period.

= [[Cumulus MX FAQ]] =
The [[FAQ]] page that was originally written for Cumulus 1 has now had some MX differences highlighted. A new FAQ for MX has been started at [[Cumulus_MX_FAQ|another page]].

MX specific questions, such as those related to installation are now covered by the updated text on this "Cumulus MX" page.

= [[MX Issues|Cumulus MX Known Issues]] =
See [https://cumulus.hosiene.co.uk/viewtopic.php?f=27&t=12943#p101209 Steve Loft's post]

Latest revision as of 15:18, 10 January 2022

This category lists all the pages that are relevant to MX, so is a good starting point.

  • There are pages in this category for all folders and files, used by MX
  • If you contribute a new page, add it to this category by quoting [[Category:Cumulus MX]] on your new page.
  • How to migrate to MX - For those still using the original Cumulus software

SOME KEY INFORMATIVE PAGES (FOR NOVICES):

REFERENCE PAGES (FOR EVERYONE):

SPECIALIST GUIDES (NOT FOR NOVICES):

PAGES THAT WERE CREATED FOR MX BETA: These were created in a rush when there was a threat that the support forum would close, they need a willing contributor to sort them into useful pages:

  • MX Issues Detailed known issues with 3.0.0 beta releases
  • Cumulus MX FAQ Was intended to be quick reference answers to frequent questions

Subcategories

This category has the following 5 subcategories, out of 5 total.

F

I

J

M

Pages in category "Cumulus MX"

The following 72 pages are in this category, out of 72 total.

A

C

D

E

F

H

M

P

R

S

T

U

V

W

Y

Retrieved from "https://www.cumuluswiki.org/index.php?title=Category:Cumulus_MX&oldid=10149"