MX on Windows OS: Difference between revisions

MX on Windows OS (view source)

Revision as of 12:09, 25 July 2021

3,990 bytes added , 12:09, 25 July 2021

m

Making more consistent with "MX on Linux" for easier future maintenance

Sfws

5,838

edits

@@ Line 13: / Line 13: @@
 *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 Pre-processor and JavaScript]] page
+*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Preprocessor and JavaScript]] page
+=Already have Cumulus?=
-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 mentioned in section after next.
+== Report and data files to copy across from any previous Cumulus location ==
-==Migrating from Cumulus 1==
+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.
+All the files in the [[data folder]] can also be copied across, but 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. Microsoft Windows uses different line terminators to other operating systems, although MX should cope, any third party routines reading your data files will probably not accept a line terminator change.
-If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], before you follow the instructions on this page.
+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
-Please note that migration from Cumulus 1 gets harder and harder as MX is developed and diverges more and more from the original software.  Therefore, it is strongly recommended that you transfer to an old MX release and then upgrade to a newer MX release as described below.
+==Configuration Files to copy across from any previous Cumulus installation==
-In particular you need to understand configuration differences, so that is covered next.
+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
-==Cumulus.ini==
+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)
-If you are moving from the legacy software to a MX release of 3.8.0 or later, many people prefer to not migrate their existing “Cumulus.ini” file.  Instead, they work through all the settings manually on the new install, so that MX can create a fresh file, with them having confidence every setting reflects their preference.
-There were significant changes to “Cumulus.ini” when moving from 1.9.4 to 3.0.0, see [[Cumulus_3_(MX)_beta_documentation]] and [[Migrating_from_Cumulus_1_to_MX]] pages. As described [[Updating_MX_to_new_version|on upgrading advice page]] in this Wiki, moving from 1.9.4 to MX is best done gradually upgrading through releases, as a number of Cumulus files (e.g. [[Amending_dayfile#Date_Separator_in_MX|dayfile.txt]]), and any database tables you are using, may also need adjusting as you progress up through releases, and that is best done at correct in-between releases (see individual MX release announcements in support forum). Documentation for the 1.9.4 '''cumulus.ini''' file can be found [[Cumulus.ini_(Cumulus_1)|here]] should you need to work on your old legacy file.
+If you are upgrading from an older release, please read the table for advice.
-There were gradual changes to “Cumulus.ini” as releases went from 3.0.0 to 3.7.0, documentation can be found [[Cumulus.ini (MX_3.0.0_to_3.7.0)| here]] where, hopefully, the changes are made clear. ''Within that range of releases, you should continue to use any existing '''Cumulus.ini''' file, as you might lose vital "read-only" parameters by starting a new file.'' As mentioned before, the [[Updating_MX_to_new_version|upgrading advice page]] is the best place to seek advice on which releases to upgrade to which, rather than attempting to directly upgrade to latest release.
+{| 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 documentation for various later MX releases (covering just 3.8.0 to 3.12.0 at the time this paragraph was last updated) can be found at [[Cumulus.ini]]. ''If you previously used Cumulus 1.x.y, or a release before 3.8.0, please note that there have been '''major changes''' to the parameters included in the file. You must proceed with caution if you want to use a file created by an older release as it will lack loads of new parameters that are now mandatory in MX''. However, [[Cumulus.ini|the configuration file page]] does include advice on (while MX is running) you can automatically update, either an existing file, or to create a new file, that approach will add all the new parameters (although some will not receive valid values, and others might default away from your preferences).
+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.
-=Download MX release=
+To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]
-Decide whether you want latest release, by looking in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 support forum] to see if any bugs are reported with it.
+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.
+|}
-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], because that may describe one-off tasks associated with that release.
+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.
-== Latest MX release ==
+=Cumulus Software=
-# To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software page and navigate to the Current_Release section]].
+Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.
-# Download the MX distribution from the link that appears there, Mark will update it for each release he makes.
-== Earlier MX releases ==
+==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, 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.
-'''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].
+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 the download zip =
+== Earlier MX releases ==
-#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.
+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.
-#* 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 (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.
-#*Decide where you want the full distribution to be stored, again you might have somewhere where you backup files.
-=Where to unzip distribution files=
+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).
-The only rule about where you put the MX files is "avoid the 'Program File' hierarchy".
+Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
-Best practice is to place MX files in the root directory of any disc or partition where you can have frequent updating.
+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.
-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.
-=Other executables=
+=Where to store the download zip, and where to extract the files =
-As well as ''CumulusMX.exe'', you will find [[Software#Create_Missing|'''CreateMissing.exe''']] and [[Software#ExportToMySQL|'''ExportToMySQL.exe''']] zips to download from the ''Software'' page.  These should be unzipped so their executables are added to same folder as '''CumulusMX.exe'''.  Both have been written in C# by Mark Crossley to work with MX. You need to ensure that you use the right version of these utilities for the MX release you are running, so if you are using an old MX release, you might 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.
+# 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.
+# 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)
+# 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
-Although you might not need them immediately, these utilities may be useful in future.  Simple Instructions for using these executables are on the github page where they are found, again links exist on '''Software''' page in this Wiki. Note that for Windows, you don't quote the ".exe" when  running them.
+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
-Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.
+* 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.
-'''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 in early MX release downloads.
 = Requirements for running MX on Windows =
@@ Line 111: / Line 157: @@
 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.
@@ Line 117: / Line 162: @@
 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).
 There are two ways to run MX:
@@ Line 124: / Line 168: @@
 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.
 {| class="wikitable" border="1"
@@ Line 233: / Line 274: @@
 # 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.
@@ Line 248: / Line 288: @@
 #* 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=
@@ Line 257: / Line 296: @@
 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.
-=Upgrade to a new MX release=
-If at any time, you need to upgrade to a newer release of MX, it is basically a case of installing the new release over the existing one, but more guidance at [[Updating MX to new version|upgrade]] MX.
 =One-off optional uploads=
@@ Line 271: / Line 306: @@
 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 ==