View source for Cumulus 3 (MX) beta documentation

=Intoduction=

This page has been created to hold information that Steve Loft made available when in 2015 he first made Cumulus MX beta builds available to the minority who showed an interest in trying it out:
*In 2015, Cumulus 1 was still recommended for most users, and it would remain so for another couple of years. 
*In 2017, the text, now on this page, was first put on another page in this Wiki. At that stage, MX was still in beta, and everything here applied to the latest build available.
*Most new Cumulus users, up to 2019, installed the original Cumulus. Relatively few new users adopted this MX beta, even when Mark Crossley first took over development and the original Cumulus was labelled as the legacy version by administrator Freddie. 
*Up to mid-2020, '''there were many, many more people using Cumulus 1 than were using MX'''.
*In mid-2020, the trickle of migrations from Cumulus 1 to MX became a flood, because by then Mark Crossley had added a lot of extra functionality to MX that was missing from Steve Loft's beta builds that this page talks about.


{{TOCright}} [[Category:Cumulus_MX]]
If you are using MX beta (versions 3.0.0 to 3.0.2), this page is for you. However, you will gain many benefits if you follow advice on [[Updating_MX_to_new_version]] page, as not only do newer builds have more functionality (including ability to correct errors e.g. in extreme records), but they also fix lots of bugs present in the software you are using.

This page may also be of historic interest to those wondering about Cumulus MX as originally developed by Steve Loft, before Mark Crossley took over development. 

Much of the content below is based on material that Steve Loft wrote in the Cumulus support forum when it was hosted by Steve (http://sandaysoft.com/forum/ is no longer available).  Mark Crossley copied the material into the Cumulus Wiki (the page title was "Cumulus_MX" at the time), to ensure it was preserved, in the period between Steve Loft saying he would not host the Wiki and Support Forum any more (September 2018) and Ken True taking over the hosting of the Wiki (October 2018). At that stage, nobody had agreed to take over the Cumulus Support Forum and there was a danger that the information below would be lost.  Around a month later, Neill Hosiene fixed some problems on the Sandaysoft host and subsequently he took over hosting of the forum, so you can now find the original content at [https://cumulus.hosiene.co.uk/viewforum.php?f=39 MX early builds support forum].


== Message from Steve Loft about who can use MX ==

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

== Message from Steve Loft about documentation ==

''The following was written by Steve Loft,  on 2 January 2015, when he first made his MX beta available to Cumulus users.''

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. 

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.

Note that most of the Cumulus 1 documentation also applies to Cumulus MX, so although [[FAQ|Frequently Asked Questions for Cumulus 1]] is specific to the original Cumulus software it might help you. Looking at the Cumulus 1 help file, it is available on the [[Software#Resources|Software Resources page]] will help you.  If you already use Cumulus 1, the help is part of the standard installation.

MX specific documentation, for this beta, is currently in very early stages (e.g. [[Cumulus MX FAQ|Frequently asked questions for MX]]) and some settings may not be obvious. Some of the articles elsewhere in this wiki will help, and will in due course be updated to cover MX. 
 
=== Message about this update to documentation ===

Although the message above from Steve Loft has been retained, it is no longer really true. When that was written MX had only been worked on for a year or so.  During that time it had been only available to people who had specifically requested for a copy of the package, and been subsequently provided with it. After that, the beta testing package became available at a download site where anyone could get it. 

Since then, of course MX has come out of beta and added a lot more functionality. More importantly, it has gained a large user base (although Cumulus 1 is still used by considerably more people than MX, there has been a recent surge of converts), and that means it is much better known, and consequently it is possible now to document it much better. You will now (January 2021) find there is extensive MX (out of beta) documentation available from [[:Category:Cumulus_MX|this Wiki]].




= Executables =

The MX package, at time of typing this, includes two executables:

== CumulusMX.exe ==

Whilst effectively MX is run by a '''CumulusMX.exe''' or '''sudo mono CumulusMX.exe''' depending on device, you actually need to ensure all the other components are loaded, so you either have a package that runs it for you, or you click a shortcut that includes the necessary path setting.

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

Beta builds in MX version 3.0.0 had an optional parameter <tt>-wsport nnnn</tt> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''WebSockets'''. That parameter is now deprecated as WebSockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. The remaining parameters that are still available are described in subsequent sub-sections.

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

MX has a default level of logging that stores in  the [[MXdiags_folder]] a log file that shows some of the interaction with the weather station and some of the output actions done as MX runs. A new log is started each time MX is restarted.

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings ('''options''' section of ''station settings'') in admin interface  while MX is running, or by adding 1 or 2 parameters when you start MX.  Obviously this log file continues to grow, the longer MX is left running, and if debugging is switched on the file will grow in size must faster. Consequently, the default is not to add the extra debugging information and the settings can be used to switch it off again if you do have it switched on. Whether you start it with a parameter or enable it within settings, stopping MX will end the extra debugging, and on restart it will default back to no debugging unless turned on again with parameter or setting.

You can also add  '''CumulusMX.exe -debug''' (to have full debugging of actions by MX turned on as MX starts), and/or '''CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging). 

<pre>sudo mono CumulusMX.exe -debug -Logging=1</pre>

Since this parameter is applied when you start MX, it applies while MX continues to run. Obviously, it must be applied every time you start MX if you want this increased level of logging to continue every time you restart MX.

The comments in the MX source suggests -debug turns on both debug and data logging (see [[MX_Administrative_Interface#Options|Station_Settings#Options]] in admin interface settings), but I believe that is wrong as per example above, there are 2 separate parameters.

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

== [[ExportMySQL.exe]] ==

This second exe file (see link in heading) has been available since the original MX package as Steve Loft developed this in April 2015, but sadly few people even notice it exists, and if they do, it is unlikely they know how to use it. Hopefully, some people will read this section and find out!

Obviously it was updated when Mark Crossley added the Feels Like fields to log files.

Put simply, this executable will read log files and insert (insert ignore) rows into an existing database table. Since it only does inserts, despite the name of this function, it is not just for MySQL tables, the included SQL should work with whatever database table type you have. 

The executable has a mandatory single parameter that tells it which log files to read, there are only 3 possible parameters ("dayfile", "monthly", or path to a file). It needs to know what locale (or culture settings) it is to use to work out what character separates each item in the log file list. It also needs to read your Cumulus.ini file, as it takes these "input parameters" from MySQL section in that:
*Host
*Port
*User
*Pass
*Database
*MonthlyTable
*DayfileTable

=== Daily summary log file ===

# Use the feature in the admin interface:
#* Settings menu
#* MySQL settings page
#* In '''Dayfile.txt upload''' section, give your database table a name, or accept default ''Dayfile''.
#* Click '''Save''' to ensure this setting is updated
# Now scroll down to '''Create database table (save settings first)'''
#* Here click '''Create Dayfile'''
# Now you have a database table ready, you can use the executable to read all lines in your '''CumulusMX/data/dayfile.txt''' log file.
# Open a terminal display (if you are using Windows then, open a Command Window, a Windows Powershell window, or a Windows Terminal window)
# Run this executable in that terminal display (or command window) by using  '''sudo mono ExportMySql.exe daily''' or <tt>ExportMySql.exe daily</tt> depending on device.
# In the terminal display (or command window) you will see '''Parameter = daily''' confirming what you entered and in the line below that a rapidly updating code that is the primary key displayed for each row it tries to insert into the table.  If that primary key already exists in the table, it will still show the key, but no insert will take place.
#If you want MX to continue adding new rows to this database table, still in the admin interface, still in MySQL settings page:
#* Return to '''Dayfile.txt upload''' section, and select '''Enable'''.

=== Standard Log files ===

# Use the feature in the admin interface:
#* Settings menu
#* MySQL settings page
#* In '''Monthly log file upload''' section, give your database table a name, or accept default ''Monthly''.
#* Click '''Save''' to ensure this setting is updated
# Now scroll down to '''Create database table (save settings first)'''
#* Here click '''Create Monthly'''
#If you want MX to continue adding new rows to this database table, still in the admin interface, still in MySQL settings page:
#* In the same '''Monthly log file upload''' section, now select '''Enable'''.
# Now you have a database table ready, you can use the executable to read all lines in either one (if path to that file is in parameter), or every (if parameter is monthly) standard log file.
#*If the parameter is "monthly" it will look in folder '''data'''  for every file it can find with a file name of datestring + "log.txt" where datestring is a 3 letter code (in your locale) for each month (1 to 12) followed by a 2 digit year (from "00" to "99") so that is how it finds every standard log file in the folder.
# Open a terminal display (if you are using Windows then, open a Command Window, a Windows Powershell window, or a Windows Terminal window)
# Run this executable in that terminal display (or command window) by using  '''sudo mono ExportMySql.exe monthly''' or <tt>ExportMySql.exe monthly</tt> depending on device.
#* Alternatively, replace '''monthly''' parameter by a full path to a single standard log file, and it will process just that log file.
# In the terminal display (or command window) you will see '''Parameter = monthly''' confirming what you entered and in the line below that a rapidly updating code that is the primary key (omitting the first two digits of the year) displayed for each row it tries to insert into the table.  If that primary key already exists in the table, it will still show the key, but no insert will take place.  So you can run this again to pick up any additions to the latest log file since the original run. Also notice that if you use the parameter "monthly" the order in which it will process different standard log files is not predicable, they probably will not be in any particular order, but as one feature of SQL databases is that the row order is not able to be determined, it does not matter if rows are not added in chronological order.
#* It is worth noting that it is safe to run this procedure while MX is also running, because this procedure only updates log entries that exist as this  procedure reads the logs, and MX only adds new entries to the log and at the same time uploads that new entry (if enabled) to the database table.

Please be aware that the transfer to the database table adds two columns where bearings in the original log file given in degrees are output as compass directions, and these use up to 3 letters of how the compass directions are defined in the '''strings.ini''' file. Thus the number of columns in the database table will be at least 2 more than the number of fields in the log files. It is also important to stress that whilst the database table must contain one column defined for each field (plus the extra 2) being uploaded, you can add even more columns to your table if you want and populate those some other way. For example, I have added a Canadian Humidity Index (Humidex) column which is not in the standard logs, but is calculated by Cumulus, and can be calculated from columns that are uploaded from the standard log. Humidex is not uploaded by either ExportMySQL or the normal CumulusMX process, but neither objects to extra columns being there.

When testing this, I had some log files produced by various old versions of Cumulus 1 in my MX data folder as well as the log files in has generated since I swapped to MX. Plus I had used a PHP script to add feels like to those log files produced before version 3.6.0 and to correct feels like for those log entries made by versions 3.6.0 to 3.6.9 inclusive because they used a different formula to the one being used from version 3.6.10.  This php script is a web page with a HTML form and can be obtained from the forum in [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 Create Missing for MX]

I notice that the database rows produced by those short log file lines produced by say version 1.9.0 had nulls entered for all subsequent columns, except '''Feels Like''' and this column was initialised at 0.0!

For those log files produced by the final version 1.9.4, all columns are populated although feels like is set to 0.0.



= 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. For full details see the [[Webtag_Applicability|web tags applicability]] article, but a quick précis follows in next two sub-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/Parameters#Dependency_on_Cumulus_flavour]] 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 are not available or work differently:
*The individual 'record set' tags such as <#TempRecordSet> etc are not available in MX beta builds (because the interface by Steve Loft 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> (These can not be implemented for software that can run on a multitude of devices)
*The <#txbattery> web tag has no content currently. Using it with a 'channel' parameter causes a 'token error'.
*The '''Weather Diary''' feature is only available from beta version 3.0.0 - Build 3046 of 2 Jan 2019 onwards, it offers same web tag (<#snowdepth>) as the original Cumulus 1.
*From beta version 3.0.0 -  build 3047 onwards:
** 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 return '---' and Date tags should return '----' until they are first set.
**<#MoonAge>, <#MoonPercent>, <#MoonPercentAbs> - all given new 'dp' and 'rc' parameters.




= 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|Software download page]].

== Replacing Cumulus 1 ==

See [[Migrating from Cumulus 1 to MX]] page. If you wish to run MX on Windows, then you can unzip the contents of the download package over your original cumulus installation, i.e. so the same data and Reports folders continue to be used. But it would be best if you take a back-up copy of the Cumulus 1 installation first!  If you are going to run MX on another device, follow instructions in next sub-section.

The package contains several extra .dll files, and everything else you need, to continue to read from your weather station, to load up the [[MX Administrative Interface|admin interface]] on a Cumulus generated web server (there are some settings you will need to change using that interface), and some simple web template examples (that replace the standard Cumulus 1 example templates).  You might want to read topics on the MX support forum to discover about other people's experiences.

== Completely new MX installation ==

See earlier for links to other articles about installing on a Windows PC or a Raspberry Pi. Here only a brief indication of installation is covered.

*Create a new directory (recommended name CumulusMX) and unzip the contents of the [[Software|download package]] into it. 
*See notes below for extras required in various operating systems.
*The package contains several extra .dll files, and everything else you need, to continue to read from your weather station, to load up the [[MX Administrative Interface|admin interface]] on a Cumulus generated web server (there are some settings you will need to change using that interface), and some simple web template examples (that replace the standard Cumulus 1 example templates). 

== 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 have been running Cumulus 1 before, then [[Migrating from Cumulus 1 to MX|as instructed here]] your MX installation will require various files from your Cumulus 1 installation including all files in the '''data''' and '''Reports''' folder and all [[:Category:Configuration Files|Configuration Files]] including Cumulus.ini but a few of the parameters that you may need to change.

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 showing what you see as the engine starts running, and what you see in the admin interface where you set your weather station type. In that link there are more instructions.


=== 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 the following commands, but '''first you need to have set up various pre-requisites''' (see [[MX_on_Linux]] article  for details):

<pre>sudo apt update && sudo apt upgrade
sudo apt install mono-complete</pre>
Note that you do need to have the '''mono-complete''' package installed, not just the Mono for developers.

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>

There are some optional parameters you might need to use, as they also apply to windows they are covered later.

Next start the administrative interface, basically same as described for Windows above. More information on admin interface [[MX Administrative Interface|in separate article]].


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

====Stopping MX====

The best way to stop MX is by sending a '''control and C''' sequence to it.  There is a start stop routine discussed in the support forum, where you will also find some topics about shutdown issues.

The MX source listing suggests it also accepts ''control and break'', '''Close main window''', ''user logoff'', and '''system shutdown''' and should still attempt to stop running tidily. There are various tasks like writing final values to log files and recreating the configuration file, [[Cumulus.ini]], that it needs to do as part of the MX closing routine, and obviously early closure of the device running MX (such as that caused by a power cut) will prevent a tidy end to MX.





=== Requirements for running on Windows ===

For those who downloaded the first MX Beta in January 2015, the code was only experimental and that version had to be run by a Windows Administrative User, but Steve Loft soon improved the code and now none of the code requires any elevated rights and it can be run by a normal user (or  a user with administrative rights) without needing to be started by '''Run as administrator'''.

However, Cumulus MX initiates a web server, which is what runs the [[MX_Administrative_Interface|Admin Interface]]. To access that, all users need to be given elevated rights to the port on which the web server runs. By default this is port 8998, so that is used in the example below of the one-off command needed to give all users access to the port. You can use a '''-port=nnnn''' parameter when starting MX to make it use another port, if you use that then the command below needs revising accordingly.

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 is dependent on some settings which determine what appears when you right click:
*the normal default on Windows 10 is '''Windows PowerShell (admin)''',
*the normal default on earlier versions of Windows is  '''Command Prompt (Administrator)''' 
*an alternative is '''Windows Terminal'''
Whichever of these you can use, the result is it opens a new window on your monitor with a prompt for typing. In that window type the command:
<pre>
netsh http add urlacl url=http://*:8998/ user=\users
</pre>

You only need to do that once. If you do not issue this command, administrative rights are needed every time to access the port.

Talking about command windows, if you want to check that the port is open for listening (i.e. able to access the admin interface) type <tt>netstat -an | findstr 8998</tt> into the command window.

The admin interface URL '''http://*:8998/''' needs to have that wildcard "*" replaced by a precise location if we are to access the admin interface.  The missing part of the URL depends on how your local network is set up.  If you are accessing the admin interface on the same device as that running MX (and you don't have another web server on that device) the "*" can be replaced by "localhost", i.e. '''http://localhost:8998/''' will be used to load the admin interface into your browser.  In the more general case when you want to access the admin interface from anywhere on your local wired and wireless interface, then the "*" needs to be replaced by a string of 4 numbers representing what is called a IPv4 address (w.x.y.z) of the device you have installed MX on.

Look at your hub or router (this should have come with instructions on how to access its settings in your browser) and on one screen it should show what devices are connected to your LAN and wifi. Look for the IPv4 address, for example 192.168.1.64, it has assigned to the device where MX is running. That is what should replace the "*".  However, there is one more complication, either the Windows networking settings may change, or else your hub or router may reconfigure, both can happen at any time and both can assign a different IPv4 address to the device running MX.


==== Setting up for either manual or automatic running ====


To run Cumulus MX, Windows needs to know
#which '''.exe''' you want to run
#the path where all the required '''.dll''' files are located

Therefore it is best to always start MX using what Windows calls a '''shortcut''', because when creating the shortcut you can enter all the required information into the properties.  If you want MX to automatically start whenever you log into your PC, then the place to store your shortcut is <tt>C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Run_CumulusMX</tt>.  Don't forget to put your Microsoft username where I have put ...

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.

There are 3 ways on Windows to create a shortcut to run MX, as mentioned above you can't just click on the executable in file manager, because Windows needs to be told the path for loading all the related .dll files.


#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). More information on admin interface [[MX Administrative Interface|in separate article]].

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.

= Cumulus flavours =

This is a new section added, just to put the whole Cumulus software project into a full historical context.

==Cumulus 1 ==

*Cumulus 1 was created in 2003 when Steve Loft moved to Wanlockhead and bought himself a weather station. Initial releases were very much tailored to his needs, and instead of supporting a variety of Weather Station makes, it supported just one. The actual make supported varied during some original builds so it would match the make he was using.
*Subsequently, he made his software available to anybody, making it compatible with every make of weather station that was lent to him, and enhanced functionality to suit not only his requirements buy also what other users asked for.
*Cumulus 1 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. This made Cumulus 1 very user friendly in an age when personal desktop computers were the device for everyone to want.
*The functionality of Cumulus grew and grew, there were a few bugs, and a few mistakes, but generally Cumulus software had a high reliability, and grew in popularity.
* Cumulus got a major boost to its popularity when weather station sellers introduced web sites and provided functionality for customers to add their own reviews. Such reviews started to suggest that instead of using the software provided with a weather station, people should try Cumulus software as it would give them more functionality and more flexibility.
*Increased popularity meant an increase in demand for more functionality. Steve Loft had to introduce a register of enhancement requests (he lost it when he moved Sandaysoft to a different hosting provider) to track all the suggestions. It is easy to guess that Steve Loft, who had a full time job and did Cumulus as a hobby, probably had mixed emotions. I'm sure there was pride because people were praising his "baby", but he could not keep up with the growing list of suggestions, and he must have felt at times that all his time outside work was being spent using the developement environment working on a single one of his planned software projects.
*Steve must have really enjoyed the popularity of his software and the interaction with Cumulus Users, because it seemed his responses to posts on the support forum were made almost 24/7/365. (In total Steve made 26,702 posts on the forum, and probably 2/3 of those were responding to users of his software).
*In August 2009, Derek Jamieson, created this Cumulus Wiki, and Steve frequently suggested people should look there for a solution instead of asking him by email or by posting on the forum. However, Cumulus was still growing in popularity, and the posts asking for help on the forum just got more and more numerous.
*The development environment software that Steve was using for Cumulus 1 became more and more expensive to subscribe to, and Cumulus 1 became "donation ware" rather than "freeware".  Although the total value donated was not made public, it is unlikely it covered the costs incurred on the software needed to create the environment in which Cumulus was being written.
*Cumulus 2 (see below) was therefore born, as a replacement for the original Cumulus using one of the new (cheap) development environments for C# that were becoming available. 
*Cumulus 1 development was halted for a while by the focus on Cumulus 2 that would run on multiple operating systems.
*Cumulus 1 development restarted when Cumulus 2 development (see below) was aborted.
*Subsequently the expensive development environment for Cumulus 1 was made obsolete and ceased to be available, so all development of the original Cumulus had to stop.
*The Windows operating systems were changing, Steve was spending less time at his PC, and more time on his tablet, so he needed to start a new flavour of Cumulus (and you can read about Cumulus 3 below).
* The last Chapter for the original Cumulus is that Steve Loft decided not to release source code for Cumulus 1, so nobody else can develop Cumulus 1 any further.
*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.
*Fortunately, Steve Loft documented Cumulus 1 very well in the Cumulus support forum, and by his contributions to this Cumulus Wiki.

== Cumulus 2 ==

This is intentionally a brief section, it does not cover all that was available in Cumulus 2, but just how it influenced MX.

*Steve Loft produced a Cumulus 2 where he tried to start again in September 2009. It was written in C# (which is the language used for MX), and it is fair to say that Steve did not find that new programming language easy, and in March 2010 he was really struggling to make Cumulus 2 work how he desired. 
* Cumulus 2 did prove that a number of concepts (like separating "engine" from "admin interface") could work, and it was a useful learning curve for when Steve decided to write Cumulus 3 (see below).
*One change that had been requested by several Cumulus 1 users was for better international viewing of web pages, with less dependence on time zones. To achieve this, one suggestion was that Cumulus should work in GMT (more widely replaced now by UTC, which is not technically identical with GMT). Cumulus 2 therefore read and logged all readings by UTC. Unfortunately, converting from local time used by weather stations, and most computer devices, never worked as smoothly as Steve Loft hoped, so this is one idea that was not adopted for Cumulus 3.
* Furthermore, Cumulus 2 never succeeded in getting some of the basic functionality like driving web pages to work reliably, so it never offered much of the more useful functionality of Cumulus 1.
*But it was a good testing ground for new functionality and enhancements and regardless of whether they could be made to work fully in Cumulus 2, some were highlighting what Cumulus 1 lacked. 
*In August 2010, the new features being tested in Cumulus 2 were added to Cumulus 1, and Cumulus 2 was discontinued.

== Cumulus 3 ==

*Steve Loft wrote and developed Cumulus 1, 2, and finally MX, while he was in Scotland, he did move a few times, but most development happened on Sanday, hence '''Sandaysoft''' became his name for his creations, he did experiment with some non-weather software, but Cumulus stayed his main hobby.
*In 2015, Cumulus 3 (also initially known as MX, and 'MX' is what was adopted once it was made available to users), was experimental and it had limited functionality, much less than was available in Cumulus 1. This made MX innovative, but unfriendly.
*Consequently, at that time, most Cumulus users were using Cumulus 1, and just those eager to take part in beta testing (perhaps because they wanted to move to Linux operating system) used MX.
*Steve Loft started development of MX while he was still in full-time employment, but as retirement approached he worked fewer days per week.  Consequently, he was faced with the question as to whether to spend his time on MX development, or to focus on spending time with his wife, Beth, exploring places.
*When he fully retired, a life on the road beckoned, and they started travelling. Work on MX decreased, and work on Cumulus 1 was no longer possible, as he was limited to what his laptop and internet connection at stops could cope with.
*Various people offered to help him with MX if he was willing to make his source code available. Initially, Steve was keen to protect his intellectual property.  He did not want anyone else to interfere with his creation.
*When he and his wife found a new home in France, there was no longer any doubt, the priorities changed in favour of a focus on his new life. Having decided to make the source code for MX available (he no longer had the development environment for editing Cumulus 1, and he had aborted Cumulus 2), Steve was able to forget about further development of MX.  Indeed the [[Software|source code]] he released included various feature that were developed prior to the last MX release he made available.
*Steve Loft was closing down his Sandaysoft.com host, so the software source, and release code, had to find a new home, as did this Wiki. SaratogaWX (Ken True) has taken over (see [[CumulusWiki:About|Cumulus  Wiki:   About]], and agreed to also the host source code files as they were at time of handover.  
*Some information was copied from the support forum to the new Wiki host, as at the time of Wiki transfer it was unclear whether the forum would remain available.
*Sandaysoft.com also hosted the support forum. Freddie (Niall Hosiene) took over the hosting of the forum the month after Ken True took over Wiki.
*The various people who had offered to help develop MX now were able to see the source code and decide whether they really did want to get involved.
*One programmer launched Cumulus 4, a new approach. Work continued on this for a while, but as far as I know it never made it into a working system, and I believe like Cumulus 2, it is abandoned.
*Other programmers looked at the source and thought we can make MX useful by adding the missing functionality, both what Steve added in the source but never got into a public release; and the functionality that makes Cumulus 1 so popular but is missing in MX and makes it difficult for those who are using MX.

== The MX future ==

* Mark Crossley was one of those who tried updating the MX source and producing a new release.
* In 2019, he made a successful first new release, and then focussed on adding some of the missing functionality. By 2020, he was not just adding in his own version of features that had been in Cumulus 1, he was also making MX talk to new weather station designs and deal with new sensors. 
* '''During 2020 much extra functionality has been added to MX''', and MX is now able to persuade [[Moving from Cumulus 1 to MX|Cumulus 1 users]] that it might be the right time to make the swap to MX.
*Cumulus 1 was designed to work with weather stations that were available when it was written, the technology used by stations, and the models available, have both been changing 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 MX, sometimes called Cumulus 3, because there was a Cumulus 2 (that was abandoned) and sometime ago there was a start on a Cumulus 4. 
*Similarly, the advice to established Cumulus 1 users is you should now consider a move to MX as you are now missing out on many features available only in MX.


It would be wrong not to repeat what Mark has said 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'''.