MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

MX on Linux (view source)

Revision as of 21:15, 23 July 2021

8,729 bytes added ,  21:15, 23 July 2021
m
→‎Add the Mono repository for a Raspberry Pi: corrected link display
(25 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}


'''This page focuses on aspects of MX that are specific to the Linux operating systems.’’’
'''This page focuses on aspects of MX that are specific to the Linux operating systems.'''


If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.
If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.
{{TOCright}}
=Page Content=
This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables
There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*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 were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page


=Using MX on UNIX-derived Operating Systems=
=Using MX on UNIX-derived Operating Systems=
Line 15: Line 38:
==Device Coverage==
==Device Coverage==


This page is intended to cover all Linux-based devices, but the content here is based on experience of those who have contributed to this page.  
Linux is available based on a multitude of different kernels (the building block for the operating system), on a multitude of devices.


Linux is available in a multitude of different kernels, on a multitude of devices, but this Wiki page will largely ignore any technical variations (some included at end of page) and focus on giving some background content to support the basics.
It is hoped that contributions to this page will be made by Cumulus users with a range of such devices. The page has been originated by a contributor using the Raspberry Pi Operating System (this is based on Debian, one of the Linux kernels). Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].
 
The Raspberry Pi Operating System is based on Debian, one of the Linux kernels. Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].
 
If you use a different kernel, or feel that this page inadequately covers what you want to know, can you add sub-sections to this page to ensure it covers the Linux device you use?


:Until somebody creates a separate page for Apple Mac computers (that would be a good idea), this page is the closest.
:Until somebody creates a separate page for Apple Mac computers (that would be a good idea), this page is the closest.
Line 32: Line 51:
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.


Microsoft has had a deliberate policy of being different, so it is not UNIX-like. The [[MX_on_Windows_OS|Running Cumulus MX on Microsoft Windows]] page covers those aspects of MX that are specific to Personal Computers running Microsoft's Windows Operating System.  
Microsoft has had a deliberate policy of being different to traditional computers mostly based on UNIX, and the [[MX_on_Windows_OS|Running Cumulus MX on Microsoft Windows]] page covers those aspects of MX that are specific to Personal Computers running Microsoft's Windows Operating System.  


In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.
In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.
=Page Content=
{{TOCright}}
This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables
There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*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 were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page


=For those using Raspberry Pi computers=
=For those using Raspberry Pi computers=
Line 85: Line 81:
Please read on, this page will tell you all you need to know.
Please read on, this page will tell you all you need to know.


= Do you have a Kernel? =
= Do you have a Operating System? =


Is your Linux computer already working? Or does it need a Kernel to be installed?
New hardware might come preloaded with an operating system, or might allow you to choose which operating system to install on it.


Operating system is alternative name for the kernel, this is the software that is loaded onto your computer to provide Linux commands and everything else that males a computer work.
Please see [[Raspberry Pi computer page]] if you want guidance on choosing which model to buy and how to install an operating system on those computers, so you are ready to install MX.


Please see [[Raspberry Pi computer page]] if you want guidance on choosing which model to buy and how to install an operating system, so you are ready to install MX.
=Do you know how to install packages?=


=Ready to install MX?=
If you already know how to install packages, your computer has the pre-installed image, or you have installed MX before, you will want to skip the sub-sections that follow on here, and continue reading at [[#Cumulus packages]].
 
Assuming our Linux computer has a kernel, how do we add packages to our system? We need a short technical digression to explain the command, skip this next section if you already know how to install packages.


Otherwise, here is a short technical digression to explain the commands.


==The various components to commands for installation==
==The various components to commands for installation==
Line 105: Line 100:


===sudo===
===sudo===
By default, a Linux user will log in as a default user with limited rights. For example, on the Raspberry Pi Operating System, there is a single default user, initially called "Pi", with their home folder that can be referenced as "~".


The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.
The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.


You can change the rights in a folder, or for a file, to make this prefix unnecessary outside root access requiring contexts like installation.
If we are working away from the folder(s) owned by the default user, we can consider whether we want to change the ownership of these parts of the file system (how to do this for a MX installation is explained later) so that we can access the files with our default user without using "sudo" for file/folder commands.
 
In some limited cases, it might make sense to just change "read" rights,so that the default user can read a file/folder, but other actions are not possible without using "sudo" prefix. This limits our ability to accidentally delete files that other processes need.


===apt===
===apt===
Line 114: Line 113:
The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   
The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   


There is a longer technical explanation towards the end of this page, all I will say here is that you might see “apt-get” used in some on-line examples. I suggest you replace “apt” where “apt-get” is seen as generally “apt” is more friendly. Equally, “apt” can replace “apt-cache”, which I won’t explain.
If you are looking online for a tutorial on how to install packages, you might see “apt-get” or "apt-cache" used in examples they quote. It should be safe to replace these older package managers with "apt". I have included a little technical explanation at the end of this page if this really worries you.


===install===
===install===
Line 131: Line 130:
|-
|-
|update
|update
|To make sure your computer has up to date information about repositories installed and to report if these contain packages that can be upgraded
| The "source list" [[#The various components to commands for installation|mentioned earlier]] that references the repositories from which software packages can be installed, needs to be updated periodically so it reflects any changes within those repositories. The instruction "update" is included after "apt" to make sure your computer has up to date information about repositories installed, and to report if these contain packages that can be upgraded
|-
|-
|upgrade
|upgrade
|To see which of your packages have newer versions now available in repositories, and to replace those packages with the newer versions
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions
|-
|-
|autoremove
|autoremove
|To check all components in the packages you have installed and remove those components that are not needed by the dependencies of the packages you use.
| The instruction "autoremove" can be included after "apt" to check all components in the packages you have installed onto your computer, and remove any components that are not needed by the dependencies of the packages you are using. A download for software frequently includes some components specifically for their software to work with particular other optional packages.


As an example, when you install mono-complete, there might be components that are never used, and “autoremove” can be used to tidy up when you finish all your installations
When we install mono-complete later, the other packages we install do not need every component that has installed, and “autoremove” can be used to tidy up when all our installations are finished.
|-
|-
|remove
|remove
|If you want to remove just one component manually, use “remove” followed by the name of component you no longer want
|If you want to remove just one component manually, after "apt", use “remove” followed by the name of component you no longer want
|-
|-
|purge
|purge
|To remove any installed package and delete all related configuration files
| To remove any installed package and delete all related configuration files, after "apt" type "purge" then the name of the package we no longer want
|-
|-
|search
|search
Line 158: Line 157:
The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.
The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.


After the “install” part mentioned above, we can add “-y” to signify that we want the install to continue.  Without this flag, the package manager will ask periodically if we want it to continue,  and we have to then respond with a “y” each time.  For example, when we ask to install a package, "apt" will do a search, it will list what components it has found, and output how big their demands are on storage, without "-y" flag, it will then ask if it is okay to continue to installing.
If we selected "install" or "upgrade" to follow "apt", we can add a “-y” flag to signify that we want the install to continue.  Without this flag, the package manager will ask periodically if we want it to continue,  and we have to then respond with a “y” each time.  For example, when we ask to install a package, "apt" will do a search, it will list what components it has found, and output how big their demands are on storage, without "-y" flag, it will then ask (at least once) if it is okay to continue to installing.


=== Name ===
=== Name ===


The final part of the installation command is the name of the package or component that we want to install.
The final part of the package command is the name of the package or component that we want to install/upgrade/purge/show/remove or search for.
 
=Install starts here=
 
If your computer has the pre-installed image, or you have installed MX before, you can skip the sub-sections that follow on here and continue reading at [[#Cumulus packages]].


== Preparing for an install==
== Preparing for an install==


Before we do an install of a new package, we typically use some of these commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
Before we do an install of a new package, we typically use this series of commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
<code>
sudo apt update
sudo apt update
Line 172: Line 175:
sudo apt autoremove
sudo apt autoremove
</code>
</code>
Each of those can be understood from information in previous section.
If you are installing onto a Pi zero, or similar slow computer, please ensure the size of the swapfile is as big as possible, as the mono-complete we will install is large. In linux, we type <code>free -m</code> to see our RAM size and our swapfile size.
To change swapfile size on the Raspberry Pi, you need to edit a file <code>sudo nano /etc/dphys-swapfile</code>.  Move the cursor down line by line until it reaches '''CONF_SWAPSIZE=100'''.  That is showing that the swapfile is only 99 mb by default in the Raspberry Pi Operating System. Now move the cursor to the 100, and change it to "512" which is enough for mono even on a Pi zero. Next, stop, and restart the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>. That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.
=== USB HID ===


Each of these can be understood from information in previous section.
There is one more prerequisite package for MX with some weather station types.


= Which software packages will we install?=
The cross-platform [https://www.nuget.org/packages/HidSharp/ Universal Serial Bus (USB) Human Interface Device (HID) library] used by MX to connect to weather stations that appear as a HID connecting via USB (like Fine Offset and USB connected Oregon Scientific models) calls a package file called ''libudev.so.1'', so you may need to [[#install|search]] your Linux computer for this file, and [[#install]] it if it is missing. Alternatively, you might just need a symbolic link where MX looks to where the file is.


If you read all the previous section, it explained Linux has a ‘’’source list’’’ of ‘’’repositories’’’ from which it can load software packages.
To check your USB devices, type <code>sudo lsusb -t</code).


# Our first task will be to install the appropriate mono repository, if that is not already in our source list
To check HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.
# Our second task will install a package called ‘’’mono-complete’’’ from the repository we just installed, (this is needed to run software written in the C# languages)


Optionally read about [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=14310&p=111593&hilit=libudev.so.1#p111593 Oregon Scientific] issues.
To read about [https://cumulus.hosiene.co.uk/viewtopic.php?p=107913#p107913 Fine Offset issues and the (file may need to be linked to where MX wants it) file link instructions]


==Changing the Source List==
==Changing the Source List==


If you type <code>sudo apt search mono-complete</code>, you will find out whether the package is available from one of the repositories already in our source list.  Each of the parts of that command was explained earlier.
The "source list" [[#The various components to commands for installation|mentioned earlier]] may not contain all the repositories we need for our installations.


If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which kernel we have, so choose the right sub-section below.
Consequently, type <code>sudo apt search mono-complete</code>, to find out whether the mono package is available from one of the repositories already in our source list, and if the version available is compatible with MX (Release announcements for MX should specify which versions of Mono will work).  Each of the parts of that command was explained earlier.
 
If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which Linux kernel is used by our Operating System.
 
There are a number of sub-sections below, please check which applies to you, and only read that one.


===Add the Mono repository for a Raspberry Pi===
===Add the Mono repository for a Raspberry Pi===


The two Mono repositories listed here are specific to the 2017 and 2019 releases (respectively) of the operating system for a Raspberry Pi computer.  These are taken from  [https://www.mono-project.com/download/stable/#download-lin-raspbian].
The two Mono repositories listed here are specific to the 2017 and 2019 releases (respectively) of the operating system for a Raspberry Pi computer.  These are taken from  [https://www.mono-project.com/download/stable/#download-lin-raspbian download-lin-raspbian].


# the first line (in each case) installs a certificate
# the first line (in each case) installs a certificate
# the echo line defines a repository to add to the sources list.
# the echo line defines a repository to add to the sources list.


{| class="wikitable" border="1"
{| class="wikitable" border="0"
|-
!style="width:450px" | Raspberry Operating System 9 (stretch)
!style="width:450px" | Raspberry Operating System 10 (buster)
|-
| sudo apt install apt-transport-https dirmngr gnupg ca-certificates<
| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
|-
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
|-
!style="width:300px" | Raspberry Operating System 9 (stretch)
| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</nowiki>
!style="width:300px" | Raspberry Operating System 10 (buster)
| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</nowiki>
|-
|-
|<code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates
| sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
| sudo tee /etc/apt/sources.list.d/mono-official-stable.list
echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
</code
|
<code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
</code>
|}
|}


==Add the Mono repository to Ubuntu, Debian, Fedora==
===Add the Mono repository to Ubuntu, Debian, Fedora===


At time of writing, [https://www.mono-project.com/download/stable/#download-lin-ubuntu], shows the instructions for versions 16, 18, and 20 of Ubuntu.
At time of writing, [https://www.mono-project.com/download/stable/#download-lin-ubuntu download-lin-ubuntu], shows the instructions for versions 16, 18, and 20 of Ubuntu.


Equally, [https://www.mono-project.com/download/stable/#download-lin-debian], gives details for debian, and [https://www.mono-project.com/download/stable/#download-lin-fedora] for Fedora.
Equally, [https://www.mono-project.com/download/stable/#download-lin-debian download-lin-debian], gives details for debian, and [https://www.mono-project.com/download/stable/#download-lin-fedora] for Fedora.


Others can be found by choosing other tabs on any of those links.
Others can be found by choosing other tabs on any of those links.
Line 237: Line 255:
=Cumulus packages=
=Cumulus packages=


Note use of plural in section name above, the following sub-sections will install MX and the other packages already mentioned, all by Developer Mark Crossley.
Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley. If you are using the [[Software#Cumulus_MX|pre-built disc image]], then (unless the MX release version included in your image is an old one) you should skip the instructions for "CumulusMX".
 
==Handling zip files==


  Our next task is to install the Cumulus software listed on [[Software]] page:
Each release is presented as a zip.
# '''CumulusMX’’’, this is written in C# and we download it from [[Software#Latest_build_distribution_download]]
 
# [[Software#Create_Missing|'''CreateMissing.exe''']], another C# package (it will populate missing fields or missing lines in log files), Simple Instructions for using this executable is on the github page where they are found, again linked from '''Software''' page in this Wiki.
The download and unzip procedure is exactly same on your Linux computer, and on a Windows PC. So if you have two devices available, you can download on either device, and if it is not the computer you want to install on, you can use a file transfer package to move the files between devices, or use a drive (or even a memory card) with a partition formatted so that you can read it on both devices.  Windows and Linux partitions are formatted in different ways. While it is likely that Linux can read a Microsoft formatted partition, Microsoft Windows can never read a Linux formatted partition.
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.
 
# Finally, install ‘’’Export (old data) To a Maria (or other MySQL) database server’’’ package downloaded from [[Software#ExportToMySQL]]
When your browser saves the zip it might be into a folder called “downloads” on your computer, or you may be able to save into another folder that you prefer (perhaps on a different partition). Your browser might even remember the folder you used before for files of type zip.
#* '''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.
 
When the download has completed, whatever computer type this is on, mouse click (it might need a right click or a double click depending on settings) on the download file and it should unzip (it may create a folder whose name is taken from the zip file name in the same folder by default, or it may ask you where you want to unzip to).  If you are unable to use a mouse, there should be a keyboard code to use. If you are using a file manager, with a graphical interface, there may be a different way to select the file and unzip it.




==Where to install all packages?==
==Where to install all packages?==


*For simplicity on this page EXISTING PATH is used to represent any location in the Linux file structure where you decide to install Cumulus:
For simplicity on this page EXISTING PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.  
**Some people install it into ‘’’/home/pi/’’’, the default folder for the default user (Pi), because then the default user has full permissions automatically
**Mark suggests you install into ‘’’/opt/’’’ which is where other additional software is often installed
* All the Cumulus packages, should be put into a sub-folder called “CumulusMX” (note where capital letters must be used).
** You can create that folder as you unzip a MX release, or you can type <code>sudo mkdir EXISTING PATH/CumulusMX</code> first (note that EXISTING PATH is explained above and always starts with a slash “/”).
** It is best to change permissions for the "CumulusMX" sub-folder, <code>chmod ugo+rwx CumulusMX</code> will give full rights to the folder, so that "sudo" is not needed to run an executable there, and you can read/update any file in the folder regardless of which user you have logged in.
*Many with a Raspberry Pi add an external drive to reduce wear on the internal micro-SD card, and so if they have to reload the kernel  (sometimes called “operating system”), they don’t lose their Cumulus packages and data.
**This is more complicated in that you might have to create linux partitions on this disc, then mount these partitions, and this page is not the place to get too technical


The phrase “EXISTING PATH”  is used, because it is most likely you want to create the sub-folder called “/CumulusMX” (note where capital letters must be used) in a part of the Linux file structure that already exists.


==Alternative download link for older MX releases==
It is important to minimise the length of the path name, because this path name has to be passed between various different software languages (and longer paths risk truncation).


For completeness, you may have discovered (from posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] that the current release of MX has a bug that affects an aspect of MX 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, different computer types, plus a whole host of features, and different external upload sites, that are only used by a sub-set of people).
* You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir EXISTING PATH/CumulusMX</code> first (note that EXISTING PATH is explained above and always starts with a slash “/”).
* By using the phrase EXISTING PATH this advice avoids telling you to install Cumulus where you do not want it:
*# Many people with a Raspberry Pi, and a little technical understanding, add an external drive to reduce wear on the internal micro-SD card, and keep their Cumulus files away from the drive that holds the operating system.
*#* This page is not going to get technical by telling you how to create, or mount, Linux partitions on your external drive. If your drive was bought from a Raspberry Pi reseller, they might help you.  
*# Other people using a Raspberry Pi without that technical expertise, might use ‘’’/home/pi’’’ for EXISTING PATH as that is the default folder for the default user (Pi) and can be referenced as "~" in file path instructions they issue (although Cumulus will not understand that shorthand)
*#* Within that ‘’’/home/pi’’’ folder, the default user has full permissions automatically.
*# The developer suggests you use ‘’’/opt’’’ for EXISTING PATH (which should be available on any Linux computer). 
*#* By default, the code Mark provides for installing Cumulus as a service, will run that service as a root user, and the root user has full permissions in /opt (and everywhere else)
*#* If you do choose a EXISTING PATH outside your home folder, you might want to change the ownership of the "CumulusMX" sub-folder, to the default user (Pi), if so, type <code>sudo chown -R pi: EXISTING PATH/CumulusMX</code>.  The advantages of that command is you no longer need "sudo" to access the files (however, if you are running MX as a service, you also need to edit the user in the script provided to create the service, so MX does not create files with root ownership - this will be covered later)


In such a case, download any earlier build, without the bug, from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
==Packages to install==


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.
<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX’’’:
#* '''CumulusMX.exe’’’ is written in C#
#* Download '''CumulusMX zip file’’’ from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is another C# package
#*  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]]), 
#* Simple Instructions for using this executable are on the github page where they are found, you can find the link for that at [[Software#Create_Missing]] in this Wiki.
# '''ExportToMySQL'''
#*  '''ExportToMySQL.exe''' is also written in C#
#* Download '''ExportToMySQL.exe''' package from [[Software#ExportToMySQL]]
#* '''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.


==Handling zip files==
As at 9 March 2020, there is another utility, '''CreateRecord''', initialised in the Github areas managed by the developer where Cumulus is worked on.  This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]].  However, at the time of writing this, it is nothing more than a concept that needs to be coded, and (as far as I know) there has been no progress on that utility for at least 4 months.
 
===Alternative download link for older MX releases===
 
Skip this sub-section if either you have installed the "pre-built disc image", or the current MX release is stable (it has been available for a while and nobody has reported any bugs).
 
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 that you intend to use.


Each release is presented as a zip.
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 download and unzip procedure is exactly same on your Linux computer, as it would be on a Windows PC.  So if you have two devices available, you can download on either device, and if it is not the computer you want to install on, you can use a file transfer package to move the files between devices, or use a drive (or even a memory card) with a partition formatted so that you can read it on both devices. Windows and Linux partitions are formatted in different ways. While it is likely that Linux can read a Microsoft formatted partition, Microsoft Windows can never read a Linux formatted partition.
Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].


When your browser saves the zip it might be into a folder called “downloads” on your computer, or you may be able to save into another folder that you prefer (perhaps on a different partition). Your browser might even remember the folder you used before for files of type zip.
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.


When the download has completed, whatever computer type this is on, mouse click (it might need a right click or a double click depending on settings) on the download file and it should unzip (it may create a folder whose name is taken from the zip file name in the same folder by default, or it may ask you where you want to unzip to).  If you are unable to use a mouse, there should be a keyboard code to use. If you are using a file manager, with a graphical interface, there may be a different way to select the file and unzip it.
==Upgrading a Cumulus package==


==Where to install MX==
Upgrading to a new MX release is explained [[Updating_MX_to_new_version|here]], but basically follow instructions above, and install over your existing files.  The alternative is to install in a new folder (or rename the old one), and copy across files not in the release from old location to new location.


As mentioned earlier, you can choose where you install your three Cumulus downloads.  It is important to minimise the length of the path name, because this has to be passed between various different software languages (and longer paths risk truncation). Here I use “EXISTING PATH” (the contents of this will start with a slash “/”, but not end with a slash) to represent whatever path you have selected.
== Report and data files to copy across from any previous Cumulus location ==


It was also mentioned before that you can create the folder to hold the packages in advance using <code>sudo mkdir EXISTING PATH/CumulusMX</code>, and you can change its permissions using <code>chmod ugo+rwx CumulusMX</code>.
All the (optional) files in the [[Reports folder]] can be copied across from a previous installation. If your previous installation was not on Linux, see [[#Line terminators in .txt files]]


==Upgrading a Cumulus package==
All the files in the [[data folder]] can also be copied across. If your previous installation was not on Linux, see [[#Line terminators in .txt files]]


Upgrading to a new MX release is explained [[Updating_MX_to_new_version|here]], but basically follow instructions above, and install over your existing files.  The alternative is to install in a new folder (or rename the old one), and copy across files not in the release.


If your previous Cumulus installation was 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


==Configuration Files to copy across from any previous Cumulus installation==
==Configuration Files to copy across from any previous Cumulus installation==
Line 302: Line 348:
'''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.
'''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.


You create a “strings.ini” file by selecting some of the parameters from the [[samplestrings.ini]] file that is included in each MX release, and modifying the value for the listed attributes.
You create a “strings.ini” file by selecting some of the parameters from the [[samplestrings.ini]] file that is included in each MX release, and modifying the value for the listed attributes as you type them (under the same group titles - these are enclosed in [ ] as before).  


The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX.  They may also be change drastically be one MX release and the next.  Therefore, your existing “strings.ini” might need to be modified.
The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX.  So be cautious if you try to use a "strings.ini" file originally created by the legacy software, check whether the parameters you used before are still available in the latest "samplestrings.ini".


There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.
The content of "samplestrings.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 in “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.
 
Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is in “samplestring.ini” of your new install. You may also find parameters in “samplestring.ini” that you need to add to your “strings.ini” file.


===Cumulus.ini===
===Cumulus.ini===


Some people prefer to omit their existing “Cumulus.ini” file from their new install. Instead, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.
If your old release was 3.8.0 or later, then copy the [[Cumulus.ini]] file used in that old installation into your new one. The file is growing with lots of new parameters, and the tables on the page I have just linked indicated when parameters were introduced, and where those settings may be changed to make it simple for you to ensure all settings are right for your new release.
 
If you previously used an older release of Cumulus, but in this new installation will be using the latest release, you may want to read up on all the changes.
 
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. Documentation for the 1.9.4 file can be found [[Cumulus.ini_(Cumulus_1)|here]].
 
There were gradual changes to “Cumulus.ini” as releases went from 3.0.0 to 3.9.7, documentation can be found [[Cumulus.ini(MX_3.0.0_to_3.9.7)| here]] where the changes are made clear.  Please note, that page was not maintained after 3.7.x releases, and so does not show all changes from 3.8.0 to 3.9.7.


The documentation for the latest MX release can be found at [[Cumulus.ini]], note that it does include advice on (while MX is running) you can automatically update the file.  This automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.
If your old release was older that 3.8.0, then you will see [[:Category:Configuration Files|the Configuration Files page]] shows different links for documentation on older "cumulus.ini" files.  Because of those differences, many people prefer to rename their existing “Cumulus.ini” file when upgrading from such an old release, or making an install on a new device. To create a new file, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.  However, you do need to be aware that such older releases included a lot of "read-only" parameters that had to be set manually in the file, you may find some of those parameters are still needed by you, so you will want to edit the new file, with MX stopped, and copy any of those old "read-only" parameters that might not yet be settings you configure within the MX interface (although the number of these is diminishing with each new release).


==Folders to copy across from previous Cumulus installations==
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.


'''If you have used Cumulus before''', you will be seeking to keep your existing ([[:Category:MX txt Files|.txt]] and extremes [[:Category:Ini Files|.ini]]) files. This means you must transfer the whole [[Data folder|/data]] sub-folder from your old installation to your new installation.  If you use decimal commas, you might want to read what it says on [[:Category:Ini Files|this page]].
==Moving from Microsoft Windows to Linux==


If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
===Line terminators in .txt files===
* [[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


If you are using the optional “NOAA report” functionality, you must also transfer the whole [[Reports folder|Reports]] sub-folder.
If you are a novice to computers, skip this sub-section and the next, go directly to [[#File Names & Paths]].  


===Line terminators in these files===
You need to have some technical understanding to do an action that might encounter the issues discussed here. For normal MX usage, line terminators do not matter.


If you are moving from Microsoft Windows to Linux, you need to be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed).  
If you are moving from Microsoft Windows to Linux, be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed). Cumulus can cope with both approaches for existing files, but will create new files correctly for Linux.


The kernel in your Linux computer might be able to detect that it is getting Microsoft files, and discard the extra end of line character.
If you run your Linux computer in a headless mode, accessing its files by a remote terminal session, be aware that the line terminator used by the remote computer may be applied to files affected by whatever command you do remotely. Equally, running a Cumulus executable (MX or one of the utilities) may create new files with the wrong end of line terminator. The latest releases have been amended to match existing files, when they create a new file to replace an old file (or because that file is missing/corrupted).


However, if you are reading that file in a script, it might not detect the end of line encoding. So if that script expects “LF” to terminate each line, when the script is reading the final field of each line, the script will find that final field has an unwanted “CR” in it and not recognise it as a numerical value (or time-stamp). Equally, if the script expects “CR” as line terminator, then the first field of the each line (except the first line) starts with a “LF” and the script will not recognise it as a date (or section name).  
If you try to edit a file outside MX, the tool you choose to use might be able to detect that it is getting Microsoft files, and discard the extra end of line character.


In each case, any checking for numerical input might fail, and any attempt to check/extract characters from these fields might fail because their position relative to start/end is changed.
However, if you are reading a comma separated value file (such as MX uses for various files) in a script, your script might not detect the end of line encoding:
* If the script expects the Linus LF, and finds CR LF, then the final field of each CSV line has an invalid character in it, so your script will not be able to understand that field as a numerical value (or time-stamp).
* If the script expects CR only, and finds CR LF, then the first field of the each line presented to the script (except the first line) starts with a “LF” and the script will not recognise it as a date.
* If the script expects CR only, but just finds LF, the script will believe the whole file is just one line, and the fields before and after the LF will be treated as a single field so your script will not be able to understand that field as a numerical value (or time-stamp).
* If the script was written for a Microsoft Windows environment, it will expect CR LF, but might be confused if the end of line is different


If you run your Linux computer in a headless mode, accessing its files by a remote terminal session, be aware that the line terminator used by the remote computer may be applied to files affected by whatever command you do remotely.


===Changing line terminators===
===Changing line terminators===
Line 355: Line 393:
Both have capabilities to make such changes on either the single file that has focus, or all loaded files.
Both have capabilities to make such changes on either the single file that has focus, or all loaded files.


===File Names & Paths===
Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".
This could be applicable if you are using Extra Web files.
Here is an example changing the case and the separators: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.


=Running MX on Linux=
=Running MX on Linux=
Line 360: Line 407:
This section explores the optional parameters, and then covers 2 ways to run MX:
This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and  
# as a service and  
#directly with terminal window left open.
# interactively with terminal window left open.


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


<div style="background: LemonChiffon;padding:5px; margin:2px;">
This list of parameters covers every parameter, if you are using the latest release skip the historic 3.0.0 sub-sections.
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
 
</div>
IMPORTANT: The "sudo" prefix shown in code examples for the various parameters can be omitted if the user that is running MX owns the folder "CumulusMX" and all its contents. In the [[#Where to install all packages?|installation notes earlier]] possible locations and ownership issues were mentioned.  That earlier section also defined EXISTING PATH, if that is not mentioned in the code examples, it is assumed you have already issued a <code>cd EXISTING PATH</code> to be in the right folder for issuing the command.


Note that you ''may'' need to supply your root password after typing any 'sudo ...' command line if the instruction changes something set by another package (e.g. changing the locale for MX from the locale set by mono). The system will prompt you for this if it is needed.


=== Parameter for changing Port ===


== Beta builds of MX ==
When Cumulus starts, it will display the URL of the user interface. It runs on port 8998 by default; if this is not suitable for some reason you can over-ride it using the '-port' parameter on the command line, e.g. to use port 9999 instead:
<pre>sudo mono CumulusMX.exe -port 9999</pre>


=== web sockets ===
=== Parameter for changing Locale ===
 
On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
:<code>sudo mono CumulusMX.exe -lang en-GB</code>
 
Other locale examples:  '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''',  '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.
 
If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.


Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.  
Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.


You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
=== Parameter for running as service ===


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.  
The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>


=== Debugging of data flow between station and MX===
You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.
For the latest release, (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 this later release announcement]:
#There is a task to do just once to configure the service
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <code>sudo nano cumulusmx.service</code> to edit the service configuration file
# Within the provided file you should find a [Service] section:
<pre>[Service]
User=root
Group=root
ExecStart=/usr/bin/mono-service -d:/home/install/CumulusMX CumulusMX.exe -service
Type=forking
ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock</pre>


Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).  
There are some edits needed to that section:
# Replace '''User=root''' if you want the service to run as a different user
# Edit the line that begins with '''ExecStart='''
#* The mandatory change is to replace '''/home/install''' by what you have selected for EXISTING PATH
#* An optional change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections above
#save file with a new name '''cumulusmx_mine.service''' (using a new name stops it being overwritten when we upgrade MX
#now copy file to where it is needed to run the service:
:<code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx_mine.service /etc/systemd/system/cumulusmx.service</code>


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.
Here is how the file might look after the changes:
<pre>[Unit]
Description=CumulusMX service
Documentation=https://cumuluswiki.org/a/Main_Page
After=network-online.target


[Service]
User=pi
Group=pi
ExecStart=/usr/bin/mono-service -d:/opt/CumulusMX CumulusMX.exe -service -debug
Type=forking
ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock


=== Parameter for changing Port ===
[Install]
WantedBy=multi-user.target</pre>


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:
== Setting up as a service in release 3.8.0 ==
<pre>sudo mono CumulusMX.exe -port 9999</pre>


You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable
Skip this sub-section for latest release. 


For historic reasons, note the original instructions in the 3.8.0 [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 release announcement]:
# Ensure you are in the folder containing CumulusMX.exe
# Type <code> mono-service -l:/var/run/cmx.pid CumulusMX.exe -service</code>
# (to verify) note this does not allow you to add -port, -debug, -locale parameters


=== Parameter for adding debugging ===
=== Parameter for adding debugging ===
Line 402: Line 493:
:<code>sudo mono CumulusMX.exe -debug</code>
:<code>sudo mono CumulusMX.exe -debug</code>


You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===


Since this parameter is applied when you start MX, it applies all the time MX continues to run. 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.
The following two parameters cannot be used with MX since it came out of 3.0.0 beta.


==== web sockets ====


=== Parameter for changing Locale ===
Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono EXISTING PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.
 
On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
<pre>
sudo mono CumulusMX.exe -lang en-GB
</pre>


You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
That parameter [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 is now deprecated as 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]], see -port parameter described earlier.  


Other local examples:  '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''',  '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.
==== Debugging of data flow between station and MX====


If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.
Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).  
 
Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.
 
Note that you ''may'' need to supply your administrator password after typing the 'sudo ...' command line. The system will prompt you for this if it is needed.
 
=== Parameter for running as service ===
 
Use of this is explained next.  The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>
 
=== Setting up as a service ===
 
If you have installed MX release 3.8.0 or later, you can set up MX to run as a service.
 
Original way (more information at [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 this release announcement]):
# Ensure you are in the folder containing CumulusMX.exe
# Type <code> mono-service -l:/var/run/cmx.pid CumulusMX.exe -service</code>
# (to verify) note this does not allow you to add -port, -debug, -locale parameters
 
A better way (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 this later release announcement]:
#There is a task to do just once to configure the service
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <code>sudo nano cumulusmx.service</code> to edit the service configuration file
# Look for '''ExecStart=/usr/bin/mono-service -d:'''
#* Replace the path that follows the above text with the path to your CumulusMX.exe, add the '''-service''' and optionally add any other parameter (e.g. '''-debug''', -locale, -port) as described in sub-sections above.
#save file
#now copy file
:<code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</code>


If you upgrade to a new release, the file in EXISTING PATH will be overwritten, but the critical file in "/etc/sytemd/system" will not be affected.
Note use of this parameter is now deprecated.


===Running as a service===
Although this is not mentioned in any release announcements, it appears that on all recent MX releases this effect is incorporated into the '''-debug''' parameter described earlier.  Perhaps someone could confirm whether this is true.


If you want MX to automatically start when your Linux computer is booted, just type <code>sudo systemctl enable cumulusmx</code> once, and it will be activated on each reboot.


To manually start MX as a service, (such as after any MX upgrade to a new release, or when you want to first run it), simply type <code>sudo systemctl start cumulusmx</code>
==Running as a service==


The instructions to set up the ability to run MX as a service [[#Parameter for running as service| were given earlier]]. If you want MX to automatically start when your Linux computer is booted, just type <code>sudo systemctl enable cumulusmx</code> once, and it will be activated on each reboot.


Use <code>systemctl status cumulusmx.service</code> in a terminal session to see status of Cumulus service
The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]],they are not duplicated here, so there is only one place to do any update.


In the [[#Parameter for running as service|earlier instructions]] it was suggested you change the user for the service, if you have done that you can omit the "sudo" in <code>sudo systemctl start cumulusmx</code> which manually restarts the service.  Equally, you can omit "sudo" from any command that accesses Cumulus files created by the service.




=== Running with a terminal session left open ===
== Running any MX executable with a terminal session left open ==


This is alternative to the running as service as described above.
This is alternative to the running as service as described above.


Whichever operating system you are using, to run MX requires an instruction that changes to the directory (EXISTING PATH) where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].
The simplest instruction to run Cumulus MX is <code>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</code>. 
* This is two commands issued together, the first changes the working folder, the second actually starts the main executable
** To run "Create Missing" or '''ExportToMySQL''', just edit what appears after "mono" to the correct executable name
* If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "EXISTING PATH/CumulusMX" folder and you can omit the "sudo".
* You can add parameters after "CumulusMX.exe"  (select from '''-debug''', -locale, -port) as described in sub-sections above


The simplest instruction to run Cumulus MX  is <code>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</code>.  Just in case it is not obvious .... if you start MX using this command in a terminal window on your Pi, you must leave that session running, then MX will continue to run.  
Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running.  


You can start it off directly on your Pi, and then
You can start it off directly on your Pi, and then
Line 490: Line 554:
The styling and library files were 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.
The styling and library files were 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.  
Please read [[Customised_templates]] for further information about the various pages originally provided, and how you could customise them to suit you.  
   
   
=== Comparison with legacy Cumulus 1 web pages ===
=== Comparison with legacy Cumulus 1 web pages ===


* Note that the MX web files are not the same as the ones for Cumulus 1,  
* Note that any web files, designed for Cumulus 1, cannot be used with MX, for multiple reasons
** 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.  
** 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 standard gauges are rather like the stand alone [[SteelSeries Gauges|SteelSeries gauges]] you could optionally add to Cumulus 1, but the MX ones are different.
* The trends web page in Cumulus 1 relied on that software generating graphs as images.
** The new default gauges page does not display a graph when you hover over a gauge (Cumulus 1 generated some images that the stand alone Steel Series gauges page could use)
** 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.
* The various charts pages for MX rely on MX to generate files with time and value pairs, these are stored in json format, the various web pages use a library package (Highstocks) to draw graphs from those data pairs.
** (The Trends page provided as standard in Cumulus 1 simply displayed images of graphs uploaded to the web server)


== Alternative ways to obtain web pages ==
== Alternative ways to obtain web pages ==
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/9237...9558"

Navigation menu