5,838
edits
MX on Windows OS: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
Introduced table format for interactive/service comparison
(Introduced table format for interactive/service comparison) |
|||
|
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
=Introduction=
This page is a simple summary for installing and running (non-beta) releases of MX on any computer running the Windows Operating System.
=Download MX release=
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.
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.
== Latest MX release ==
# 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]].
# Download the MX distribution from the link that appears there, Mark will update it for each release he makes.
== Earlier MX releases ==
'''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].
=Where to store the download zip =
#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.
=Where to unzip distribution files=
The only rule about where you put the MX files is "avoid the 'Program File' hierarchy".
Best practice is to place MX files in the root directory of any disc or partition where you have frequent updating.
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=
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. Although you might not need them immediently, these utilities may be useful in future.
These should be unzipped so their executables are added to same folder as '''CumulusMX.exe'''.
Instructions for using these executables are on the github page where they are found. Note that for Windows, you don't quote the ".exe" when running them.
= Requirements for running MX on Windows =
*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 <
=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).
There are two ways to run MX:
# either Interactively
# 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.
{| class="wikitable" border="1"
|-
!style="width:30px" | Step
!style="width:600px" | Interactively
!style="width:600px" | As Service
|-
|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 MX:
#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.
#* '''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.
#* 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.
# 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 <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 ...
#* 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.
# 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''' <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
#**'''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>
#* 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 '''∨''' in the navigation panel
#*# Right Click on '''ImagePath'''
#*# Select '''Modify'''
#*# You should see '''"C:\CumulusMX\CumulusMX.exe"'''
#*# 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
# MX is now set up as a service.
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 priveldges.
# 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).
|-
| (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]].
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).
| 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 [optional parameters for start-up here]</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.
|-
| 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.
|-
| 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 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.
|-
| 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.
''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>
|}
=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 [[Log Files|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==
# 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).
=One-off essential settings=
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.
If you are running MX interactively (explained above), you will see [[File: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.
=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=
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.
== 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.
= Optional parameters to add to the instruction to run the MX engine =
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>
== Beta builds of MX ==
=== 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'''.
That parameter is now deprecated as Web Sockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see Port parameter below.
=== Debugging of data flow between station and MX===
Use '''CumulusMX -Logging=1''' (for the station to MX transfers to have increased debugging logging).
Although this is not mentioned in any release announcements, it appears that use of this parameter is now deprecated as it appears that on all recent MX releases this effect is incorporated into the '''-debug''' parameter. Perhaps someone could confirm whether this is true.
== Parameter for changing Port ==
When Cumulus starts, it will display the URL of the user interface.
It runs on port 8998 by default; if this is not suitable for some reason you can over-ride it using the '-port' parameter on the command line, e.g. to use port 9999 instead:
:<code>CumulusMX -port 9999</code>
== 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.
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 [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>CumulusMX -debug</code>
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. 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.
| |||
