MX on Windows OS: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
m (Text replacement - "[[MXDiags" to "[[MXdiags")
(26 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
=Introduction=
=Introduction=


This page is a simple summary for installing and running (non-beta) releases of MX on any computer running the Windows Operating System.  
This page is a simple summary for installing and running (non-beta) releases of MX on any computer running the Microsoft Windows Operating System.


If you are not running MX using the Microsoft Windows Operating System, then please see [[MX on Linux]] page instead.


<div style="background: LemonChiffon;padding:5px; margin:2px;">
There are various related pages to get more information:
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
</div>
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Preprocessor and JavaScript]] page


=Download MX release=
=Already have Cumulus?=


#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
== Report and data files to copy across from any previous Cumulus location ==
#Download the MX distribution from the link that appears there, Mark will update it for each release he makes.
#*It is up to you, where you store the download, but it is a good idea to store it on a separate disc, or partition, if you have a choice.
#* Whether this location is the default, or you are asked to select location will depend on whether your browser's default settings have been changed.
#When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
#*Decide where you want the full distribution to be stored, again you might have somewhere where you backup files.


'''If the latest release has bugs''' (it is impossible for the developer to check all the ways in which versatile MX can be used), you can '''download'', whatever older version of MX you have decided is sufficiently bug-free to install, from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
All the (optional) files in the [[Reports folder]] can be copied across from a previous installation. It should not matter which release created past files, although ideally you need to ensure that the report naming and encoding described on that linked page remain the same.


=Putting distribution where you want to run MX=
<br>


The only rule about where you put the MX files is "avoid the 'Program File' hierarchy".
Whilst you should copy ALL the files in the [[data folder]], from any old installation into the new installation, there are several extra considerations:
* '''Your new MX installation will ignore any entries prior to the MX Start Date'''  when it reads from [[Monthly log files]], such as [[Standard log files]], and [[Extra Sensor Files]]:
**  See [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, edit using ''Station Settings → Common Options → Advanced Options → Records Began date''
* Be aware your new installation has to use the same "locale" as the old installation, or MX will struggle as the locale affects how new lines are stored, and how MX expects old lines to have been stored the same way.
* If your old installation, is on a different operating system to the Microsoft Windows for your new installation, remember that Microsoft Windows uses different line terminators to all other operating systems, although MX should cope with mixed line terminators, any third party routines reading your data files will probably not accept a line terminator change.
* If your previous Cumulus installation was of the legacy software, version 1.9.4, or earlier, then you need to do a lot of reading:
** [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
** [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
** [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date


Best practice is to place MX files in the root directory of any disc or partition where you have frequent updating.
==Configuration Files to copy across from any previous Cumulus installation==


MX uses a number of different computer languages and multiple components. It is best to keep the path short, to remove any possibility of path name being truncated as it is passed between components.
There are two configuration files that are not included in any MX release:
*[[strings.ini]] (Windows is case insensitive, so your file might have capitals) – optional file to customise output
*[[Cumulus.ini]] (Windows is case insensitive,so your file might be all lower case) – main configuration file


=Are you going to use the optional feature in MX to upload to a web server?=
Just copy the existing files from old to new installation, if
# Your locale (Language settings in the Settings app, Regional Settings in the Windows Control Panel, even on Windows 10) is still the same
# All files on your new install are in same paths as on your old install (some settings involve specifying paths)
# Your old installation has a relatively recent MX release (compare the "y" in 3.y.z,between old and new installation,  a difference of more than 1 means you do not have a recent release)
# Your old installation was on computer running Microsoft Windows Operating System,  (not a Linux computer)


As this is an optional feature, the tasks here are optional.


== To set up your web server for the first time ==
If you are upgrading from an older release, please read the table for advice.


{| class="wikitable"
|-
! scope="col" style="width:450px; color:blue" | Cumulus.ini !! scope="col" style="width:450px; color:navy" | strings.ini
|-
| Your old installation will have this file. In general, ''if your old installation was any release before 3.8.0'', the advice is give  the old file a different name when you copy it across to the new installation, and let MX create the file as you work through all the settings.
| '''This is an optional file'''.  Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.
|-
| When you work through the Settings pages, MX will create this file if it does not exist.
* If your old installation was of the legacy software then do consult [[Migrating from Cumulus 1 to MX]]
* As MX evolves, the former "read-only" settings in this file are becoming "advanced" settings in the interface.
| You create a “strings.ini” file by '''selecting some of the parameter'''s from the [[Samplestring.ini]] file that is included in each MX release, and ''modifying the value for the listed attributes'' as you type just those you selected (under the same group titles - these are enclosed in [ ] as before).


<div style="background: LemonChiffon;padding:5px; margin:2px;">
The sections that appear in '''samplestring.ini''', and the parameters that appear within a section, depend upon which release you are using.  So be cautious if you try to reuse a "strings.ini" file originally created by the legacy software, you may find you need to specify your customisation using different parameters in the latest "samplestring.ini".
[[File:Crystal Clear info.png|40px]] This document was written for a MX release that is no longer latest!
|-
|  The content of "Cumulus.ini" is changing as MX is developed, the [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Release Announcements] normally list any new parameters as they appear in the file, without always mentioning those that have become redundant. The announcements tend to avoid any detail, so you have to guess ''from the attribute'' what values it might take, and generally have no idea of where to make any change.


<big>From release 3.10.1, web template pages (that need to be processed and uploaded) are no longer provided with MX, instead the default web pages are installed once onto your web server and they use the technique mentioned at [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript_Object_Notation (.json) files]], for full details please see [[New_Default_Web_Site_Information]]</big>
To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]


With latest release, you still need to do a one-off of files in '''\CumulusMX\webfiles''' and its sub-folders. However, the files found there have changed.
If your old file contains any [[Cumulus.ini (Cumulus 1)|legacy read-only]] parameters not yet converted into advanced settings, or any [[Cumulus.ini (MX 3.0.0 to 3.7.0)|MX read-only parameters not yet converted into advanced settings]], you may need to manually add such missing parameters back into new file by stopping MX (after finishing all the settings you can configure in the interface), doing an external file edit, and then restarting MX
</div>
| The content of "samplestring.ini" is changing as MX is developed:
* Therefore, your existing “strings.ini” might need to be modified.
* There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.  
* Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is still in the “samplestring.ini” included in the release you have installed.
* You may also find new parameters in “samplestring.ini” that you wish to add to your “strings.ini” file to tailor new functionality to your preferences.
|}


If you previously used an older release of Cumulus, but in this new installation will be using the latest release (latest is what is normally best, unless it has bugs), you may want to read up on all the changes between your old release and the current release, not just changes that affect the configuration file.


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


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.
Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.


#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.
==Packages to install==
#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.


== Operating a web site with uploads from MX engine ==
<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX''':
#* '''CumulusMX.exe''' is written in C#, that has been developed by Mark Crossley, but still contains some code by Steve Loft
#* Download '''CumulusMX zip file’’’ from the link at[[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is also written in C#, created, and developed, by Mark Crossley
#* Download '''Create Missing zip file''' from the link at [[Software#Create_Missing]]
#** This takes you to a github page with a "ReadMe" providing minimal instructions
#*  Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki
#* (it will populate missing fields in [[standard log files]] and/or missing lines in [[dayfile.txt]]).
# '''ExportToMySQL'''
#*  '''ExportToMySQL.exe''' is also written in C# by Mark Crossley
#* Download '''Export To My SQL zip file''' from the link at [[Software#ExportToMySQL]]
#** This takes you to a github page with a "ReadMe" providing minimal instructions
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included within early CumulusMX zip downloads.


=== The standard web pages ===
As at 9 March 2020, another utility, '''CreateRecord''', has been initialised in the Github areas managed by the developer where Cumulus is worked on, although it appears to be just a concept (any code on the developer's computer has not yet been included) on github. This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]].
   


<div style="background: LemonChiffon;padding:5px; margin:2px;">
== Earlier MX releases ==
[[File:Crystal Clear info.png|40px]] This section was written for a MX release that is no longer latest!


<big>From release 3.10.1, web template pages (that need to be processed and uploaded) are no longer provided with MX, instead the default web pages are installed once onto your web server and they use the technique mentioned at [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript_Object_Notation (.json) files]], for full details please see [[New_Default_Web_Site_Information]]</big>
Check if posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX functionality that you intend to use.  


You still need to do a one-off upload of the ''contents'' of the '''webfiles''' folder, but the files included have changed.
Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:
</div>
* Different weather station types (the developer only has a Davis),
* Different computer types (development is mostly on Microsoft Windows),
* Plus a whole host of optional features, and different external upload sites, (typically each of these optional features are only used by a sub-set of Cumulus users).


*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).
Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
**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.


=== Alternative ways to obtain web pages ===
You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities that matches your older MX.


You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].


=== Using your own web pages ===
=Where to store the download zip, and where to extract the files =


*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:
# Most browsers, if you don't change any options, will download to the Current User's folder that is called "Download" (or associated with a link of that name)
*#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.
#* Some people change the default, so they can place all downloads onto a separate partition, or a separate disc, mostly because it helps to keep downloads safe in case your main computer disc fails.
*#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.
# It is good practice to backup your existing MX installation, if you have one, before you install a new MX release over it (as if there is a bug in the new release,people regress back to their old one)
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) 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.
# When download completes, use the mouse (those unable to use the mouse should do the equivalent keyboard action) to click on the download file name, this should ask if you want to extract (unzip) it.
# The only rule about where you put the MX files is "avoid the 'Program File' hierarchy".
#* MX uses a number of different computer languages and multiple components. It is best to keep the path to where you install it short, to remove any possibility of path name being truncated as it is passed between components.
#* Best practice is to place MX files in the root directory of any disc or partition where you can have frequent updating
#* Normally, you will unzip over any existing MX installation, so you retain all files not part of the release distribution


You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.
If you already have MX installed, you should be following the [[Updating MX to new version|Upgrade]] page advice:
* It is not a good idea to skip too many in-between releases
* Read the relevant release announcement at [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST], for all in-between releases just in case particular releases have one-off tasks associated with that release.


= Requirements for running MX on Windows =
= Requirements for running MX on Windows =
Line 114: Line 157:
*an alternative is '''Windows Terminal'''
*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:
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>
:<code>netsh http add urlacl url=http://*:8998/ user=\users</code>
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 so you can use the admin interface.
You only need to do that once. If you do not issue this command, administrative rights are needed every time to access the port so you can use the admin interface.


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.
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 <code>netstat -an | findstr 8998</code> 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.
 
To give your Computer a fixed address for the MX admin interface,
#first find the network card via Network and Sharing Centre (Control Panel),
#then click on Change Adapter Settings,
#then Right click on Ethernet or WiFi Adapter,
#next select Properties
# In the window that opens, right click on Internet Protocol Version 4 (TCP/IP 4),
#Next select properties
# Onn that pop up screen tell the computer to "use the following IP address"
#Fill out the form 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).
 
 
 
==Running MX as a service==
 
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section has not yet been written!
</div>
 
 
You might be able to work it out from reading the Linux equivalent [[MX_on_Linux#Setting_up_as_a_service]].


== Setting up for either manual or automatic running (without service) ==


=How to run MX=


To run Cumulus MX, Windows needs to know
We need to run MX in order for it to generate a web server that will enable us to see the [[MX_Administrative_Interface|admin interface]] where we can change [[Cumulus.ini|settings]], view our weather data, or edit various [[:Category:Cumulus_Files|Cumulus files]] (extreme records or log files).
#which '''.exe''' you want to run (ExportMySQL.exe or CumulusMX.exe)
#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 <code>C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Run_CumulusMX</code>.  Don't forget to put your Microsoft username where I have put ...
There are two ways to run MX:
# either Interactively
# or As Service


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.
It is recommended that you run MX interactively to begin with, as this means you will see any messages it outputs, and can respond to those.  Once you are happy that MX is running smoothly, then run it as a service, as that will run in background, and you don't need to watch for messages.


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.
{| class="wikitable" border="1"
|-
!style="width:30px" | Step
!style="width:600px" | Interactively
!style="width:400px" | As Service
|- style="vertical-align:top;"
! scope="row" |Setting up
| To run Cumulus MX, Windows needs to know
# which '''.exe''' you want to run (ExportToMySQL.exe, CalculateMissing.exe, or CumulusMX.exe)
# 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. 


There are 3 ways on Windows to create a shortcut to run the CumulusMX executable:
#Create a shortcut on your desktop (and/or the taskbar) for the '''CumulusMX.exe''' executable <code>cmd.exe /C start CumulusMX C:\CumulusMX\CumulusMX.exe -debug</code>, 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.
#Create a shortcut on your desktop (and/or the taskbar) for the '''CumulusMX.exe''' executable <code>cmd.exe /C start CumulusMX C:\CumulusMX\CumulusMX.exe -debug</code>, 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.
#*In that shortcut define the path where the executable is located as the path to start in.
#* '''Remember, if you have not done the <code>''netsh http add urlacl url=http://*:8998/ user=\users''</code> command mentioned above, you must run as administrator.'''
#* '''Remember, if you have not done the <code>''netsh http add urlacl url=http://*:8998/ user=\users''</code> 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.
#* 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
#* 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.
#* 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
#* Now you can click the shortcut to start the engine, it will open a Command window or Powershell window or Terminal window (default depends on release of Windows OS, but you can change which is used in Settings)
#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).
#* Please note: '''This window must be left open''', closing it will stop MX.
# 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):
# OR place the shortcut as defined here 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).
#**'''Action''' <code>Start a program</code> from drop-down
#* If you want MX to automatically start whenever you log into your PC, then the place to store your shortcut is <code>C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Run_CumulusMX</code>.  Don't forget to put your Microsoft username where I have put ...
#**'''Program/script''' <code>cmd.exe</code> (this is standard Windows environment to run something)
#* 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.
#**'''Add arguments''' <code>/C start Start_MX \CumulusMX\CumulusMX.exe -debug -port=nnnn</code> (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.
# OR declare a task in the scheduler to start MX;  
#**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),
#* in the '''Actions''' tab fill in fields as follows (the other tabs should be obvious):
#** '''Action''' <code>Start a program</code> from drop-down
#** '''Program/script''' <code>cmd.exe</code> (this is standard Windows environment to run something)
#** '''Add arguments''' <code>/C start Start_MX \CumulusMX\CumulusMX.exe -debug -port=nnnn</code> (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
#** all optional parameters are listed later
#**'''Start in''' <code>\CumulusMX</code> (include a drive specifier if necessary)
#**'''Start in''' <code>\CumulusMX</code> (include a drive specifier if necessary)
|
# '''Navigate to the folder with your MX installation'''.
# '''Install MX service''' (as an administrative user) using <code>CumulusMX.exe - install</code>
# '''MX is now set up as a service'''.
# There are other optional parameters (e.g. -port, -debug, -locale) you can add by editing registry
#* To add parameters to the service when it starts automatically you will have to edit the registry
#*# Right click the Windows button at left hand edge of taskbar (often at bottom of your screen)
#*# Choose '''Run'''
#*# Type '''regedit''' (and press ENTER)
#*# Navigate to '''HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\CumulusMX'''
#*#* Hint, you can expand at any level by clicking the '''>''' in the navigation panel
#*#* Similarly, contract by clicking on '''&or;''' in the navigation panel
#*# Right Click on '''ImagePath'''
#*# Select '''Modify'''
#*# You should see '''"C:\CumulusMX\CumulusMX.exe"'''
#*#* This assumes that you have installed your MX in that system partition path, adjust the '''C:''' if you have installed your MX in another partition, in above and in examples below
#*# Now you can add parameters as per [[#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine]]
#*#* For example modify to ''' "C:\CumulusMX\CumulusMX.exe" -port 9000''' to add port
#*#* For example modify to ''' "C:\CumulusMX\CumulusMX.exe" -debug''' to add full debugging
# The service will stop itself if it detects that the computer is going into standby:
# In your MX release distribution, navigate to '''CumulusMX\MXutils\windows'''.
# Find file '''CreateCmxResumeFromStandbyTask.ps1''' for resuming MX after Microsoft Windows has gone into standby.
#  The script MUST be run with Administrator privileges.
# Type <code>CreateCmxResumeFromStandbyTask</code>, and press '''Enter''', this will create a Scheduled Task.
#* The scheduled task will exist from now on, and will automatically restart the service (on resume from standby/hibernate).
|- style="vertical-align:top;"
! scope="row" | (Re-)Starting MX
|  # First '''start the MX engine''' using your shortcut (created in one of the 3 ways as above), if it has not started when you started your computer
# Next '''start the admin interface''', it does not need to run all the time, but only when you need it , 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]].


=== Each time you want to run Cumulus MX on Windows: ===
Try '''start /min C:\Cumulus\CumulusMX''' to run MX as a minimised package (although in Windows you can change the properties of the shortcut you use to start minimised).
 
#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 ===
Note that you may sometimes want to use one or more of the optional parameters when starting MX.
| There are two ways to start MX service:
* Either, use the Services applet:- services.msc (You can pass parameters using this tool, but they are not saved for future use)
* Or, use the service command line tool:- <code>sc start CumulusMX</code> using Command window or Powershell window or Terminal window (one of these will be offered when you right click the Windows/Start symbol) and type '''exit''' to leave that window.


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.
Note that you may sometimes want to use one or more of the optional parameters when starting MX, as per previous row.
|-
! scope="row"| Checking MX is still running
| Simply look in the Command window or Powershell window or Terminal window you used to start MX and left open.
| You can use <code>sc query CumulusMX</code> at any time to check that the service is running.
|-
! scope="row"| Deleting shortcut/service
| If you have set up your short-cut in the '''Startup''' folder, you need to delete that short-cut (or move it to a sub-folder), to stop MX automatically starting when you restart your computer
| To remove the Cumulus system service:
* Either run <code>CumulusMX.exe - uninstall</code> as an Administrator using Command window or Powershell window or Terminal window (one of these will be offered when you right click the Windows/Start symbol) and type '''exit''' to leave that window.
* Or select '''Services''' from "Start", as an administrator, in the ''services applet'' that loads navigate to the one labelled Cumulus, and delete that.
|- style="vertical-align:top;"
! scope="row"| Stopping MX
| 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 be closed by MX.


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.
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.
Line 196: Line 264:


''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.
''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.
| There are two ways to stop MX service:
* Either, use the Services applet:- services.msc
* Or, use the service command line tool:- <code>sc stop CumulusMX</code>
|}


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


The MX package, at time of typing this, includes two executables:
As seen above, in Microsoft Windows, we leave off the file extension when we want to run one of the Cumulus executables, but we might need to add a parameter (starts with a minus symbol), and that parameter might need to be followed with a value.


== CumulusMX.exe ==
== -install parameter for installing as Windows Service==


Whilst effectively MX is run by a '''CumulusMX.exe''', 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.
Use '''CumulusMX -install''' to install MX as a Windows service.


=== Optional parameters to add to the instruction to run the MX engine ===
By default, MX's Microsoft Windows service is installed to run under the System account.


System does not have permissions for network access, that it turn means that any batch file that MX initiates as an external program will be restricted to actions that a System account can do, that excludes actions that a network access account can do.


== -uninstall parameter for uninstalling the Windows Service==


<div style="background: LemonChiffon;padding:5px; margin:2px;">
Use '''CumulusMX -uninstall''' to uninstall the service that runs MX.
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>


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.
== -Port parameter for changing HTTP Port ==


==== Parameter for changing Port ====
When Cumulus starts, it will display the URL of the user interface.


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:
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>CumulusMX.exe -port 9999</pre>
:<code>CumulusMX -port 9999</code>


==== Parameter for adding debugging ====
== -debug parameter for adding debugging ==


MX has a default level of logging that stores in  the [[MXdiags_folder]] 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.
This is only available for [https://cumulus.hosiene.co.uk/viewtopic.php?p=138839#p138839 release 3.4.4 - Build 3068] onwards. This switches on debug and data logging from the start-up of Cumulus MX by adding a parameter:
:<code>CumulusMX -debug</code>


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.
MX has a default level of logging that stores in the [[MXdiags_folder]] 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.


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).  
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 (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[:Category:Diagnostics]] page for details) or the above command.


<pre>CumulusMX.exe -debug -Logging=1</pre>
== Beta builds of MX ==


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 following two parameters are not available since MX came out of 3.0.0 beta.


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.
=== -wsport parameter for web sockets ===


== [[ExportMySQL.exe]] ==
Beta builds in MX version 3.0.0 had an optional parameter <code>CumulusMX -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.  


Note use of this parameter is now deprecated, as it has been incorporated into '''-port''' parameter described earlier.  The reason is that [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. 


<big>The package described here has been replaced by '''ExportToMySQL.exe''', which is an improved version with slight differences in parameters and functionality.  The new package is documented at [https://github.com/cumulusmx/ExportToMySQL Export To My SQL]</big>
=== -Logging parameter for debugging of data flow between station and MX===


Use '''CumulusMX -Logging=1''' (for the station to MX transfers to have increased debugging logging).


This second exe file (see link in heading) was available in the original MX beta package that Steve Loft developed in April 2015, it remained part of the standard release distribution until March 2021. As noted above, it is no longer part of the MX release distribution and has been replaced by Mark Crossley with a separate package with a slightly more meaningful name.
Note use of this parameter is now deprecated, as it has been incorporated into '''-debug''', see above.


Sadly few people even notice ExportMySQL.exe exists, and if they do, it is unlikely they know how to use it. Hopefully, some people will read this section and find out!
=Access to admin interface=


Obviously, the original executable was updated when Mark Crossley added the Feels Like fields to log files.
The admin interface URL '''http://*:8998/''' needs to have that wildcard "*" replaced by a precise location if we are to access the [[MX_Administrative_Interface|admin interface]] to change [[Cumulus.ini|settings]], view our weather data, or edit various [[Log Files|Cumulus files]] (extreme records or 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 missing part of the URL depends on how your local network is set up.


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:
*If you are accessing the admin interface on the same device as that running MX then the "*" can be replaced by "localhost", i.e. '''http://localhost:8998/''' will be used to load the admin interface into your browser.
*Host
*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.
*Port
*User
*Pass
*Database
*MonthlyTable
*DayfileTable


=== Daily summary log file to database table ===
==How to find out which Internet Protocol address to use==


# Use the feature in the admin interface:
# 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.  
#* Settings menu
# 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 "*".
#* 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 to single database table ===
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.


# Use the feature in the admin interface:
To give your Computer a fixed address for the MX admin interface,  
#* Settings menu
#first find the network card via Network and Sharing Centre (Control Panel),
#* MySQL settings page
#then click on Change Adapter Settings,
#* In '''Monthly log file upload''' section, give your database table a name, or accept default ''Monthly''.
#then Right click on Ethernet or WiFi Adapter,  
#* Click '''Save''' to ensure this setting is updated
#next select Properties
# Now scroll down to '''Create database table (save settings first)'''
# In the window that opens, right click on Internet Protocol Version 4 (TCP/IP 4),
#* Here click '''Create Monthly'''
#Next select properties
#If you want MX to continue adding new rows to this database table, still in the admin interface, still in MySQL settings page:
# Onn that pop up screen tell the computer to "use the following IP address"
#* In the same '''Monthly log file upload''' section, now select '''Enable'''.
#Fill out the form with
# 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.
#* a subnet mask of 255.255.255.0 and
#*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.
#*gateway address between 192.168.1.1 and 192.168.1.254 (depending on the address of your hub/router).
# 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.
=One-off essential settings=


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]
If this is your first time using MX, the release distribution does not contain a [[Cumulus.ini|configuration file]], and you need to [[MX_Administrative_Interface#Changing_Settings| set various settings]] to create this file.


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!
If you are running MX interactively (explained above), you will see [[File:MX first start.PNG]].


For those log files produced by the final version 1.9.4, all columns are populated although feels like is set to 0.0.
So 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. The settings you see may vary, depending on which MX release you have installed, so are not described here. It is best to work through all the settings listed, as although some have defaults, you might want to vary them from default.


=One-off optional uploads=


If you have a web server, then navigate to the [[Webfiles_folder|CumulusMX\webfiles]] sub-folder, and upload everything in that folder onto your web server.


You don't create a folder called webfiles on your web server, but you put the files and sub-folders into position at the root for your weather pages.


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 a very 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 contents of that sub-folder may change when you upgrade MX, so this task might need to be repeated.


== webfiles sub-folder in releases from 3.10.1 onwards ==


I'm not going to list all the files and sub-folders within '''CumulusMX\webfiles''' as the contents may change.
*However, it can be said that you will find some .htm files (basic web pages) in the main folder,
* and some sub-folders for
**  .css files (styling) in \css
** .js files (scripts) in \js
**  .png and .jpg files in \images
** two further sub-folders in \lib
**# steelseries
**# jquery (makes scripts independent of browser selection)


== webfiles subfolder in releases 3.0.x to 3.9.y ==


#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.
= Operating a web site with uploads from MX engine =
== The standard web pages ==


=== From release 3.10.1 ===


As mentioned above, the web pages are a one-off upload from '''CumulusMX\webfiles'''.  The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].


Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.


=== Until release 3.9.7 ===


As mentioned above, the styling and library files are a one-off upload from '''CumulusMX\webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.


Please read [[Customised_templates]] for further information about the various pages provided, and how you can customise them to suit you.
=== Comparison with legacy Cumulus 1 web pages ===


* Note that the MX web files are not the same as the ones for Cumulus 1,
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are now the SteelSeries gauges. The default gauges page does 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.


[[Category:Cumulus_MX]]
== Alternative ways to obtain web pages ==
 
You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].
 
== Using your own web pages ==
 
* 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 locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) 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.

Revision as of 18:15, 27 August 2021

Crystal Clear info.png This document is 'Work In Progress' so content may not be complete.

Request for help from Wiki Readers

  • Do you understand how MX works?
  • Do you use hardware, or MX functionality, that is not yet documented? Can you begin that documenting?
  • Can you contribute simple text for novice users, examples of what you have done, correction of typing or factual errors, or supply missing details?
  • Will you make this page more useful by bringing content up-to-date as new releases change some information written for older releases?
  • Does any page need a section for novices, so they don't need to read more technical information further down that page?
  • Is there some information on this page, that should be on a separate page? Can you create the new page and move the less relevant information off this page, don't forget this page needs a link to the new page so people who expect to find it here know where it has moved to?

If you plan on contributing to the Wiki, then you will need an account.

  • Please use the Request Account form to apply for an account. Note that the Wiki is currently undergoing restructuring and is largely locked for editing, but please apply for an account if you wish to contribute in the future.
  • You will find help on how to contribute to this wiki at How to Edit.
  • If you need to consult others, please use the Cumulus Wiki suggestions forum.

Please be aware that information on this page may be incorrect.

Cumulus Version MX Specific

Introduction

This page is a simple summary for installing and running (non-beta) releases of MX on any computer running the Microsoft Windows Operating System.

If you are not running MX using the Microsoft Windows Operating System, then please see MX on Linux page instead.

There are various related pages to get more information:

Already have Cumulus?

Report and data files to copy across from any previous Cumulus location

All the (optional) files in the Reports folder can be copied across from a previous installation. It should not matter which release created past files, although ideally you need to ensure that the report naming and encoding described on that linked page remain the same.


Whilst you should copy ALL the files in the data folder, from any old installation into the new installation, there are several extra considerations:

  • Your new MX installation will ignore any entries prior to the MX Start Date when it reads from Monthly log files, such as Standard log files, and Extra Sensor Files:
    • See StartDate=xxxxx parameter, edit using Station Settings → Common Options → Advanced Options → Records Began date
  • Be aware your new installation has to use the same "locale" as the old installation, or MX will struggle as the locale affects how new lines are stored, and how MX expects old lines to have been stored the same way.
  • If your old installation, is on a different operating system to the Microsoft Windows for your new installation, remember that Microsoft Windows uses different line terminators to all other operating systems, although MX should cope with mixed line terminators, any third party routines reading your data files will probably not accept a line terminator change.
  • If your previous Cumulus installation was of the legacy software, version 1.9.4, or earlier, then you need to do a lot of reading:
    • Amending dayfile tells you about how MX is far more fussy about the content in dayfile.txt
    • .ini files explains how time-stamps are formatted differently in the extreme tracking files
    • Migrating from Cumulus 1 to MX gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

Configuration Files to copy across from any previous Cumulus installation

There are two configuration files that are not included in any MX release:

  • strings.ini (Windows is case insensitive, so your file might have capitals) – optional file to customise output
  • Cumulus.ini (Windows is case insensitive,so your file might be all lower case) – main configuration file

Just copy the existing files from old to new installation, if

  1. Your locale (Language settings in the Settings app, Regional Settings in the Windows Control Panel, even on Windows 10) is still the same
  2. All files on your new install are in same paths as on your old install (some settings involve specifying paths)
  3. Your old installation has a relatively recent MX release (compare the "y" in 3.y.z,between old and new installation, a difference of more than 1 means you do not have a recent release)
  4. Your old installation was on computer running Microsoft Windows Operating System, (not a Linux computer)


If you are upgrading from an older release, please read the table for advice.

Cumulus.ini strings.ini
Your old installation will have this file. In general, if your old installation was any release before 3.8.0, the advice is give the old file a different name when you copy it across to the new installation, and let MX create the file as you work through all the settings. This is an optional file. Its purpose is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.
When you work through the Settings pages, MX will create this file if it does not exist.
  • If your old installation was of the legacy software then do consult Migrating from Cumulus 1 to MX
  • As MX evolves, the former "read-only" settings in this file are becoming "advanced" settings in the interface.
You create a “strings.ini” file by selecting some of the parameters from the Samplestring.ini file that is included in each MX release, and modifying the value for the listed attributes as you type just those you selected (under the same group titles - these are enclosed in [ ] as before).

The sections that appear in samplestring.ini, and the parameters that appear within a section, depend upon which release you are using. So be cautious if you try to reuse a "strings.ini" file originally created by the legacy software, you may find you need to specify your customisation using different parameters in the latest "samplestring.ini".

The content of "Cumulus.ini" is changing as MX is developed, the Release Announcements normally list any new parameters as they appear in the file, without always mentioning those that have become redundant. The announcements tend to avoid any detail, so you have to guess from the attribute what values it might take, and generally have no idea of where to make any change.

To remove any parameters no longer used in this file, see remove redundant parameters

If your old file contains any legacy read-only parameters not yet converted into advanced settings, or any MX read-only parameters not yet converted into advanced settings, you may need to manually add such missing parameters back into new file by stopping MX (after finishing all the settings you can configure in the interface), doing an external file edit, and then restarting MX

The content of "samplestring.ini" is changing as MX is developed:
  • Therefore, your existing “strings.ini” might need to be modified.
  • There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.
  • Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is still in the “samplestring.ini” included in the release you have installed.
  • You may also find new parameters in “samplestring.ini” that you wish to add to your “strings.ini” file to tailor new functionality to your preferences.

If you previously used an older release of Cumulus, but in this new installation will be using the latest release (latest is what is normally best, unless it has bugs), you may want to read up on all the changes between your old release and the current release, not just changes that affect the configuration file.

Cumulus Software

Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.

Packages to install

We shall install the Cumulus software listed on Software page:

  1. CumulusMX:
  2. Create Missing:
  3. ExportToMySQL
    • ExportToMySQL.exe is also written in C# by Mark Crossley
    • Download Export To My SQL zip file from the link at Software#ExportToMySQL
      • This takes you to a github page with a "ReadMe" providing minimal instructions
    • ExportToMySQL.exe is not (at the time this was written) documented in this Wiki although MX_Administrative_Interface#MySQL_settings does describe a similar utility (written by Steve Loft) that was actually included within early CumulusMX zip downloads.

As at 9 March 2020, another utility, CreateRecord, has been initialised in the Github areas managed by the developer where Cumulus is worked on, although it appears to be just a concept (any code on the developer's computer has not yet been included) on github. This will, if my understanding is correct, read dayfile.txt and use that to update the various extreme record files.

Earlier MX releases

Check if posts in the Cumulus Support Forum tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX functionality that you intend to use.

Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:

  • Different weather station types (the developer only has a Davis),
  • Different computer types (development is mostly on Microsoft Windows),
  • Plus a whole host of optional features, and different external upload sites, (typically each of these optional features are only used by a sub-set of Cumulus users).

Anyway, you can download any earlier build, without the bug, from CumulusMX/releases.

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the Cumulus MX github page, and navigate to the utility of interest, to download an older version of these utilities that matches your older MX.


Where to store the download zip, and where to extract the files

  1. Most browsers, if you don't change any options, will download to the Current User's folder that is called "Download" (or associated with a link of that name)
    • Some people change the default, so they can place all downloads onto a separate partition, or a separate disc, mostly because it helps to keep downloads safe in case your main computer disc fails.
  2. It is good practice to backup your existing MX installation, if you have one, before you install a new MX release over it (as if there is a bug in the new release,people regress back to their old one)
  3. When download completes, use the mouse (those unable to use the mouse should do the equivalent keyboard action) to click on the download file name, this should ask if you want to extract (unzip) it.
  4. The only rule about where you put the MX files is "avoid the 'Program File' hierarchy".
    • MX uses a number of different computer languages and multiple components. It is best to keep the path to where you install it short, to remove any possibility of path name being truncated as it is passed between components.
    • Best practice is to place MX files in the root directory of any disc or partition where you can have frequent updating
    • Normally, you will unzip over any existing MX installation, so you retain all files not part of the release distribution

If you already have MX installed, you should be following the Upgrade page advice:

Requirements for running MX on Windows

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

For Windows 10 you use .NET version 5 (or its updates), as installed by your windows update feature. (MX will also run on version 4.8; the .Net download for version 4.8 should be here https://dotnet.microsoft.com/download/dotnet-framework/net48).


.NET

Microsoft originally created .NET for all operating systems, but Microsoft then decided to restrict it to just Windows (and that was the position while MX was being developed, and was still true in early 2020), 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 (although Microsoft still has a leading role).

Later, Microsoft launched an alternative called .NET Core that took out of .NET the parts that were Windows specific, and it ceased work on further development of .NET beyond version 4.x.x.

The most recent change, in November 2020, involved a change around of names, and the multi-operating system .NET Core product took over the .NET name as version 5

Are you using elevated administrative rights?

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

netsh http add urlacl url=http://*:8998/ user=\users

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

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 netstat -an | findstr 8998 into the command window.


How to run MX

We need to run MX in order for it to generate a web server that will enable us to see the admin interface where we can change settings, view our weather data, or edit various Cumulus files (extreme records or log files).

There are two ways to run MX:

  1. either Interactively
  2. or As Service

It is recommended that you run MX interactively to begin with, as this means you will see any messages it outputs, and can respond to those. Once you are happy that MX is running smoothly, then run it as a service, as that will run in background, and you don't need to watch for messages.

Step Interactively As Service
Setting up To run Cumulus MX, Windows needs to know
  1. which .exe you want to run (ExportToMySQL.exe, CalculateMissing.exe, or CumulusMX.exe)
  2. 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.

There are 3 ways on Windows to create a shortcut to run the CumulusMX executable:

  1. Create a shortcut on your desktop (and/or the taskbar) for the CumulusMX.exe executable cmd.exe /C start CumulusMX C:\CumulusMX\CumulusMX.exe -debug, 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 netsh http add urlacl url=http://*:8998/ user=\users 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, it will open a Command window or Powershell window or Terminal window (default depends on release of Windows OS, but you can change which is used in Settings)
    • Please note: This window must be left open, closing it will stop MX.
  2. OR place the shortcut as defined here 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).
    • If you want MX to automatically start whenever you log into your PC, then the place to store your shortcut is C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Run_CumulusMX. 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.
  3. 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 Start a program from drop-down
      • Program/script cmd.exe (this is standard Windows environment to run something)
      • Add arguments /C start Start_MX \CumulusMX\CumulusMX.exe -debug -port=nnnn (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 \CumulusMX (include a drive specifier if necessary)
  1. Navigate to the folder with your MX installation.
  2. Install MX service (as an administrative user) using CumulusMX.exe - install
  3. MX is now set up as a service.
  4. There are other optional parameters (e.g. -port, -debug, -locale) you can add by editing registry
    • To add parameters to the service when it starts automatically you will have to edit the registry
      1. Right click the Windows button at left hand edge of taskbar (often at bottom of your screen)
      2. Choose Run
      3. Type regedit (and press ENTER)
      4. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\CumulusMX
        • Hint, you can expand at any level by clicking the > in the navigation panel
        • Similarly, contract by clicking on in the navigation panel
      5. Right Click on ImagePath
      6. Select Modify
      7. You should see "C:\CumulusMX\CumulusMX.exe"
        • This assumes that you have installed your MX in that system partition path, adjust the C: if you have installed your MX in another partition, in above and in examples below
      8. Now you can add parameters as per #Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine
        • For example modify to "C:\CumulusMX\CumulusMX.exe" -port 9000 to add port
        • For example modify to "C:\CumulusMX\CumulusMX.exe" -debug to add full debugging
  5. The service will stop itself if it detects that the computer is going into standby:
  6. In your MX release distribution, navigate to CumulusMX\MXutils\windows.
  7. Find file CreateCmxResumeFromStandbyTask.ps1 for resuming MX after Microsoft Windows has gone into standby.
  8. The script MUST be run with Administrator privileges.
  9. Type CreateCmxResumeFromStandbyTask, and press Enter, this will create a Scheduled Task.
    • The scheduled task will exist from now on, and will automatically restart the service (on resume from standby/hibernate).
(Re-)Starting MX # First start the MX engine using your shortcut (created in one of the 3 ways as above), if it has not started when you started your computer
  1. Next start the admin interface, it does not need to run all the time, but only when you need it , 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 in separate article.

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

Note that you may sometimes want to use one or more of the optional parameters when starting MX.

There are two ways to start MX service:
  • Either, use the Services applet:- services.msc (You can pass parameters using this tool, but they are not saved for future use)
  • Or, use the service command line tool:- sc start CumulusMX using Command window or Powershell window or Terminal window (one of these will be offered when you right click the Windows/Start symbol) and type exit to leave that window.

Note that you may sometimes want to use one or more of the optional parameters when starting MX, as per previous row.

Checking MX is still running Simply look in the Command window or Powershell window or Terminal window you used to start MX and left open. You can use sc query CumulusMX at any time to check that the service is running.
Deleting shortcut/service If you have set up your short-cut in the Startup folder, you need to delete that short-cut (or move it to a sub-folder), to stop MX automatically starting when you restart your computer To remove the Cumulus system service:
  • Either run CumulusMX.exe - uninstall as an Administrator using Command window or Powershell window or Terminal window (one of these will be offered when you right click the Windows/Start symbol) and type exit to leave that window.
  • Or select Services from "Start", as an administrator, in the services applet that loads navigate to the one labelled Cumulus, and delete that.
Stopping MX 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 be closed by MX.

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.

There are two ways to stop MX service:
  • Either, use the Services applet:- services.msc
  • Or, use the service command line tool:- sc stop CumulusMX

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

As seen above, in Microsoft Windows, we leave off the file extension when we want to run one of the Cumulus executables, but we might need to add a parameter (starts with a minus symbol), and that parameter might need to be followed with a value.

-install parameter for installing as Windows Service

Use CumulusMX -install to install MX as a Windows service.

By default, MX's Microsoft Windows service is installed to run under the System account.

System does not have permissions for network access, that it turn means that any batch file that MX initiates as an external program will be restricted to actions that a System account can do, that excludes actions that a network access account can do.

-uninstall parameter for uninstalling the Windows Service

Use CumulusMX -uninstall to uninstall the service that runs MX.

-Port parameter for changing HTTP 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:

CumulusMX -port 9999

-debug parameter for adding debugging

This is only available for release 3.4.4 - Build 3068 onwards. This switches on debug and data logging from the start-up of Cumulus MX by adding a parameter:

CumulusMX -debug

MX has a default level of logging that stores in the MXdiags_folder 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 (on recent MX releases this is on Program Settings page of admin interface - please see Category:Diagnostics page for details) or the above command.

Beta builds of MX

The following two parameters are not available since MX came out of 3.0.0 beta.

-wsport parameter for web sockets

Beta builds in MX version 3.0.0 had an optional parameter CumulusMX -wsport nnnn that determined which port (represented by a 4 digit number nnnn) was used for Web Sockets.

Note use of this parameter is now deprecated, as it has been incorporated into -port parameter described earlier. The reason is that Web Sockets in all builds since 3045 use the same port for web sockets as for the HTTP port of the Admin Interface.

-Logging parameter for debugging of data flow between station and MX

Use CumulusMX -Logging=1 (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated, as it has been incorporated into -debug, see above.

Access to admin interface

The admin interface URL http://*:8998/ needs to have that wildcard "*" replaced by a precise location if we are to access the admin interface to change settings, view our weather data, or edit various Cumulus files (extreme records or log files).

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

How to find out which Internet Protocol address to use

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

To give your Computer a fixed address for the MX admin interface,

  1. first find the network card via Network and Sharing Centre (Control Panel),
  2. then click on Change Adapter Settings,
  3. then Right click on Ethernet or WiFi Adapter,
  4. next select Properties
  5. In the window that opens, right click on Internet Protocol Version 4 (TCP/IP 4),
  6. Next select properties
  7. Onn that pop up screen tell the computer to "use the following IP address"
  8. Fill out the form 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).

One-off essential settings

If this is your first time using MX, the release distribution does not contain a configuration file, and you need to set various settings to create this file.

If you are running MX interactively (explained above), you will see MX first start.PNG.

So 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. The settings you see may vary, depending on which MX release you have installed, so are not described here. It is best to work through all the settings listed, as although some have defaults, you might want to vary them from default.

One-off optional uploads

If you have a web server, then navigate to the CumulusMX\webfiles sub-folder, and upload everything in that folder onto your web server.

You don't create a folder called webfiles on your web server, but you put the files and sub-folders into position at the root for your weather pages.

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 a very 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 contents of that sub-folder may change when you upgrade MX, so this task might need to be repeated.

webfiles sub-folder in releases from 3.10.1 onwards

I'm not going to list all the files and sub-folders within CumulusMX\webfiles as the contents may change.

  • However, it can be said that you will find some .htm files (basic web pages) in the main folder,
  • and some sub-folders for
    • .css files (styling) in \css
    • .js files (scripts) in \js
    • .png and .jpg files in \images
    • two further sub-folders in \lib
      1. steelseries
      2. jquery (makes scripts independent of browser selection)

webfiles subfolder in releases 3.0.x to 3.9.y

  1. 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.
  2. 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).
  3. The "lib" sub-folder contains further levels of sub-folders all to be replicated on your web site.
  4. The trends.htm web page also loads some library software from an internet Content Delivery Network (cdn) to invoke the JavaScript based Highstocks library.

Operating a web site with uploads from MX engine

The standard web pages

From release 3.10.1

As mentioned above, the web pages are a one-off upload from CumulusMX\webfiles. The data to be shown on these web pages are uploaded from .json files in the web_folder.

Please read this page for more information about styling options and other details.

Until release 3.9.7

As mentioned above, the styling and library files are a one-off upload from CumulusMX\webfiles. These release use template files, these are processed by MX to add the variable data, and this will create web pages that are uploaded to your web site.

Please read Customised_templates for further information about the various pages provided, and how you can customise them to suit you.

Comparison with legacy Cumulus 1 web pages

  • Note that the MX web files are not the same as the ones for Cumulus 1,
    • so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
  • The standard gauges are now the SteelSeries gauges. The default gauges page does 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.

Alternative ways to obtain web pages

You can choose to use some of the alternative web pages available from third parties and described on User Contributions page.

Using your own web pages

  • 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:
    1. 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 page in this Wiki.
    2. 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.
    3. Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the 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 'require_once 'filename'; syntax) to put those variables into a web page.

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