5,838
edits
MX on Windows OS: Difference between revisions
m
→How to run MX: typo
m (Minor resequencing of page) |
m (→How to run MX: typo) |
||
| (14 intermediate revisions by the same user not shown) | |||
|
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
The banner above has been included as, at the time of typing this, everything on this Wiki page has been typed by a single contributor, who no longer uses Microsoft Windows to run MX. Cumulus MX is evolving rapidly, and any documentation in any page of this Wiki tends to quickly become outdated. It is therefore essential that at least one other contributor takes over updating this Wiki page.
=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 (e.g. personal computer, notebook computer, laptop computer, Raspberry Pi with Windows instead of Linux, etc.).
If you are not running MX using the Microsoft Windows Operating System, then please
There are various related pages to get more information:
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Preprocessor and JavaScript]] page
= Requirements for running MX on Windows =
MX can be run on most computers with a modern version of the Microsoft operating system, but this Wiki page is trying not to get too technical, so it will focus on just two aspects, the locale and .NET.
==Locale==
Cumulus MX is much more fussy than the legacy Cumulus 1 about items like [[Amending_dayfile#Correcting_date_separator_errors|date separators like hyphen or slash]] and [[:Category:Ini_Files#File_content_differences_between_Cumulus_1_and_MX|decimal separators like comma or point]]. For example, Microsoft computers usually default to USA locale, that specifies date format as month, day of month, year. Cumulus may default to GB format (day of month, month, year) or to ISO 8601 format of "yyyy-MM-ddTHH:mm:ss". Note that as of 2020, there are plans for MX to standardise on slash for date separator,and decimal points, and increasingly MX is using UTC, so check release announcements.
There is also the character set and [[Reports_folder#Encoding| File Encoding]], MX defaults to UTF-8 and it does not use "Byte Order Mark" that Microsoft traditionally has used by default. Microsoft used to actively pursue an approach of being non-standard in everything to keep people from using rival products, so there may be other issues if you have previously used a different computer.
Anyway it is vital that your Microsoft computer is set up correctly, if you have used Cumulus (1 or MX) before and wish to have access to existing data, reports and extreme records. You can choose a locale within the '''Settings''' app (cogwheel icon) on your computer, but you will get on better working through individual settings using ''Control Panel -->> Region''. There you can choose between 24-hour clock, am/pm, or AM/PM, as well as between different date formats, and between different field separators (both decimal commas and field separator set to comma must be avoided!).
Ask in support forum if you need more advice, the evidence in there is that MX on Windows raises lots of queries!
==.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
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).
==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 [[MX_Administrative_Interface|Admin Interface]]. To access that, all users need to be given elevated rights to the port on which the web server runs. By default this is port 8998, so that is used in the example below of the one-off command needed to give all users access to the port. You can use a '''-port=nnnn''' parameter when starting MX to make it use another port, if you use that then the command below needs revising accordingly.
To enter the command, first open a command window as administrator. One way to do this is to right click the windows symbol at the start of the windows task bar. The option to choose there is dependent on some settings which determine what appears when you right click:
*the normal default on Windows 10 is '''Windows PowerShell (admin)''',
*the normal default on earlier versions of Windows is '''Command Prompt (Administrator)'''
*an alternative is '''Windows Terminal'''
Whichever of these you can use, the result is it opens a new window on your monitor with a prompt for typing. In that window type the command:
:<code>netsh http add urlacl url=http://*:8998/ user=\users</code>
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 <code>netstat -an | findstr 8998</code> into the command window.
=Cumulus Software=
Note use of plural in section name above, the following
==Packages to install==
<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,
#* Download '''CumulusMX zip file’’’ from the link at[[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
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]].
== Where to store download ==
There are no firm rules.
* Most browsers, if you don't change any options, will download to a sub-folder that is called "Download" within the Current User's folder (or a location elsewhere that is 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.
* A beginner may find it easier to create a new folder specifically for storing MX download zips, so it is easy to find if your standard download location is used a lot.
* It probably is not sensible for a beginner to store the download zip in a "temp" folder, although that is sometimes suggested for downloads that do not need to be kept.
== Earlier MX releases ==
Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you
=
Please note there are rules governing where you can install MX.
==Have you already got Cumulus MX?==
# It is good practice to backup your existing MX installation, (i.e. make a copy that is placed somewhere else, so it is easy to check what you had before; and if you find a bug in new release, or you make a mistake during the new installation, it is easy to regress to the earlier version)
# Now install the new MX over where the old MX was
#* This makes life simpler, as you know you will retain all files needed that are not included inthe new release
If you already have MX installed, you should be following the [[Updating MX to new version|Upgrade]] page advice:
* 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.
==Where should you install MX if you have not used MX before?==
# 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.
# If there is an option as to whether to preserve folder structure, then select to preserve it, and be aware that this extracts into a folder with a name '''CumulusMX3xyz''' where the digits represented there by "xyz" identifies the build
# You should therefore extract to the download location (see earlier), and then copy, or file transfer all the files in sub-folder of that into appropriate place, following hierarchy in final location
# The final location has a small number of important rules, although there is some flexibility if you have multiple drives.
#* 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, i.e. '''G:\CumulusMX''' (where G is the chosen drive, might be ''C:'' and '''CumulusMX''' is a short informative folder name that matches the top folder under the name '''CumulusMX3xyz''' in the release download after extraction from zip.
#* There is one place, where you must not store MX, and that is "avoid the 'Program File' hierarchy".
#*# Let me explain that:
#*# Microsoft tell developers to put code in '''C:\Program Files''' or ''c:\Program Files (x86)'' as these are read only folders except when software is being installed, and Microsoft tells developers to put data files for that software in '''c:\ProgramData'''
#*# Cumulus MX has not been developed in accordance with those Microsoft specific rules
#*# Consequently, if you did wrongly install MX in the above hierarchy, the read-only rule would mean that Microsoft stores any files that MX updates in another place and MX would not find them, here are two examples:
#*#* When you use the Settings pages in MX, instead of creating/updating a [[Cumulus.ini]] file in the same folder as "CumulusMX.exe", Microsoft would create/update the file in ''C:\Users\user_name\AppData\Local\VirtualStore\Program Files\CumulusMX\Cumulus.ini''
#*#* As MX runs, instead of creating files in say the [[Data folder|data sub-folder]], Microsoft redirects any file changes, after the software installation, into ''C:\Users\user_name\AppData\Local\VirtualStore\Program Files\CumulusMX\data'' (and similar redirection for other sub-folders)
#*# The problem then is that your Microsoft Windows computer now has two "data" (and other) sub-folders, but MX cannot know which sub-folder to look in, (as any file not updated is in installation sub-folder, while any file that has been updated is in the redirection sub-folder).
=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 [[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).
If this is your first run of MX, please see [[First_Run_of_MX|First Run of MX page]].
There are two ways to run MX:
!style="width:30px" | Step
!style="width:600px" | Interactively
!style="width:
|- 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)
#*# 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
# 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
# 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]].
* 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.
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.
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==
== -debug parameter for adding debugging ==
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>
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 <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]].
=== -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 [[MX_Administrative_Interface|admin interface]] to change [[Cumulus.ini|settings]], view our weather data, or edit various [[
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.
** (Note "localhost" will work even if you host your own database server or own web server, each of these uses a different port number to ensure the correct server is loaded)
*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.
# 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.
=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 MX release created past files, although ideally you need to ensure that the report naming and encoding described on that linked page remain the same. If you previously used the legacy Cumulus 1, on the same computer, the same requirement for settings compatibility applies. If however you previously used the legacy Cumulus 1 on a different computer, then you may have some difficulty in accessing the old files because of differences in the default settings, please see [[Migrating from Cumulus 1 to MX]] page and read about why it is often more complex.
<br>
Whilst you should copy ''nearly'' ALL the files in the [[data folder]], from any old installation into the new installation, there are several extra considerations:
* MX cannot understand the Cumulus 1 [[Log.xml|log file]] (aka [[Weather Diary]]), so there is no point in copying that from the legacy Cumulus to a MX folder
* 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
* When copying [[Standard log files|MMMYYlog.txt]] files and [[Extra Sensor Files|ExtraLogyyyymm.txt]] files, be aware that '''your new MX installation will ignore any entries prior to the MX Start Date''' when it reads those files:
** See [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, edit using ''Station Settings → Common Options → Advanced Options → Records Began date''
* Some releases of MX are very fussy, some are less fussy, about all lines in all [[:Category:Files_with_Comma_Separated_Values]] being totally consistent in all "locale" settings.
* If your old MX 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.
==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]] – optional file to customise output (MX content significantly different to legacy Cumulus content)
*[[Cumulus.ini]] – main configuration file (Substantial changes to content at release 3.12.0, some changes at other releases)
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 (use that not "Settings" even on Windows 10/11) 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)
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).
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 [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.
To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]
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
| 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.
= Operating a web site with uploads from MX engine =
| |||