MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
 
(111 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
'''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.
=Using MX on UNIX-derived Operating Systems=
=Using MX on UNIX-derived Operating Systems=
 
[[Category:Cumulus MX]]
MX runs on any UNIX-derived operating systems (OS):
MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,  
* including those found on Apple Mac computers,  
* and those found on a multitude of devices running Linux.  
* and those found on a multitude of devices running Linux.  


UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.
UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn just once and then you can normally continue to use what you have learnt.  
 
==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 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.
 
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?
Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.


:Until somebody creates a separate page for Apple Mac computers (that would be a good idea), this page is the closest.


==What do people think about MX on Linux?==
==Why install MX on Linux?==


Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*In general, people find installing, and running, MX on Linux is easy
*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 therefore are so convinced they cannot cope with a swap to something different, that they give up too easily!


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 (all others are mostly based on UNIX).


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.
You may know that this Wiki started with a single page covering MX regardless on which operating system was used, that did not work.  


=Page Content=
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. In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs.  It appears this is not because Microsoft computers are so more readily available and therefore known about; but because people often find “installing”, and using, MX is more difficult when using the more complex Microsoft Windows operating system, and people tend not to understand basic issues such as avoiding "Program Files".
{{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:
{{Template:Version badge Mx}}'''This page focuses on aspects of MX that are specific to the Linux operating systems.'''
*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=
Still believe it will be too complex for you? The developer has created [[Software#Raspberry_Pi_Image|an image you can download]] for those prepared to run two computers (a RPi for actually running MX and another computer for all interactions with MX).  Read all about it, on [[Raspberry_Pi_Image]] page, and decide if that is for you.


You have two choices:
==Device Coverage==


CHOICE ONE: ‘’’Create a micro-SD card that has everything on it to load a kernel onto your computer and run MX’’’
Linux is available based on a multitude of different kernels (the building block for the operating system), on a multitude of devices.


The developer has created [[Software#Raspberry_Pi_Image|an image you can download]].
This page has been originated by a contributor using the Raspberry Pi Operating System (this is based on Debian, one of the Linux kernels). Be aware therefore that some instructions on this page are specific to a [[Raspberry Pi computer page|Raspberry Pi computer]] with its default operating system.


That image contains:
For other devices, the inclusion of the correct instructions is totally dependent on whether any contributor has edited this page to cover your device in the context of that section of this page. It is hoped that contributions to this page will be made by Cumulus users with a range of different devices so this page is useful to more people.
#Raspberry Pi Lite Operating System as kernel (no graphical user interface, designed for a RPi without keyboard or monitor)
#Mono-complete package
#Cumulus MX package


* If you are new to MX, after booting from image, you will need to use the [[MX_Administrative_Interface#Station_Settings|admin interface]] to define station type, your choice of units, and some other settings, before MX can start recording data from the connected weather station.
:Until somebody creates a separate page for Apple Mac computers (that could be a good idea, as there are some significant differences), this page is the best source of advice.
* If you are migrating from another computer, after booting from image, you need to add (using an external memory stick or file transfer from your other device to the RPi), the following:
** (mandatory) [[Cumulus.ini]],
**(optional) [[strings.ini]],
**(mandatory) all files from old [[Data_folder|data sub-folder]],
**and any (optional) files from old Reports sub-folder.


If you want to pursue that approach, please read [[Raspberry_Pi_Image]] page, instead of continuing to read this page.  Obviously, you can return to this page if you want to learn more.
==Further Information==


CHOICE TWO: ‘’’Load the software packages individually’’’
There are various related pages to get more information:
* If you encounter a problem when running MX, please see [[What to do when I have a problem with MX]]
* If MX gives you a message saying "you are not running the latest version", please see [[Updating_MX_to_new_version|Guide to upgrading MX]]
* If you are puzzled by the terminology, please see [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (these pages were written for the legacy Cumulus 1 and may need updating for MX)
* If you need to know more about files in the installation, please see [[:Category:Cumulus Files]] for links to all Wiki pages describing the sub-folders and files used by 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
* 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
* If you will be using the standard web pages (from release 3.10.1) see [[New_Default_Web_Site_Information|this page]]
* If you want to write your own customised templates, read [[Customised_templates]].
* If you want to explore alternative web pages from third-parties, start [[:Category:User Contributions|on User Contributions page]].


Please read on, this page will tell you all you need to know.


= Do you have a Operating System? =


Is your Linux computer already working? Or does it need an Operating System to be installed?
=Preparing your computer for installing the Cumulus MX suite=


An operating system is the is is the software that is loaded onto your computer to provide commands and everything else that males a computer work.
Please see [[Preparing your Linux computer for MX]] page if you have not installed MX on Linux before.


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.
That page covers:
* [[Preparing your Linux computer for MX#Operating systems|Installing Operating Systems]]
* Package manager
** [[Preparing your Linux computer for MX#Interactive Package management on RPi|Interactive version]]
** [[Preparing your Linux computer for MX#Using Package Manager in terminal mode|Terminal version]]
** [[Preparing your Linux computer for MX#The various components to commands for installation|Commands]]
* [[Preparing your Linux computer for MX#USB HID|Human Interface Devices]]
* [[Preparing your Linux computer for MX#Installing Mono instruction|'''Installing Mono''']]
* [[Preparing your Linux computer for MX#Moving from Microsoft Windows to Linux|Preparing Microsoft Windows files for Linux]]
* [[Preparing your Linux computer for MX#File Names & Paths|Guide to file names and paths]]


=Ready to install MX?=


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.


Please be advised some of the above is rather technical reading, but ''Mono is required to run the Cumulus packages'' described next.  So do ensure that you installed Mono before continuing.


==The various components to commands for installation==
==Technical aside==


Linux computers have a “source list” which references the repositories from which software packages can be installed.
Please note this Wiki page talks about "folders" for compatibility with the [[MX on Windows OS]] page, but Linux prefers to call them directories.


If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.
Linux has a well defined filesystem, represented as a hierarchic tree starting at the root "/", that is divided into directories (one of which will be "/boot" and hold the kernel), each of those first level directories can be divided into second level directories, this second level is sometimes referenced to as defining the "scope", an indication that each is meant to be used for a specific purpose. The scope can be sub-divided again at lower levels representing "categories" (categories cover items like binary code, documentation, configuration, hardware, source code, runtime and content), and at a lower level still "applications" (i.e. related to specific programs) with further sub-levels for various options within those applications. Many Linux distributions will use logical links so references to a directory at one level in the hierarchy will actually redirect to files in a different directory, this might be because different programs expect to see files in different places or just to enforce ownership and writing rights.


===sudo===
For the purposes of this Wiki, the terminology "operating system" is used for the whole Linux distribution, you will find that Linux technical people prefer to talk about Linux distributions including:
# a "kernel" for the underlying handling of files, network and so on;
# one or more "shell" components for the handling of commands entered in terminal mode, including those that run programs (whether included in distribution or added later);
# an optional graphical user interface for simpler access to commands and programs.


The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.
For simplicity the terminology "terminal" is used for how you access the shell, this term refers to seeing the command prompt if your Linux is running without a graphical user interface, or to a window that you can open within the graphical interface where commands can be typed. Depending on your Linux, that window might be called "Terminal", "Konsole", "xterm", "gnome-terminal", "uxterm", or even something else. If you are accessing your Linux computer over a network from a computer running Microsoft Windows, then again you may encounter a number of terms for how to access the shell on your Linux computer, "Command Window", "Windows Powershell", or "Windows Terminal". Equally you may use software that calls it a teletype mode, e.g. PuTTY software.


You can change the rights in a folder, or for a file, to make this prefix unnecessary outside root access requiring contexts like installation.
=Cumulus packages=


===apt===
* This section covers:
** CumulusMX.exe
** ExportToMySQL.exe
** CreateMissing.exe


The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.
(At time of writing this "CreateRecords.exe" is proposed, and under development, but not released).


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.


===install===
==Handling zip files==


The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.
Each release is presented as a zip.  It does not matter which device (if you have two or more computers), or which browser (it can be default browser for your device or the browser you like best) you use for the download. 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.


For the record only, here is full list of what can follow “apt”:
In general, any device will load a suitable application to use to unzip the package when you click on a filename that ends in '''.zip'''.  You might need to do a "right click" and choose the application, it depends on your settings.


{| class="wikitable" border="1"
Be aware, you may need to adjust the settings within that application for how it handles the file structure. The preferences may determine whether the unzip process preserves the file structure used when the zip was created (i.e. each file remains in any sub-folder) or it ignores the folder structure.  For the Cumulus context, it is essential to preserve the folder structure. You may also be asked where you want the files to be extracted to, or the default settings might always use a particular destination (and that might be a '''tmp''' folder).
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|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
|-
|upgrade
|To see which of your packages have newer versions now available in repositories, and to replace those packages with the newer versions
|-
|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.


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
For example on the Raspberry Pi operating system, there is a package called '''xarchiver''', in its Graphical User Interface (GUI), there is a menu called "Action", and the final option in that menu is "Preferences". There, in "Archive" section, you can select "zip"  as the preferred archive format (using a drop-down) and whether you want the application to confirm with you before deleting any files; in "Advanced" section, you can select the directory to use for the extraction. If you are using the lite version of the RPi OS, then you need to edit the '''/home/pi/.config/xarchiver/xarchiverrc''' file to set preferences, before you use the archiver package.  Once you have started the archiver package, and told it which file to process, you can click on '''Extract files''',
|-
the GUI presents a screen of options:
|remove
* "Extract to:", use the icon to browse to the required location if it has not been set up in preferences
|If you want to remove just one component manually, use “remove” followed by the name of component you no longer want
* "Ensure a containing directory", tick this if it has not been set in the configuration file
|-
* "Files", select "All files", the advice is to overwrite all of any existing files if you are upgrading, but you definitely need all files if this is a new install
|purge
* "Options"
|To remove any installed package and delete all related configuration files
** Tick "Extract files with full path", this is essential if you are going to successfully install any of the Cumulus software
|-
** Tick "Overwrite existing files",  the advice is to overwrite all of any existing files if you are upgrading, it may not always be clear which files have been updated since an earlier release, and there are a lot of interdependencies between different files
|search
|To search in repositories in source list for a package you specify after “search”
|-
|show
|To show any information available about a package that you name after the “show”
|}


=== Flags ===
It is worth stressing here, if you decide to customise any files that are included in a release distribution, then you should at the very least add something like an "_" character to the file name to make your tailored file different to the standard file. The best practice is to put any files you tailor, or any additional files you create, outside the CumulusMX folder.


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.
If you have chosen to do the download on a different device to that on which you will install, you can unzip on either device. To transfer either the downloaded .zip file, or the extracted file structure, between devices, you can use a file transfer package, or use a portable drive (a memory stick 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.


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.
==Where to install all packages?==


=== Name ===
For simplicity on this page CHOSEN 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.


The final part of the installation command is the name of the package or component that we want to install.
The phrase “CHOSEN 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.


== Preparing for an install==
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).


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:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>


Each of these can be understood from information in previous section.
===Creating the CumulusMX sub-folder===


= Which software packages will we install?=
* You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir CHOSEN PATH/CumulusMX</code> first (note that CHOSEN PATH is explained above and always starts with a slash “/”).
* By using the phrase CHOSEN 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 CHOSEN 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 CHOSEN 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)
*#* (Novices: Skip this step) If you do choose a CHOSEN PATH outside your home folder, then a more technical user can change the ownership of the "CumulusMX" sub-folder, to the default user (Pi) with <code>sudo chown -R pi: CHOSEN PATH/CumulusMX</code>, and reduce the need to use "sudo" on many actions. 


If you read all the previous section, it explained Linux has a ‘’’source list’’’ of ‘’’repositories’’’ from which it can load software packages.
==Packages to install==


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


As at 9 March 2020, another utility, '''CreateRecord''', has been initialised in the Github areas managed by the developer where Cumulus is worked on, although it appears to be just a concept on github.  This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]]. The developer is still aiming to make this available, but his work on it (on his computer) has been stalled by the level of pressure being applied for bug-fixes and changes to MX itself.


==Changing the Source List==
===Alternative download link for older package releases===


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.
Because the developer uses Git Hub to manage releases, the older releases remain available.


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.
====Old Cumulus MX packages====
Skip this subsection 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).


===Add the Mono repository for a Raspberry Pi===
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.


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].
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 first line (in each case) installs a certificate
Anyway, '''you can download any earlier MX build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
# the echo line defines a repository to add to the sources list.


{| class="wikitable" border="1"
====Old utilities====
|-
!style="width:300px" | Raspberry Operating System 9 (stretch)
!style="width:300px" | Raspberry Operating System 10 (buster)
|-
|<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-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==
The zips for "CreateMissing.exe" and "ExportToMySQL.exe" utilities do NOT contain the '''''.dll''''' components that they need when they are running.


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.
This means that each version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities is dependent on it being used with a release of Cumulus MX that does have correct  '''''.dll''''' components in its release distribution.


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.
That in turn means you can't use the latest version of the utility with older MX releases, nor can you use an old utility version with latest MX release. This is why [[Software#By_Mark_Crossley|utilities downloads]] make clear which MX release is the minimum for them.


Others can be found by choosing other tabs on any of those links.
The older versions of these "CreateMissing.exe" and "ExportToMySQL.exe" utilities are available by going directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigating to the utility of interest. However, to use those older versions, you also need to download the corresponding older MX release, because the MX distributions contain the .dll files that the utilities require, they are not in the utilities zip.  Because of this complication, novice users are advised not to attempt to use the older utilities, even if the latest version appears to have a bug.  Technical users may be able to work out which .dll files are needed and can be safely added back (if they are not left over from when that past MX release was in use). An alternative is to create a new folder with the old release packages (MX and the utility of interest), a copy of the latest Cumulus.ini file, and a copy of all files from /data sub-folder; then afterwards copy back the changed files into original /data folder.


== Installing Mono instruction ==
==Upgrading a Cumulus package==
 
Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.
 
The “sudo”, “apt”, “install”, and “-y” have already been explained.


The "mono-complete" is the package we want.
Always check the release announcements in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX announcements] for any action needed in planned upgrade.  In brief, all files from new release distribution replace the files from previous release, and the download/unzip is as covered above.


:Please note that if you just specify “mono”, you will get ‘’’mono-devel’’’ (the developer edition) that does not include all the components required by each of the Cumulus executables.
No further action needed for upgrade of "Create Missing" or "Export To My SQL" or "Create Records".  See below for upgrade of main Cumulus MX package.


Please note that a particular MX build might specify it needs a particular version of MonoHence, although normally you can upgrade a cumulus package without upgrading Mono, sometimes you will need to install Mono again.
If you are running an older MX release, before skipping in-between versions please check [[Updating_MX_to_new_version|here]].   


The latest release of Mono can always be downloaded from [https://www.mono-project.com/download/stable/#download-lin], follow step 1 there, but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’
If you run MX as a service, then:
# Ensure you are not doing any changes to settings
# Leave MX running as you copy files from the new release distribution over the existing files
# Try to pick a time just after MX has done any standard interval store of readings or upload, so that it is least busy
# Use <code>sudo systemctl restart cumulusmx</code> to stop and then restart MX picking up the new files
# Result, downtime of MX kept to a minimum, so avoiding losing data


=Cumulus packages=
If you run MX interactively, do the unzip into a temporary location before you stop MX, then copy all files from temporary location over your existing files, and finally restart MX. Depending on your weather station type, it might or might not offer historic data catch-up, so you might lose some data while MX is stopped, and therefore should keep the downtime to a minimum.


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.
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, but in that alternative you might forget some files.


Our next task is to install the Cumulus software listed on [[Software]] page:
==Changing location of Cumulus MX==
# '''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.
#* 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]]
#* '''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.


If your install, or upgrade, is creating MX in a different place to where you previously ran Cumulus, then you will want to copy files across that are not in the zip extract distribution.


==Where to install all packages?==
===Configuration Files to copy across from any previous Cumulus installation===
 
*For simplicity on this page EXISTING PATH is used to represent any location in the Linux file structure where you decide to install Cumulus:
**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
 
 
==Alternative download link for older MX releases==
 
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).
 
In such a case, download any earlier build, without the bug, from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
 
You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you 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.
 
==Handling zip files==
 
Each release is presented as a zip.
 
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.
 
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.
 
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 MX==
 
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.
 
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>.
 
==Upgrading a Cumulus package==
 
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.
 
 
==Configuration Files to copy across from any previous Cumulus installation==


There are two configuration files that are not included in any MX release:
There are two configuration files that are not included in any MX release:
Line 294: Line 215:
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file


If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.
Here, it must be stressed that having either or both of these files in an existing Cumulus installation does not imply such file or files can be understood by the new MX release you have just installed.


If you are upgrading from an older release, please read the next 2 sub-sections for advice.
Just copy the existing files from old to new installation, if
# Your locale is still the same
# All files on your new install are in same paths as on your old install (some settings involve specifying paths)
# Your old installation has a relatively recent MX release (compare the "y" in 3.y.z,between old and new installation, a difference of more than 1 in that middle figure means you do not have a recent release)
# Your old installation was on a Unix-based computer (not a computer running Microsoft Windows Operating System)


===strings.ini===
Please see the table below for more advice, but the problem is that content of both files has changed as MX has been developed, so some content is no longer understood, and some new content has been added.


'''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.
Some of the differences between versions of '''Cumulus.ini''' file can be seen by comparing the different pages in this Wiki documenting this file: [[Cumulus.ini (Beta)]], [[Cumulus.ini (Cumulus 1)]], [[Cumulus.ini (MX 3.0.0 to 3.7.0)]], [[Cumulus.ini (preserving history)]], and [[Cumulus.ini]], but even that does not tell the whole story.  MX release 3.12.0 needs to be installed if your old Cumulus was earlier than that, because it is the only release with code to rename the old "Cumulus.ini" and create a new file containing the new set of settings, and new names for some old settings, but without any old settings that are no longer recognised.   Please see [[Updating MX to new version]] page for more information about the need to step slowly through from old releases to the newest.


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. 


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.
If you are upgrading from an older release, please read the table for advice.


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


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.
The sections that appear in '''samplestring.ini''', and the parameters that appear within a section, depend upon which release you are using.  So be cautious if you try to reuse a "strings.ini" file originally created by the legacy software, you may find you need to specify your customisation using different parameters in the latest "samplestring.ini".
|-
|  The content of "Cumulus.ini" is changing as MX is developed, the [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Release Announcements] normally list any new parameters as they appear in the file, without always mentioning those that have become redundant. The announcements tend to avoid any detail, so you have to guess ''from the attribute'' what values it might take, and generally have no idea of where in the settings pages to make any change.


===Cumulus.ini===
To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]


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


If you previously used an older release of Cumulus, but in this new installation will be using the latest release, you may want to read up on all the changes.
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.


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]].
If you have used Cumulus 1 before, and decide to start with a new "Cumulus.ini" file, then you will need to work through all settings, to ensure they are set as you want. Please remember that when you use MX for first time, it uses that date it was first run as a starting date, and ignores any data found with earlier dates. Therefore you must change that start date:
'''MX interface''' --> Setting menu --> '''Station Settings''' --> Click on ''General Settings'' --> Click on '''Advanced Options''' --> Edit ''Records Began Date'' following instructions below that field


There were gradual changes to “Cumulus.ini” as releases went from 3.0.0 to 3.7.0, documentation can be found [[Cumulus.ini (MX_3.0.0_to_3.7.0)| here]] where the changes are made clear.
==="data" directory===


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 fileThis automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.
Please see [[:Category:Files_with_Comma_Separated_Values]], [[:Category:Ini_Files]], and [[Weather_Diary]], for information if you are moving from Cumulus 1 to MX.  Otherwise just copy files from any existing folder to your new one.


==Folders to copy across from previous Cumulus installations==
You may also wish to read:
** [[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 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]].
Complications occur if the locale used by '''Mono''' or the locale specified when starting MX using [[#-lang parameter for changing Locale|-lang parameter]] differs from the locale for your previous device (please see [[:Category:Files with Comma Separated Values]] because some locales separate fields with commas, some separate integer and decimal parts of real numbers with commas; not to mention all sorts of issues with how dates are formatted). The main MX developer proposed that the format of files with comma separated values will be fixed from a release planned for September 2020, so all dates will use one standard format, all numbers will use decimal points, and the field separating character will be fixed.


If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
Update May 2022, this has been put on hold, no public MX release has this restriction yet.
* [[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.


===Line terminators in these files===
==="Reports" directory===


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).  
By default MX now creates monthly and annual reports that are in the style used by NOAA in USA.  If you have been using this functionality before (and it is optional) then you need to file transfer, or copy, all the files that were in the old [[Reports folder]] into the new folder of that name.  Do look at that cross-reference, and read about the encoding default differences between Cumulus 1 and MX.


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.
=MX can cause problems with storage=


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).  
MX now assumes by default that you are going to use its [[New Default Web Site Information|Default Web Site]]. That means that by default MX will re-generate temporary files in its [[Web folder|/web sub-folder]] on a frequent time-scale. That number of files writes will considerably shorten the working life-time of the "high capacity micro-SD" card that is the default storage for the Raspberry Pi.  It will also considerably shorten the life of any flash memory (e.g. memory card) that you might install MX on.


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.
The expected life of any storage device, and the extent to which its life is shortened depends on the actual device.  The external devices that have the longest life (and therefore can cope most easily with multiple read/write actions) are solid state discs (SSD). Also the larger the capacity of the storage device, the more places on the device where files can be stored and the storing algorithm will try to spread the storing evenly across the entire storage area, so wear at any one location is reduced.


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.
All Linux computers will have some random access memory chips (RAM) and it is worthwhile to define part of that RAM as a drive used for temporary files.  For a Raspberry Pi computer, a typical approach would be to edit the fstab file, adding the line ''tmpfs /run/tmp tmpfs nodev,nosuid,size=1M 0 0'', but the size you choose will depend on RAM available and what temporary files are being created.  For maximum life of the "high capacity micro-SD" card if that is what your computer boots from, you should create a symbolic link path that maps the '''/tmp''' folder used by the system to your '''/run/tmp''' you have just defined in RAM.  The difficulty will be that you cannot create a logical redirect on '''/tmp''' if the folder is already in use, so that makes it too complicated to explain here.


===Changing line terminators===
==web directory==


Many editors designed for programmers (they might be described as providing a programming development environment) can change the line ending of every line (either while file is being edited or when file is saved).  
All the files in this folder come from the download.


‘’’Geany’’’ is a programming development editor provided on some Linux systems including Raspberry Pi, that can do this ('''Document''' menu, -->> '''Select Line Endings''').
However, when you are running MX, it may try to create temporary files here, and following the advice above, you may decide to set up symbolic links so any attempt to create a temporary file in the "web" folder is redirected to the temporary folder you set up in RAM.


Notepad++ is another editor available for multiple operating systems ('''Edit''' menu -->> '''EOL conversion''').
The links you need depend on which options you select in settings, you might find it easier to wait until you have run MX for a while to see what files are created that end in ".json".


Both have capabilities to make such changes on either the single file that has focus, or all loaded files.
If MX is currently running, you need to stop it, or at least alter any options that generate .json files.  Then you must delete those files that end in ".json", except that you don't delete "websitedataT.json".


In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier):


=Running MX on Linux=
<code>sudo ln -s /run/tmp/websitedata.json CHOSEN PATH/CumulusMX/web/websitedata.json</code>


This section explores the optional parameters, and then covers 2 ways to run MX:
Notes:
# as a service and  
* The "-s" flag is what says you are creating a symbolic link
#directly with terminal window left open.
* Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file
* "CHOSEN PATH" is defined in [[#Where to install all packages?]], but basically it starts with a "/" and defines the path to get to where "CumulusMX" is a sub-folder.
* The text "websitedata.json" is just one file in the set of files linked from [[:Category:JSON Files]].


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


<div style="background: LemonChiffon;padding:5px; margin:2px;">
There are multiple subsections here, you are unlikely to need to read them all. Look at each, and decide if it applies to you.
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>


== Parameters ==


CumulusMX.exe can take a number of optional parameters as summarised here:
{| class="wikitable" border="1"
!style="width:30px" | Parameter
!style="width:600px" | Description
|-
! scope="row" | -port nnnn
| This parameter can be used whether MX is running interactively or as a service. Used to change the port where the web server for the MX interface runs, when Cumulus starts, it will display the URL of the interface where you change the settings, this is port 8998 by default. To use it when running MX in interactive mode, type <code>sudo mono CumulusMX.exe -port 9999</code> and the interface will run at port 9999 instead.
|-
! scope="row" | -service
| This parameter is not available when running interactively. It is used in a service definition file, please see [[#Running MX as a Linux "systemd" service]] for all details
|-
! scope="row" | -lang {locale}
| This parameter can be used whether MX is running interactively or as a service. Used to change the locale that MX will use from the default on your computer.  To use it when running MX in interactive mode, type <code>sudo mono CumulusMX.exe -lang en_GB</code. There is a list of locale codes at http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. Remember this changes whether MX uses decimal comma or decimal point (although the intention is that all Cumulus files will use decimal points, this will still affect the output from api calls, web tags, etc.) and how it names files that include letetrs representing a month abbreviation.
|-
! scope="row" | -debug
| This parameter can be used whether MX is running interactively or as a service. This is only available for [https://cumulus.hosiene.co.uk/viewtopic.php?p=138839#p138839 release 3.4.4 - Build 3068] onwards. This switches on debug and (from 3.1.0) data logging from the start-up of Cumulus MX. Please note this increases size of files created in [[MXdiags_folder]].  As an alternative to using this parameter, you can switch debug and data logging on and off within the MX interface settings, see the aforementioned link for instructions.
|-
! scope="row" | -wsport
| Applied to MX beta 3.0.0, no longer available, set the port for web sockets, now incorporated into the -port parameter.
|-
! scope="row" | -logging
| Applied to MX beta 3.0.0, no longer available, enabled just data logging, now incorporated into the -debug parameter
|}


== Beta builds of MX ==


=== web sockets ===


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'''.
==Your first run of  MX on Linux==


You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
Once you have got all the files sorted out as described above, you need to run MX.


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.  
On the first run of MX, unless you have run a recent release before, you need to work through either the [[First_Run_of_MX|'''Config wizard''']] or all the individual settings pages (or both) as accessed from "Settings" menu.  It is suggested you run MX interactively (see below) to do this, as you will then need to close MX, and then start it up again.


=== Debugging of data flow between station and MX===
Information about settings is on other Wiki pages ([[MX Administrative Interface]] and [[Cumulus.ini]]).


Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).
== Run interactive or as a service==


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''' parameterPerhaps someone could confirm whether this is true.
MX can be run in two different ways.   


It is advised that you run MX interactively to begin with, and only run it as a service when you are happy that all settings are correct, and that any uploading or other external tasks are working correctly.


=== Parameter for changing Port ===
Running interactively allows MX to display error messages to you, and to confirm when it is running normally. Just in case it is not obvious .... if you start any executable interactively in a terminal window on your Pi, you must leave that session running, or that executable will stop running


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:
If you run MX as a service you do not get any direct feedback, and cannot see if there has been a problem or failure. Running as a "systemd" service was first made available at Patch release 3.8.4 - b3094 (14 September 2020).
<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
==Running MX interactively==


To run MX interactively, you must open a terminal window, and leave it open until after you have closed MX.


=== Parameter for adding debugging ===
The simplest instruction to run Cumulus MX  is <code>cd CHOSEN PATH/CumulusMX && sudo mono CumulusMX.exe [optional parameters]</code>. 
* This is two commands issued together, the first changes the working folder, the "&&" means that first command has to succeed before the second command is obeyed and actually starts the main executable
* This example has not included any optional parameters, as they are rarely needed, but the optional parameters available are as listed in table earlier.


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.
When you want MX to stop, you must (for Linux) within your terminal session hold down the "Ctrl" button on your keyboard, and press "c". A word of caution here, if you are accessing your Linux computer over a network from another computer, do be careful about using any control sequences, as it is possible that your "Ctrl" "C" sequence will be applied to an application other than Cumulus MX, if that terminal session has started more than one application. The issue is that all running applications use the same terminator, it should be applied to whatever is regarded as the "foreground" application at the moment the control key sequence is used, which is guaranteed to be MX if that terminal session has only been used for running MX, and MX has not launched any external applications. After that you can choose to close the terminal window.


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: 
===Interactive advice===
:<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.
If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "CHOSEN PATH/CumulusMX" folder and you ''may'' be able to omit the "sudo" befor the "mono". I say "may" because there are other reasons why you may need to run as root user, too technical to explain here.
 
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. 
 
 
=== 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:
<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.
 
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'''.
 
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.
 
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.
 
===Running as a service===
 
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>
 
 
Use <code>systemctl status cumulusmx.service</code> in a terminal session to see status of Cumulus service
 
 
 
=== Running with a terminal session left open ===
 
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>.  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.  


You can start it off directly on your Pi, and then
You can start it off directly on your Pi, and then
Line 474: Line 377:
*Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.
*Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.


Use <code>'''ps -ef | grep -i cumulus | grep -v grep'''</code> to see if Cumulus is running or not.
===Running MX interactively from a remote computer===


= Operating a web site with uploads from MX engine =
This is similar to running a terminal session on the machine that you installed MX on. If your remote computer is running Microsoft Windows, then the option to run a terminal session, may be called "terminal", "powershell window", "command window", or you might install software such as "PuTTY" to provide the teminal (TTY is the abbreviation for "teletype", a device that was commonly used to access computers in the 1970s and early 1980s).


== The standard web pages ==
These won't be explained any further here, but be aware that control key sequences may not work, and you may need to type "exit" to close the session.


=== From release 3.10.1 ===
Use <code>'''ps -ef | grep -i cumulus | grep -v grep'''</code> to see if Cumulus is running or not.


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]].
== Running another executable with a terminal session left open ==


Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.
Open a  terminal window, then navigate to the folder where you have installed the 3 Cumulus executables:


=== Until release 3.9.7 ===
To run "Create Missing utility" type <code>cd CHOSEN PATH/CumulusMX && sudo mono CreateMissing.exe</code>. It does not take any parameters, so that is all you need to know, although it is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.


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.
To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, follow that link for more details.


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,
==Running MX as a Linux "systemd" service==
** 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 ==
There is a one-off task to define a service file, after that you can simply issue commands to stop/start/restart the service.


You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].
For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement].


== Using your own web pages ==
===The Service definition file===


* 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:
The MX download includes a file that can be used as a starting point for the service definition. Find this file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service''. You do have to edit this file, and then you have to copy it to a new location, before you start the MX service for the first time.
*# 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.
# Open the file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor  (see [[Preparing_your_Linux_computer_for_MX#editing_files|editing_files]]).
#* On a Raspberry Pi with a graphical interface, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
#* If you are accessing from another computer, using a terminal session, then "nano" is a suitable editor (explained at link just mentioned).
# 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 -f /tmp/CumulusMX.exe.lock</pre>


=That is enough folks=
*Be aware that what quoted above applies from MX 3.16.0 (b.3182, 30 Apr 2022) onwards, earlier releases did not include the "-f" flag in final line quoted above.


If you have read up to here, you now know the basics for using MX on Linux.
:There is more in the file, but for now focus on the line including "ExecStart=/usr/bin/mono-service -d:". Don't change any of the bit I just quoted.


The remaining sections are more technical and so you can skip them.
Almost certainly you will need to change "/home/install/CumulusMX" on that line.  Replace that with "CHOSEN PATH/CumulusMX", i.e. the full path to the directory that the executables are being stored in.


=Technical Extra=
The final line, with all possible parameters, could read: <code>'ExecStart=/usr/bin/mono-service -d:CHOSEN PATH/CumulusMX CumulusMX.exe -service -debug -port 999 - lang el-GR</code>
* Note the space between the path (just looked at) and the executable file,
* Note the mandatory parameter "-service" that follows a space after the "CumulusMX.exe", you must leave that untouched,
* Note you can remove/keep the rest of the line after the -service i.e. the other parameters (some with their values) -lang, -port, or -debug, (as defined in table earlier),  are all optional.


PLEASE SKIP ALL SUBSEQUENT SUB-SECTIONS IF YOU WANT TO AVOID TECHNICAL EXPLANATIONS.


== A very quick introduction to Linux ==
Technical user may do other edits on the file, these will be described later, for now save the changed file under a new name (so it won't be lost when you do a MX upgrade that replaces original file) within your MX installation:
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service'''
# Exit out of the editor you are using
# Next, open a terminal session
# Now copy file to where it is needed to run the service <code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx_edited.service /etc/systemd/system/cumulusmx.service</code>
# Now type <code>sudo systemctl daemon-reload</code>, this tells "systemd" that it needs to reload all service definitions because either one has changed, or a new one has been added
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot


This article is not the place to teach you Linux, you can find books and on-line articles for yourself, but I list here enough for you to understand the instructions used elsewhere in this article.


If you have a Raspberry Pi with a monitor attached, you will see a raspberry icon that you can click to get Graphical User Interface access to many features, including shutdown options.
====Technical users - additional edits====


=== su and sudo ===
Novice users, skip this subsection.  ''The changes in this subsection have to be made with other changes that are not covered here'' (they depend on your weather station type, and your computer type, so are not appropriate to a Wiki page trying to generalise, and anyway your contributor is not a technical expert).


There is a command <code>su</code> that allows a terminal session to become a super user session with root privileges. If you use that command, without a '''sudo''' command in front, you need to type in the password (we changed earlier) when prompted.  if you type <code>sudo su</code>, then you get root privileges without being asked to quote password. All subsequent lines in this terminal session will have a prompt that reminds you that you have root access and do not need to prefix subsequent commands with "sudo".
:Look at the '''[Service]''' part of the file quoted above.


Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.
This states Cumulus should use root for both the user it runs under and for the group permissions it uses. ''If you have the technical expertise'', you might choose to run MX in a different user, if your weather station type allows MX to run in a different user. If so, replace the "root" in its two locations. (Please note some weather stations require other changes outside this file before Cumulus can make contact, one example is discussed [https://cumulus.hosiene.co.uk/viewtopic.php?t=20413 on support forum here], but there are other topics that may be relevant).  


You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.  
You may also wish to add an extra line after the "Group" line <code>ExecStartPre=/bin/sleep 5</code>, this [https://cumulus.hosiene.co.uk/viewtopic.php?p=163754#p163754 is to delay the starting of MX by 5 seconds while other services start] (on a reboot of your computer) that might affect MX. (For some users, change 5 into 10, it all depends what else is being started).


There are also some commands (like displaying mounted storage) that are not available to a standard user. Here are 3 system commands that in terminal mode will only ever work with this prefix (although if you have installed the version of the Raspberry Pi Operating System that supports a graphical user interface you can also select these actions from a menu):
:Look at the rest of the file, the '''[Unit]''' part.
*'''sudo halt''' = stops any cpu functions, but leaves Pi running; used when you have reached the end of commands you want to do for now
*'''sudo poweroff''' = makes pi do a tidy shutdown and turn off its power; used when you will not be using your Pi for a while
*'''sudo reboot''' (or "sudo reboot -verbose" for diagnostic output during shutdown and reboot) = makes your Pi close down and then reboot; used when you change settings, and after you install new software, to ensure Pi starts with all applications running using the latest settings and latest already installed software


=== ~ and / ===
For releases 3.8.4 to 3.15.0: you will see one reference to '''network-online.target''' in <code>After=network-online.target</code>.


The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.
For release 3.15.1 build 3170 (19 March 2022) onwards: you will see an extra line <code>Wants=network-online.target</code>


To reference a folder in root or any other area, the prefix is always '''/'''.
If you are a technical user, you might decide to edit the [Unit] part of the file, you have to decide what is needed in your context, only you know what other services are started by systemd on your computer, you can list all items using something like <code>systemctl list-unit-files</code> to see the services, but you still need to understand what each does.


If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are availableThe file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarksDepending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.
If your computer has online access, then it can look up the correct time online and adjust its clock. However, it might not even try to do that for say 10 minutes after being booted, and so there may be a benefit in making MX wait until after systemd has asked for the time to be synced, and asked that the local file-system is made ready so MX can read/update/store filesTo achieve this, you might choose to add a blank line after '''<nowiki>Documentation=https://cumuluswiki.org/a/Main_Page</nowiki>''' and in that blank line, type <code>Requires= time-sync.target local-fs.target</code>. Using "Requires" ensures these requesting events have happened before MX can start, if they fail, MX will not be started, this example has not specified a time that MX should wait for the other services to start!


In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.
For that ''time-sync.target'' to work, you need to '''enable''', by creating the symbolic links needed, the appropriate services outside this edit:
 
<pre>sudo systemctl enable --now systemd-timesyncd.service
 
sudo systemctl enable --now systemd-time-wait-sync.service
 
</pre>
=== folder commands ===
 
To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.
 
To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.
 
To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!
 
To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>
 
Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>. 
 
An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).
 
=== chmod ===
 
When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder.  Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).
 
 
*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]
 
Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit.  So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.
 
=== editing files ===
 
*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.
 
There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality
 
All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit. 
 
====nano====
 
The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory.  If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]].  If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.
 
After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>. 
 
After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.
 
You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.
 
====Geany====
 
This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard).  Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.
 
Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.
 
== removing an unwanted file ==
 
You can remove a file with various commands, including <code>sudo rm filename</code>.
 
 
=== external storage ===
 
Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.
 
However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).
 
You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].
 
 
Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we  selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.
 
 
== Package Manager – a brief technical aside==
 
Linux operating systems install software by looking in repositories, and checking a register showing dependencies.  When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.


If you look up on-line how to install any software in Linux, it may use “apt-get”, that is an earlier package manager, in general you can use “apt” instead now.


The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.
Here is a quick explanation of all entries in this UNIT section:
# Entries
#* The terminology "After" tells "systemd" that what is named can be started after MX, in this case it does not guarantee that the network service (to send data to a remote web server) will be started
#* The terminology "Wants" tells "systemd" that what is named is wanted now, i.e. try to start before MX, but still start MX even if the starting of the network service fails.
#* The terminology ''Requires'' tells  "systemd" that the "cumulusmx" service should not be started until the services specified on that line have successfully started
#*# The '''local-fs.target''' specifies that the ''cumulusmx'' service requires the file service to have started, i.e. checks your computer can read files before it attempts to start the ''cumulusmx'' service
#*# The '''time-sync.target''' specifies that the ''cumulusmx'' service requires the computer to have synced with some time source (see notes below), which could be useful if your weather station type does not time-stamp readings stored in the console, and you want to ensure MX reads correct time from your computer


===Debian as used by Raspberry Pi===
''Don't forget to save the file under a new name, and copy it as instructed in previous subsection.''


“Debian Linux” (and its derivatives such as “Raspberry Pi Operating System”) uses “apt” to mean a ‘’’Package Manager’’’ that can install, update, and remove packages from these computer systems.
====Technical Notes only relevant to Raspberry Pi====


For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).  
This Wiki page has tried to avoid being too specific to particular hardware, but to avoid misunderstanding the last subsection, a little does need to be said to justify the claim that only technical users, who understand all the other changes needed, should make changes mentioned there.  


There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).  
A standard Raspberry Pi computer does not include a clock chip. Instead one of the packages it loads as a service on booting is called "fake-hwclock", and that sets the clock to what the date/time was when it was last running, irrespective of how many days/hours it has been off. That counts as a time sync for the purposes of instruction specified above.  You can buy and fit a real-time clock chip, and configure your computer to use that, but even that RTC will only keep time when it is kept powered, and even then it will drift off unless periodically able to be corrected by a time from internet.


As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.
The issue is your Cumulus MX on restarting will skip the catch-up of historic data (should your weather station settings make that available), because the dummy clock makes MX think the computer was not off for long. Subsequent measurements will then get logged against the wrong time until the correct time is found on the internet (NTP). At that moment, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day. In my experience it can be anything from 2 minutes to 10 minutes after switch on before my RPi does a time sync over the internet.


===Ubuntu===
You might expect <code>sudo systemctl disable fake-hwclock.service</code> (or remove the service, and modify the scripts that call it) could ensure the computer (if online) has to get a time found on the internet (NTP). Nothing is as simple as it might seem!


For Ubuntu only “apt-get” was available up to 2014, when “apt” was added. Both work as described above for Debian. Again “apt” is best to use.
===Commands to do actions on a service===


===Mint===
You will need to start (or restart) MX after you have defined (or redefined) the service as instructed above.  The specific commands to use with MX service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]], here I simply repeat the basic commands that can be used with any service (status, enable, disable, start, stop, and restart).


Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features.  So both effectively do the same, but (as with previous flavours) “apt” is best to use.
Don't forget you may need to type <code>sudo systemctl daemon-reload</code> to tell "systemd" that it needs to reload all service definitions whenever either one has changed, or a new one has been added.


It is likely that other Linux variants will also vary how these alternative commands differ.
In all these commands, '''just replace [service_name] with ''cumulusmx''''' (or enter the name of another service).
* <code>sudo systemctl status [service_name]</code>
** (displays whether named service has started, whether it has failed, whether it has stopped, also whether enabled, extra information will be added should status change)
** type the single character "q" to quit updating status display and return to prompt
* <code>sudo systemctl enable [service_name]</code>
** (typed just once, and service named will automatically start when your Linux computer is booted)
** the confirmation message says a link has been created
* <code>sudo systemctl disable [service_name]</code>
** (used when you don't want an automatic restart of the named service)
* <code>sudo systemctl start [service_name]</code>
** (will start the named service)
* <code>sudo systemctl stop [service_name]</code>
** (will stop the named service)
** Closing MX with "cumulusmx" as the named service this way does a proper shutdown
* <code>sudo systemctl restart [service_name]</code>
** (issues a stop, then start, command to named service)
** You can upgrade MX by installing new files over the existing ones, while MX is left running, and then use this command to pick up new release with minimum downtime.

Latest revision as of 08:38, 20 September 2023

Using MX on UNIX-derived Operating Systems

MX runs on any UNIX-derived operating systems (OS):

  • including those found on Apple Mac computers,
  • and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn just once and then you can normally continue to use what you have learnt.

Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.


Why install MX on Linux?

Contributions to the Cumulus Support Forum suggest that:

  • Use on a Raspberry Pi (RPi) computer is very popular
  • In general, people find installing, and running, MX on Linux is easy
  • The few people who do have difficulties are those who have good knowledge of Microsoft systems and therefore are so convinced they cannot cope with a swap to something different, that they give up too easily!

Microsoft has had a deliberate policy of being different to traditional computers (all others are mostly based on UNIX).

You may know that this Wiki started with a single page covering MX regardless on which operating system was used, that did not work.

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. In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs. It appears this is not because Microsoft computers are so more readily available and therefore known about; but because people often find “installing”, and using, MX is more difficult when using the more complex Microsoft Windows operating system, and people tend not to understand basic issues such as avoiding "Program Files".


Cumulus Version MX SpecificThis page focuses on aspects of MX that are specific to the Linux operating systems.

Still believe it will be too complex for you? The developer has created an image you can download for those prepared to run two computers (a RPi for actually running MX and another computer for all interactions with MX). Read all about it, on Raspberry_Pi_Image page, and decide if that is for you.

Device Coverage

Linux is available based on a multitude of different kernels (the building block for the operating system), on a multitude of devices.

This page has been originated by a contributor using the Raspberry Pi Operating System (this is based on Debian, one of the Linux kernels). Be aware therefore that some instructions on this page are specific to a Raspberry Pi computer with its default operating system.

For other devices, the inclusion of the correct instructions is totally dependent on whether any contributor has edited this page to cover your device in the context of that section of this page. It is hoped that contributions to this page will be made by Cumulus users with a range of different devices so this page is useful to more people.

Until somebody creates a separate page for Apple Mac computers (that could be a good idea, as there are some significant differences), this page is the best source of advice.

Further Information

There are various related pages to get more information:

  • If you encounter a problem when running MX, please see What to do when I have a problem with MX
  • If MX gives you a message saying "you are not running the latest version", please see Guide to upgrading MX
  • If you are puzzled by the terminology, please see Category:Terminology for links to pages that explain terminology used by Cumulus (these pages were written for the legacy Cumulus 1 and may need updating for MX)
  • If you need to know more about files in the installation, please see Category:Cumulus Files for links to all Wiki pages describing the sub-folders and files used by MX
  • Go to Category:Cumulus MX for links to all pages in this Cumulus Wiki that relate specifically to MX
  • Admin interface provides information on configuration and web pages for viewing your weather data locally
  • 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 Hypertext Pre-processor and JavaScript page
  • If you will be using the standard web pages (from release 3.10.1) see this page
  • If you want to write your own customised templates, read Customised_templates.
  • If you want to explore alternative web pages from third-parties, start on User Contributions page.


Preparing your computer for installing the Cumulus MX suite

Please see Preparing your Linux computer for MX page if you have not installed MX on Linux before.

That page covers:


Please be advised some of the above is rather technical reading, but Mono is required to run the Cumulus packages described next. So do ensure that you installed Mono before continuing.

Technical aside

Please note this Wiki page talks about "folders" for compatibility with the MX on Windows OS page, but Linux prefers to call them directories.

Linux has a well defined filesystem, represented as a hierarchic tree starting at the root "/", that is divided into directories (one of which will be "/boot" and hold the kernel), each of those first level directories can be divided into second level directories, this second level is sometimes referenced to as defining the "scope", an indication that each is meant to be used for a specific purpose. The scope can be sub-divided again at lower levels representing "categories" (categories cover items like binary code, documentation, configuration, hardware, source code, runtime and content), and at a lower level still "applications" (i.e. related to specific programs) with further sub-levels for various options within those applications. Many Linux distributions will use logical links so references to a directory at one level in the hierarchy will actually redirect to files in a different directory, this might be because different programs expect to see files in different places or just to enforce ownership and writing rights.

For the purposes of this Wiki, the terminology "operating system" is used for the whole Linux distribution, you will find that Linux technical people prefer to talk about Linux distributions including:

  1. a "kernel" for the underlying handling of files, network and so on;
  2. one or more "shell" components for the handling of commands entered in terminal mode, including those that run programs (whether included in distribution or added later);
  3. an optional graphical user interface for simpler access to commands and programs.

For simplicity the terminology "terminal" is used for how you access the shell, this term refers to seeing the command prompt if your Linux is running without a graphical user interface, or to a window that you can open within the graphical interface where commands can be typed. Depending on your Linux, that window might be called "Terminal", "Konsole", "xterm", "gnome-terminal", "uxterm", or even something else. If you are accessing your Linux computer over a network from a computer running Microsoft Windows, then again you may encounter a number of terms for how to access the shell on your Linux computer, "Command Window", "Windows Powershell", or "Windows Terminal". Equally you may use software that calls it a teletype mode, e.g. PuTTY software.

Cumulus packages

  • This section covers:
    • CumulusMX.exe
    • ExportToMySQL.exe
    • CreateMissing.exe

(At time of writing this "CreateRecords.exe" is proposed, and under development, but not released).


Handling zip files

Each release is presented as a zip. It does not matter which device (if you have two or more computers), or which browser (it can be default browser for your device or the browser you like best) you use for the download. 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.

In general, any device will load a suitable application to use to unzip the package when you click on a filename that ends in .zip. You might need to do a "right click" and choose the application, it depends on your settings.

Be aware, you may need to adjust the settings within that application for how it handles the file structure. The preferences may determine whether the unzip process preserves the file structure used when the zip was created (i.e. each file remains in any sub-folder) or it ignores the folder structure. For the Cumulus context, it is essential to preserve the folder structure. You may also be asked where you want the files to be extracted to, or the default settings might always use a particular destination (and that might be a tmp folder).

For example on the Raspberry Pi operating system, there is a package called xarchiver, in its Graphical User Interface (GUI), there is a menu called "Action", and the final option in that menu is "Preferences". There, in "Archive" section, you can select "zip" as the preferred archive format (using a drop-down) and whether you want the application to confirm with you before deleting any files; in "Advanced" section, you can select the directory to use for the extraction. If you are using the lite version of the RPi OS, then you need to edit the /home/pi/.config/xarchiver/xarchiverrc file to set preferences, before you use the archiver package. Once you have started the archiver package, and told it which file to process, you can click on Extract files, the GUI presents a screen of options:

  • "Extract to:", use the icon to browse to the required location if it has not been set up in preferences
  • "Ensure a containing directory", tick this if it has not been set in the configuration file
  • "Files", select "All files", the advice is to overwrite all of any existing files if you are upgrading, but you definitely need all files if this is a new install
  • "Options"
    • Tick "Extract files with full path", this is essential if you are going to successfully install any of the Cumulus software
    • Tick "Overwrite existing files", the advice is to overwrite all of any existing files if you are upgrading, it may not always be clear which files have been updated since an earlier release, and there are a lot of interdependencies between different files

It is worth stressing here, if you decide to customise any files that are included in a release distribution, then you should at the very least add something like an "_" character to the file name to make your tailored file different to the standard file. The best practice is to put any files you tailor, or any additional files you create, outside the CumulusMX folder.

If you have chosen to do the download on a different device to that on which you will install, you can unzip on either device. To transfer either the downloaded .zip file, or the extracted file structure, between devices, you can use a file transfer package, or use a portable drive (a memory stick 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.

Where to install all packages?

For simplicity on this page CHOSEN 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.

The phrase “CHOSEN 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.

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


Creating the CumulusMX sub-folder

  • You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type sudo mkdir CHOSEN PATH/CumulusMX first (note that CHOSEN PATH is explained above and always starts with a slash “/”).
  • By using the phrase CHOSEN PATH this advice avoids telling you to install Cumulus where you do not want it:
    1. 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.
    2. Other people using a Raspberry Pi without that technical expertise, might use ‘’’/home/pi’’’ for CHOSEN 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.
    3. The developer suggests you use ‘’’/opt’’’ for CHOSEN 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)
      • (Novices: Skip this step) If you do choose a CHOSEN PATH outside your home folder, then a more technical user can change the ownership of the "CumulusMX" sub-folder, to the default user (Pi) with sudo chown -R pi: CHOSEN PATH/CumulusMX, and reduce the need to use "sudo" on many actions.

Packages to install

We shall install the Cumulus software listed on Software page:

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

As at 9 March 2020, another utility, CreateRecord, has been initialised in the Github areas managed by the developer where Cumulus is worked on, although it appears to be just a concept on github. This will, if my understanding is correct, read dayfile.txt and use that to update the various extreme record files. The developer is still aiming to make this available, but his work on it (on his computer) has been stalled by the level of pressure being applied for bug-fixes and changes to MX itself.

Alternative download link for older package releases

Because the developer uses Git Hub to manage releases, the older releases remain available.

Old Cumulus MX packages

Skip this subsection 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 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.

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

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

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

Old utilities

The zips for "CreateMissing.exe" and "ExportToMySQL.exe" utilities do NOT contain the .dll components that they need when they are running.

This means that each version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities is dependent on it being used with a release of Cumulus MX that does have correct .dll components in its release distribution.

That in turn means you can't use the latest version of the utility with older MX releases, nor can you use an old utility version with latest MX release. This is why utilities downloads make clear which MX release is the minimum for them.

The older versions of these "CreateMissing.exe" and "ExportToMySQL.exe" utilities are available by going directly to the Cumulus MX github page, and navigating to the utility of interest. However, to use those older versions, you also need to download the corresponding older MX release, because the MX distributions contain the .dll files that the utilities require, they are not in the utilities zip. Because of this complication, novice users are advised not to attempt to use the older utilities, even if the latest version appears to have a bug. Technical users may be able to work out which .dll files are needed and can be safely added back (if they are not left over from when that past MX release was in use). An alternative is to create a new folder with the old release packages (MX and the utility of interest), a copy of the latest Cumulus.ini file, and a copy of all files from /data sub-folder; then afterwards copy back the changed files into original /data folder.

Upgrading a Cumulus package

Always check the release announcements in Cumulus MX announcements for any action needed in planned upgrade. In brief, all files from new release distribution replace the files from previous release, and the download/unzip is as covered above.

No further action needed for upgrade of "Create Missing" or "Export To My SQL" or "Create Records". See below for upgrade of main Cumulus MX package.

If you are running an older MX release, before skipping in-between versions please check here.

If you run MX as a service, then:

  1. Ensure you are not doing any changes to settings
  2. Leave MX running as you copy files from the new release distribution over the existing files
  3. Try to pick a time just after MX has done any standard interval store of readings or upload, so that it is least busy
  4. Use sudo systemctl restart cumulusmx to stop and then restart MX picking up the new files
  5. Result, downtime of MX kept to a minimum, so avoiding losing data

If you run MX interactively, do the unzip into a temporary location before you stop MX, then copy all files from temporary location over your existing files, and finally restart MX. Depending on your weather station type, it might or might not offer historic data catch-up, so you might lose some data while MX is stopped, and therefore should keep the downtime to a minimum.

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, but in that alternative you might forget some files.

Changing location of Cumulus MX

If your install, or upgrade, is creating MX in a different place to where you previously ran Cumulus, then you will want to copy files across that are not in the zip extract distribution.

Configuration Files to copy across from any previous Cumulus installation

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

  • strings.ini (note all lower case) – optional file to customise output
  • Cumulus.ini (note initial capital, then lower case) – main configuration file

Here, it must be stressed that having either or both of these files in an existing Cumulus installation does not imply such file or files can be understood by the new MX release you have just installed.

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

  1. Your locale is still the same
  2. All files on your new install are in same paths as on your old install (some settings involve specifying paths)
  3. Your old installation has a relatively recent MX release (compare the "y" in 3.y.z,between old and new installation, a difference of more than 1 in that middle figure means you do not have a recent release)
  4. Your old installation was on a Unix-based computer (not a computer running Microsoft Windows Operating System)

Please see the table below for more advice, but the problem is that content of both files has changed as MX has been developed, so some content is no longer understood, and some new content has been added.

Some of the differences between versions of Cumulus.ini file can be seen by comparing the different pages in this Wiki documenting this file: Cumulus.ini (Beta), Cumulus.ini (Cumulus 1), Cumulus.ini (MX 3.0.0 to 3.7.0), Cumulus.ini (preserving history), and Cumulus.ini, but even that does not tell the whole story. MX release 3.12.0 needs to be installed if your old Cumulus was earlier than that, because it is the only release with code to rename the old "Cumulus.ini" and create a new file containing the new set of settings, and new names for some old settings, but without any old settings that are no longer recognised. Please see Updating MX to new version page for more information about the need to step slowly through from old releases to the newest.


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

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

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

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

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

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

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

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

If you have used Cumulus 1 before, and decide to start with a new "Cumulus.ini" file, then you will need to work through all settings, to ensure they are set as you want. Please remember that when you use MX for first time, it uses that date it was first run as a starting date, and ignores any data found with earlier dates. Therefore you must change that start date: MX interface --> Setting menu --> Station Settings --> Click on General Settings --> Click on Advanced Options --> Edit Records Began Date following instructions below that field

"data" directory

Please see Category:Files_with_Comma_Separated_Values, Category:Ini_Files, and Weather_Diary, for information if you are moving from Cumulus 1 to MX. Otherwise just copy files from any existing folder to your new one.

You may also wish to read:

    • Amending dayfile tells you about how MX is far more fussy about the content in dayfile.txt
    • .ini files explains how time-stamps are formatted differently in the extreme tracking files
    • Migrating from Cumulus 1 to MX gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

Complications occur if the locale used by Mono or the locale specified when starting MX using -lang parameter differs from the locale for your previous device (please see Category:Files with Comma Separated Values because some locales separate fields with commas, some separate integer and decimal parts of real numbers with commas; not to mention all sorts of issues with how dates are formatted). The main MX developer proposed that the format of files with comma separated values will be fixed from a release planned for September 2020, so all dates will use one standard format, all numbers will use decimal points, and the field separating character will be fixed.

Update May 2022, this has been put on hold, no public MX release has this restriction yet.


"Reports" directory

By default MX now creates monthly and annual reports that are in the style used by NOAA in USA. If you have been using this functionality before (and it is optional) then you need to file transfer, or copy, all the files that were in the old Reports folder into the new folder of that name. Do look at that cross-reference, and read about the encoding default differences between Cumulus 1 and MX.

MX can cause problems with storage

MX now assumes by default that you are going to use its Default Web Site. That means that by default MX will re-generate temporary files in its /web sub-folder on a frequent time-scale. That number of files writes will considerably shorten the working life-time of the "high capacity micro-SD" card that is the default storage for the Raspberry Pi. It will also considerably shorten the life of any flash memory (e.g. memory card) that you might install MX on.

The expected life of any storage device, and the extent to which its life is shortened depends on the actual device. The external devices that have the longest life (and therefore can cope most easily with multiple read/write actions) are solid state discs (SSD). Also the larger the capacity of the storage device, the more places on the device where files can be stored and the storing algorithm will try to spread the storing evenly across the entire storage area, so wear at any one location is reduced.

All Linux computers will have some random access memory chips (RAM) and it is worthwhile to define part of that RAM as a drive used for temporary files. For a Raspberry Pi computer, a typical approach would be to edit the fstab file, adding the line tmpfs /run/tmp tmpfs nodev,nosuid,size=1M 0 0, but the size you choose will depend on RAM available and what temporary files are being created. For maximum life of the "high capacity micro-SD" card if that is what your computer boots from, you should create a symbolic link path that maps the /tmp folder used by the system to your /run/tmp you have just defined in RAM. The difficulty will be that you cannot create a logical redirect on /tmp if the folder is already in use, so that makes it too complicated to explain here.

web directory

All the files in this folder come from the download.

However, when you are running MX, it may try to create temporary files here, and following the advice above, you may decide to set up symbolic links so any attempt to create a temporary file in the "web" folder is redirected to the temporary folder you set up in RAM.

The links you need depend on which options you select in settings, you might find it easier to wait until you have run MX for a while to see what files are created that end in ".json".

If MX is currently running, you need to stop it, or at least alter any options that generate .json files. Then you must delete those files that end in ".json", except that you don't delete "websitedataT.json".

In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier):

sudo ln -s /run/tmp/websitedata.json CHOSEN PATH/CumulusMX/web/websitedata.json

Notes:

  • The "-s" flag is what says you are creating a symbolic link
  • Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file
  • "CHOSEN PATH" is defined in #Where to install all packages?, but basically it starts with a "/" and defines the path to get to where "CumulusMX" is a sub-folder.
  • The text "websitedata.json" is just one file in the set of files linked from Category:JSON Files.

Running MX

There are multiple subsections here, you are unlikely to need to read them all. Look at each, and decide if it applies to you.

Parameters

CumulusMX.exe can take a number of optional parameters as summarised here:

Parameter Description
-port nnnn This parameter can be used whether MX is running interactively or as a service. Used to change the port where the web server for the MX interface runs, when Cumulus starts, it will display the URL of the interface where you change the settings, this is port 8998 by default. To use it when running MX in interactive mode, type sudo mono CumulusMX.exe -port 9999 and the interface will run at port 9999 instead.
-service This parameter is not available when running interactively. It is used in a service definition file, please see #Running MX as a Linux "systemd" service for all details
-lang {locale} This parameter can be used whether MX is running interactively or as a service. Used to change the locale that MX will use from the default on your computer. To use it when running MX in interactive mode, type sudo mono CumulusMX.exe -lang en_GB</code. There is a list of locale codes at http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. Remember this changes whether MX uses decimal comma or decimal point (although the intention is that all Cumulus files will use decimal points, this will still affect the output from api calls, web tags, etc.) and how it names files that include letetrs representing a month abbreviation.
-debug This parameter can be used whether MX is running interactively or as a service. This is only available for release 3.4.4 - Build 3068 onwards. This switches on debug and (from 3.1.0) data logging from the start-up of Cumulus MX. Please note this increases size of files created in MXdiags_folder. As an alternative to using this parameter, you can switch debug and data logging on and off within the MX interface settings, see the aforementioned link for instructions.
-wsport Applied to MX beta 3.0.0, no longer available, set the port for web sockets, now incorporated into the -port parameter.
-logging Applied to MX beta 3.0.0, no longer available, enabled just data logging, now incorporated into the -debug parameter


Your first run of MX on Linux

Once you have got all the files sorted out as described above, you need to run MX.

On the first run of MX, unless you have run a recent release before, you need to work through either the Config wizard or all the individual settings pages (or both) as accessed from "Settings" menu. It is suggested you run MX interactively (see below) to do this, as you will then need to close MX, and then start it up again.

Information about settings is on other Wiki pages (MX Administrative Interface and Cumulus.ini).

Run interactive or as a service

MX can be run in two different ways.

It is advised that you run MX interactively to begin with, and only run it as a service when you are happy that all settings are correct, and that any uploading or other external tasks are working correctly.

Running interactively allows MX to display error messages to you, and to confirm when it is running normally. Just in case it is not obvious .... if you start any executable interactively in a terminal window on your Pi, you must leave that session running, or that executable will stop running

If you run MX as a service you do not get any direct feedback, and cannot see if there has been a problem or failure. Running as a "systemd" service was first made available at Patch release 3.8.4 - b3094 (14 September 2020).

Running MX interactively

To run MX interactively, you must open a terminal window, and leave it open until after you have closed MX.

The simplest instruction to run Cumulus MX is cd CHOSEN PATH/CumulusMX && sudo mono CumulusMX.exe [optional parameters].

  • This is two commands issued together, the first changes the working folder, the "&&" means that first command has to succeed before the second command is obeyed and actually starts the main executable
  • This example has not included any optional parameters, as they are rarely needed, but the optional parameters available are as listed in table earlier.

When you want MX to stop, you must (for Linux) within your terminal session hold down the "Ctrl" button on your keyboard, and press "c". A word of caution here, if you are accessing your Linux computer over a network from another computer, do be careful about using any control sequences, as it is possible that your "Ctrl" "C" sequence will be applied to an application other than Cumulus MX, if that terminal session has started more than one application. The issue is that all running applications use the same terminator, it should be applied to whatever is regarded as the "foreground" application at the moment the control key sequence is used, which is guaranteed to be MX if that terminal session has only been used for running MX, and MX has not launched any external applications. After that you can choose to close the terminal window.

Interactive advice

If you have followed advice at #Where to install all packages?, the user you are using will own the "CHOSEN PATH/CumulusMX" folder and you may be able to omit the "sudo" befor the "mono". I say "may" because there are other reasons why you may need to run as root user, too technical to explain here.

You can start it off directly on your Pi, and then

  • optionally disconnect the keyboard,
  • switch off monitor or TV attached to your Pi,
  • Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.

Running MX interactively from a remote computer

This is similar to running a terminal session on the machine that you installed MX on. If your remote computer is running Microsoft Windows, then the option to run a terminal session, may be called "terminal", "powershell window", "command window", or you might install software such as "PuTTY" to provide the teminal (TTY is the abbreviation for "teletype", a device that was commonly used to access computers in the 1970s and early 1980s).

These won't be explained any further here, but be aware that control key sequences may not work, and you may need to type "exit" to close the session.

Use ps -ef | grep -i cumulus | grep -v grep to see if Cumulus is running or not.

Running another executable with a terminal session left open

Open a terminal window, then navigate to the folder where you have installed the 3 Cumulus executables:

To run "Create Missing utility" type cd CHOSEN PATH/CumulusMX && sudo mono CreateMissing.exe. It does not take any parameters, so that is all you need to know, although it is fully documented at Calculate_Missing_Values#CreateMissing.exe in this Wiki.

To run Export To My SQL, you change the name of the executable above and add the necessary parameters, follow that link for more details.


Running MX as a Linux "systemd" service

There is a one-off task to define a service file, after that you can simply issue commands to stop/start/restart the service.

For more information, see original release announcement.

The Service definition file

The MX download includes a file that can be used as a starting point for the service definition. Find this file at CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service. You do have to edit this file, and then you have to copy it to a new location, before you start the MX service for the first time.

  1. Open the file at CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service using an editor (see editing_files).
    • On a Raspberry Pi with a graphical interface, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
    • If you are accessing from another computer, using a terminal session, then "nano" is a suitable editor (explained at link just mentioned).
  2. Within the provided file you should find a [Service] section:
[Service]
User=root
Group=root
ExecStart=/usr/bin/mono-service -d:/home/install/CumulusMX CumulusMX.exe -service
Type=forking
ExecStopPost=/bin/rm -f /tmp/CumulusMX.exe.lock
  • Be aware that what quoted above applies from MX 3.16.0 (b.3182, 30 Apr 2022) onwards, earlier releases did not include the "-f" flag in final line quoted above.
There is more in the file, but for now focus on the line including "ExecStart=/usr/bin/mono-service -d:". Don't change any of the bit I just quoted.

Almost certainly you will need to change "/home/install/CumulusMX" on that line. Replace that with "CHOSEN PATH/CumulusMX", i.e. the full path to the directory that the executables are being stored in.

The final line, with all possible parameters, could read: 'ExecStart=/usr/bin/mono-service -d:CHOSEN PATH/CumulusMX CumulusMX.exe -service -debug -port 999 - lang el-GR

  • Note the space between the path (just looked at) and the executable file,
  • Note the mandatory parameter "-service" that follows a space after the "CumulusMX.exe", you must leave that untouched,
  • Note you can remove/keep the rest of the line after the -service i.e. the other parameters (some with their values) -lang, -port, or -debug, (as defined in table earlier), are all optional.


Technical user may do other edits on the file, these will be described later, for now save the changed file under a new name (so it won't be lost when you do a MX upgrade that replaces original file) within your MX installation:

  1. Open the "File" menu, and select "Save as" and enter a new name cumulusmx_edited.service
  2. Exit out of the editor you are using
  3. Next, open a terminal session
  4. Now copy file to where it is needed to run the service sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx_edited.service /etc/systemd/system/cumulusmx.service
  5. Now type sudo systemctl daemon-reload, this tells "systemd" that it needs to reload all service definitions because either one has changed, or a new one has been added
  6. Finally, optionally, create a symbolic link to that file using sudo systemctl enable cumulusmx if you want the service to automatically start after a reboot


Technical users - additional edits

Novice users, skip this subsection. The changes in this subsection have to be made with other changes that are not covered here (they depend on your weather station type, and your computer type, so are not appropriate to a Wiki page trying to generalise, and anyway your contributor is not a technical expert).

Look at the [Service] part of the file quoted above.

This states Cumulus should use root for both the user it runs under and for the group permissions it uses. If you have the technical expertise, you might choose to run MX in a different user, if your weather station type allows MX to run in a different user. If so, replace the "root" in its two locations. (Please note some weather stations require other changes outside this file before Cumulus can make contact, one example is discussed on support forum here, but there are other topics that may be relevant).

You may also wish to add an extra line after the "Group" line ExecStartPre=/bin/sleep 5, this is to delay the starting of MX by 5 seconds while other services start (on a reboot of your computer) that might affect MX. (For some users, change 5 into 10, it all depends what else is being started).

Look at the rest of the file, the [Unit] part.

For releases 3.8.4 to 3.15.0: you will see one reference to network-online.target in After=network-online.target.

For release 3.15.1 build 3170 (19 March 2022) onwards: you will see an extra line Wants=network-online.target

If you are a technical user, you might decide to edit the [Unit] part of the file, you have to decide what is needed in your context, only you know what other services are started by systemd on your computer, you can list all items using something like systemctl list-unit-files to see the services, but you still need to understand what each does.

If your computer has online access, then it can look up the correct time online and adjust its clock. However, it might not even try to do that for say 10 minutes after being booted, and so there may be a benefit in making MX wait until after systemd has asked for the time to be synced, and asked that the local file-system is made ready so MX can read/update/store files. To achieve this, you might choose to add a blank line after Documentation=https://cumuluswiki.org/a/Main_Page and in that blank line, type Requires= time-sync.target local-fs.target. Using "Requires" ensures these requesting events have happened before MX can start, if they fail, MX will not be started, this example has not specified a time that MX should wait for the other services to start!

For that time-sync.target to work, you need to enable, by creating the symbolic links needed, the appropriate services outside this edit:

sudo systemctl enable --now systemd-timesyncd.service
sudo systemctl enable --now systemd-time-wait-sync.service


Here is a quick explanation of all entries in this UNIT section:

  1. Entries
    • The terminology "After" tells "systemd" that what is named can be started after MX, in this case it does not guarantee that the network service (to send data to a remote web server) will be started
    • The terminology "Wants" tells "systemd" that what is named is wanted now, i.e. try to start before MX, but still start MX even if the starting of the network service fails.
    • The terminology Requires tells "systemd" that the "cumulusmx" service should not be started until the services specified on that line have successfully started
      1. The local-fs.target specifies that the cumulusmx service requires the file service to have started, i.e. checks your computer can read files before it attempts to start the cumulusmx service
      2. The time-sync.target specifies that the cumulusmx service requires the computer to have synced with some time source (see notes below), which could be useful if your weather station type does not time-stamp readings stored in the console, and you want to ensure MX reads correct time from your computer

Don't forget to save the file under a new name, and copy it as instructed in previous subsection.

Technical Notes only relevant to Raspberry Pi

This Wiki page has tried to avoid being too specific to particular hardware, but to avoid misunderstanding the last subsection, a little does need to be said to justify the claim that only technical users, who understand all the other changes needed, should make changes mentioned there.

A standard Raspberry Pi computer does not include a clock chip. Instead one of the packages it loads as a service on booting is called "fake-hwclock", and that sets the clock to what the date/time was when it was last running, irrespective of how many days/hours it has been off. That counts as a time sync for the purposes of instruction specified above. You can buy and fit a real-time clock chip, and configure your computer to use that, but even that RTC will only keep time when it is kept powered, and even then it will drift off unless periodically able to be corrected by a time from internet.

The issue is your Cumulus MX on restarting will skip the catch-up of historic data (should your weather station settings make that available), because the dummy clock makes MX think the computer was not off for long. Subsequent measurements will then get logged against the wrong time until the correct time is found on the internet (NTP). At that moment, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day. In my experience it can be anything from 2 minutes to 10 minutes after switch on before my RPi does a time sync over the internet.

You might expect sudo systemctl disable fake-hwclock.service (or remove the service, and modify the scripts that call it) could ensure the computer (if online) has to get a time found on the internet (NTP). Nothing is as simple as it might seem!

Commands to do actions on a service

You will need to start (or restart) MX after you have defined (or redefined) the service as instructed above. The specific commands to use with MX service are at systemctl_commands, here I simply repeat the basic commands that can be used with any service (status, enable, disable, start, stop, and restart).

Don't forget you may need to type sudo systemctl daemon-reload to tell "systemd" that it needs to reload all service definitions whenever either one has changed, or a new one has been added.

In all these commands, just replace [service_name] with cumulusmx (or enter the name of another service).

  • sudo systemctl status [service_name]
    • (displays whether named service has started, whether it has failed, whether it has stopped, also whether enabled, extra information will be added should status change)
    • type the single character "q" to quit updating status display and return to prompt
  • sudo systemctl enable [service_name]
    • (typed just once, and service named will automatically start when your Linux computer is booted)
    • the confirmation message says a link has been created
  • sudo systemctl disable [service_name]
    • (used when you don't want an automatic restart of the named service)
  • sudo systemctl start [service_name]
    • (will start the named service)
  • sudo systemctl stop [service_name]
    • (will stop the named service)
    • Closing MX with "cumulusmx" as the named service this way does a proper shutdown
  • sudo systemctl restart [service_name]
    • (issues a stop, then start, command to named service)
    • You can upgrade MX by installing new files over the existing ones, while MX is left running, and then use this command to pick up new release with minimum downtime.