Cumulus Wiki

MX on Linux: Difference between revisions

MX on Linux (view source)

Revision as of 17:50, 13 March 2022

20,878 bytes added ,  17:50, 13 March 2022
m
Some resequencing of content, with a few corrections and a few simplifications
m (Some resequencing of content, with a few corrections and a few simplifications)
Line 1: Line 1:
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
<big>This page needs further contributions, can you help?</big>
{{Template:WorkInProgressBanner}}


'''This page focuses on aspects of MX that are specific to the Linux operating systems.'''
=Are you on the right Wiki page?=
 
{{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.
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.
==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 page|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.
=For those using Raspberry Pi computers=
As described [[Raspberry Pi computer page|on this Raspberry Pi computer Wiki page]], there are significant advantages in using a Raspberry Pi computer to run Cumulus MX, such as it being simple to use, it saving energy costs, and it avoiding the dreaded regular rebooting by Microsoft's Windows Update.
You have two choices:
CHOICE ONE: ‘’’Create a micro-SD card that has everything on it to load a kernel onto your RPi computer and run MX’’’
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).
That image contains:
#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 other computer to access the Wizard in the [[MX_Administrative_Interface#Station_Settings|admin interface]]; this will define station type, your choice of units, and some other settings, before MX can start recording data from the connected weather station.
* 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 folder|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 on another day if you want to learn more.
CHOICE TWO: ‘’’Load the software packages individually’’’
Please read on, this page will tell you all you need to know.


{{TOCright}}
{{TOCright}}
Line 9: Line 53:


This page:
This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the options available for installing the 3 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
** CumulusMX.exe
** ExportToMySQL.exe
** CreateMissing.exe
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, how to add the Mono repository to your system, and how to upgrade MONO
* explains how to run Cumulus MX either interactively or as a service
* briefly indicates instructions for configuring MX using the administrative interface
* explains the few key Linux commands it uses
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* the content tries to compromise between three types of readers:
* 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
** to be useful to anyone who has never used MX (regardless of their previous Linux experience)
* describes the various options available to run MX
** to assist anyone who knows Cumulus, but has not run MX on Linux before
** to add a little technical information for those who wish to tailor their Cumulus MX operation
* describes the optional parameters you can add when starting MX
* describes the optional parameters you can add when starting MX
* describes the other executables  
* briefly explains how to use the other executables  


There are various related pages to get more information:
There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*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
*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
*[[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
*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 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.
Line 34: Line 85:
* 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==
 
Linux is available based on a multitude of different kernels (the building block for the operating system), on a multitude of devices.


It is hoped that contributions to this page will be made by Cumulus users with a range of such devices. The page has been originated by a contributor using the Raspberry Pi Operating System (this is based on Debian, one of the Linux kernels). Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].
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?==
==What do people think about MX on Linux?==
Line 51: Line 97:
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.


Microsoft has had a deliberate policy of being different to traditional computers mostly based on UNIX, and the [[MX_on_Windows_OS|Running Cumulus MX on Microsoft Windows]] page covers those aspects of MX that are specific to Personal Computers running Microsoft's Windows Operating System.
Microsoft has had a deliberate policy of being different to traditional computers (all others are mostly based on UNIX).  This is why this Wiki gave up attempting to have one page covering MX regardless on which operating system was used, instead creating this page, and the [[MX_on_Windows_OS|Running Cumulus MX on Microsoft Windows]] page with very little duplicated text.  
 
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.
 
=For those using Raspberry Pi computers=
 
You have two choices:
 
CHOICE ONE: ‘’’Create a micro-SD card that has everything on it to load a kernel onto your computer and run MX’’’
 
The developer has created [[Software#Raspberry_Pi_Image|an image you can download]].
 
That image contains:
#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.
* 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.
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 Microsoft Windows.


CHOICE TWO: ‘’’Load the software packages individually’’’
Please read on, this page will tell you all you need to know.


= Do you have a Operating System? =
= Do you have a Operating System? =
Line 89: Line 110:
=Do you know how to install packages?=
=Do you know how to install packages?=


If you already know how to install packages, your computer has the pre-installed image, or you have installed MX before, you will want to skip the sub-sections that follow on here, and continue reading at [[#Cumulus packages]].
This is one of several places on this page where a novice can skip on to step-by-step instructions (in this case continue reading at [[#Cumulus packages]]), but others may want to read a little technical detail to understand what they are doing.


Otherwise, here is a short technical digression to explain the commands.
Read on for a short technical digression to explain the commands for how to install and update software packages (the same commands can be used to install software for [[Your_Own_Server]], or to read the SQLite databases used by MX [[Cumulusmx.db]] and [[Diary.db]]).


==The various components to commands for installation==
==The various components to commands for installation==
Line 101: Line 122:
===sudo===
===sudo===


By default, a Linux user will log in as a default user with limited rights.  
By default, a Linux user should log in as a default user with limited rights.  


For example, the Raspberry Pi Operating System has a single default user "Pi", with their home folder that can be referenced as "~".
For example, the Raspberry Pi Operating System has a single default user "Pi", with their home folder that can be referenced as "~".


In the '''apt''' context here, those limited rights allow use of actions that just read (such as '''search''', ''show'').
The limited rights mean that a standard user cannot even see (read) some files, cannot execute some commands, and cannot edit (write to) some files.  For full access to files, the <code>sudo</code> instruction gives you (just for the command that follows) the same read/write/execute access that the system root user has.


However, for any action involving writing (such as '''install''', ''full-upgrade'', '''update''', ''autoremove''), the package manager needs additional rights, and we prefix the "apt" with '''sudo'''.
For software packages, the command to be used is <code>apt</code) to invoke the package manager, followed by an "action" and then optionally by the "package name".  In that context the default user's limited rights allow use of actions that just read (such as '''search''', ''show''). However, for any action involving writing (such as '''install''', ''full-upgrade'', '''update''', ''autoremove''), the package manager needs additional rights, and we prefix the "apt" with '''sudo'''.


: Elsewhere on this page you might notice [[#Running any MX executable with a terminal session left open|'''cd''']] can move round the file structure (without a "sudo"), but "sudo" is used with [[# Installing/Configuring the MX service and the -service parameter|'''cp''']] as that writes a file.
: Elsewhere on this page you might notice [[#Running any MX executable with a terminal session left open|'''cd''']] can move round the file structure (without a "sudo"), but "sudo" is used with [[# Installing/Configuring the MX service and the -service parameter|'''cp''']] as that writes a file.


Novice readers should exercise caution, because using "sudo", changing folder/file ownership, adding write rights, and even using "-R" or "-y" flags, can all make it very easy to inadvertently do the wrong action, even perhaps delete vital folders/files.   
Novice readers were advised to skip this part of this Wiki page.  That is because everyone should exercise caution before using "sudo", changing folder/file ownership, adding write rights, and even using "-R" or "-y" flag. The use of "sudo" makes it very easy to inadvertently do the wrong action, in the worst case making your computer unusable because it can delete vital folders/files because of something as simple as a typo.   


: '''For technical readers only''', "sudo" is further explained later [[#su_and_sudo]]). Briefly,  "sudo" gives super-user (root) rights when executing the instruction that follows for actions on files that are either not in the current user's ownership, or for which the current user lacks necessary (read, write, execute) permissions.
: '''For technical readers only''', "sudo" is further explained later [[#su_and_sudo]]).


===apt===
===apt===


The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   
The second part of any software installation command is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   


If you are looking online for a tutorial on how to install packages, you might see “apt-get” or "apt-cache" used in examples they quote. It should be safe to replace these older package managers with "apt". I have included [[#Package Manager – a brief technical aside|a little technical explanation]] at the end of this page if this really worries you.
If you are looking online for a tutorial on how to install packages, you might see “apt-get” or "apt-cache" used in examples they quote. Don't copy those examples directly, it should be safe to replace these older package managers with "apt". I have included [[#Package Manager – a brief technical aside|a little technical explanation]] at the end of this page if this really worries you.


===install===
===install===


The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.
The third part of our installation instruction is the action parameter. In our current context this is “install”, which tells our package manager what we are trying to do.


Here is full list of what can follow “apt”, as we will use some of the alternatives later:  
Here is full list of what can follow “apt”, as we will use some of the alternatives later:  
Line 139: Line 160:
|-
|-
! scope="row"|upgrade
! scope="row"|upgrade
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions.  (You cannot upgrade the actual kernel within the operating system with this instruction, so there is no necessity to reboot your Linux computer).
| Once your "source list" is up to date, <code>sudo apt upgrade</code>, followed by a package name, will for the named packages download any newer versions now available in repositories. If you include <code>-y</code> flag, or you answer 'Y' or 'y' to the prompt, then the package manager will continue, and actually replace those packages that are already installed on your computer with the downloaded newer versions, making them available for immediate use.  (You cannot upgrade the actual kernel within the operating system with this instruction, so there is no necessity to reboot your Linux computer).
|-
|-
! scope="row"|full-upgrade
! scope="row"|full-upgrade
| Once your "source list" is up to date, the instruction "full-upgrade" can be included after "apt". The advantage of "full-upgrade" over the simple "upgrade" is that it picks up dependencies, and so results in more components being upgraded. (Again, this does not affect kernel and does not require a computer reboot).
| Once your "source list" is up to date, the instruction "full-upgrade" can be included after "apt". The advantage of "full-upgrade" over the simple "upgrade" is that it picks up dependencies, it ensures that every package is able to work with all other packages, and so normally results in more components being upgraded. (Again, this does not affect kernel, and does not require a computer reboot).
|-
|-
! scope="row"|autoremove
! scope="row"|autoremove
| The instruction "autoremove" can be included after "apt" to check all components in the packages you have installed onto your computer, and remove any components that are not needed by the dependencies of the packages you are using. A download for software frequently includes some components specifically for their software to work with particular other optional packages.
| The instruction "autoremove" can be included after "apt" to check all components in the packages you have installed onto your computer, and remove any components that are not needed by the dependencies of the packages you are using. A download for software frequently includes some components specifically for their software to work with particular other optional packages, and therefore installs more than you actually need.


When we install mono-complete later, the other packages we install do not need every component that has installed, and “autoremove” can be used to tidy up when all our installations are finished.
When we install mono-complete later, the other packages we install do not need every component that has installed, and “autoremove” can be used to tidy up when all our installations are finished.
|-
|-
! scope="row"|remove
! scope="row"|remove
|If you want to remove just one component manually, after "apt", use “remove” followed by the name of component you no longer want
|If you want to remove just one component manually, use <code>sudo apt remove</code> followed by the name of component you no longer want
|-
|-
! scope="row"|purge
! scope="row"|purge
| To remove any installed package and delete all related configuration files, after "apt" type "purge" then the name of the package we no longer want
| To remove any installed package and delete all related configuration files, use <code>sudo apt purge</code> then the name of the package we no longer want
|-
|-
! scope="row"|search
! scope="row"|search
|To search in repositories in source list for a package you specify after “search”
|To search in repositories in source list for a package you specify after <code>apt search</code>
|-
|-
! scope="row"|show
! scope="row"|show
|To show any information available about a package that you name after the “show”
|To show any information available about a package that you name after the <code>apt show</code>
|}
|}


Line 166: Line 187:
The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.
The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.


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


=== Name ===
=== Name ===
Line 196: Line 217:
# Next, stop, and restart, the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>.  
# Next, stop, and restart, the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>.  
# That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.
# That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.
The actual swapfile size to choose depends on the amount of RAM installed on your computer, if you want to know more (because there is some conflicting advice), then do an online search to discover the RAM size on your device and the advice on suitable swapfile size.


=== USB HID ===  
=== USB HID ===  
Line 225: Line 248:
===Add the Mono repository for a Raspberry Pi===
===Add the Mono repository for a Raspberry Pi===


The two Mono repositories listed here are specific to the 2017 and 2019 releases (respectively) of the operating system for a Raspberry Pi computer.  These are taken from  [https://www.mono-project.com/download/stable/#download-lin-raspbian download-lin-raspbian].
The two Mono repositories listed here are specific to the 2017 and 2019 releases (respectively) of the operating system for a Raspberry Pi computer.  These are taken from  [https://www.mono-project.com/download/stable/#download-lin-raspbian download-lin-raspbian].  If your Rasberry Pi is running the 2021 release (11 = Bullseye), or whatever is available when you are reading this page, please refer to that external link for more recent instructions.


# the first line (in each case) installs a certificate
# the first line (in each case) installs a certificate
Line 260: Line 283:
: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.
: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.


Please note that a particular MX build might specify it needs a particular version of Mono.  Hence, although normally you can upgrade any (CumulusMX.exe, ExportToMySQL.exe, CreateMissing.exe, proposed CreateRecords) cumulus package without upgrading Mono, sometimes you will need to install Mono again.
Please note that a particular MX build might specify it needs a particular version of Mono.  Hence, although normally you can upgrade any (CumulusMX.exe, ExportToMySQL.exe, CreateMissing.exe, proposed CreateRecords) cumulus package without upgrading Mono, sometimes you will need to upgrade Mono, and that means following above install instructions again.


The latest release of Mono can always be downloaded from [https://www.mono-project.com/download/stable/#download-lin] for a variety of Linux distributions:
The latest release of Mono, for a variety of Linux distributions, can always be downloaded from [https://www.mono-project.com/download/stable/#download-lin]:
# follow step 1 there,  
# follow step 1 there,  
# but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’
# but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’


The complete mono package includes a component (mono-xsp4) that creates a simple web server to run ASP.NET 4.0 applications.  MX does not need this, so type <code>sudo update-rc.d mono-xsp4 disable</code>.
The complete mono package includes a component (mono-xsp4) that creates a simple web server to run ASP.NET 4.0 applications.  MX does not need this, so type <code>sudo update-rc.d mono-xsp4 disable</code>, to stop it being used (without needing to do a <code>sudo apt remove</code> followed by the name of component you no longer want).


=Cumulus packages=
=Cumulus packages=


Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.  If you are using the [[Software#Cumulus_MX|pre-built disc image]], then (unless the MX release version included in your image is an old one) you should skip the instructions for installing "CumulusMX" itself.
Welcome back anybody who has skipped the technical sections above, everybody needs to read this section.
 
Note use of plural in section name above, the following sub-sections will install various packages produced by developer Mark Crossley.  If you are using the [[Software#Cumulus_MX|pre-built disc image]], then (unless the MX release version included in your image is an old one) you should skip the instructions for installing "CumulusMX" itself.


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


Each release is presented as a zip.
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).


The download and unzip procedure is exactly same on your Linux computer, and on a Windows PC.  So if you have two devices available, you can download on either device, and if it is not the computer you want to install on, you can use a file transfer package to move the files between devices, or use a drive (or even a memory card) with a partition formatted so that you can read it on both devices.  Windows and Linux partitions are formatted in different ways. While it is likely that Linux can read a Microsoft formatted partition, Microsoft Windows can never read a Linux formatted partition.
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 dropdown) 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 containg 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


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


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 menu item (or two menu items) to select the file and unzip it.
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?==
==Where to install all packages?==
Line 289: Line 325:


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).
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).
===MX can severely damage storage===
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) or external drive (with a spining disc and moving head) 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).
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 /var/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 '''/var/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.
===Creating the CumulusMX sub-folder===


* You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir EXISTING PATH/CumulusMX</code> first (note that EXISTING PATH is explained above and always starts with a slash “/”).
* You can create sub-folder called “/CumulusMX” as you unzip a MX release, or you can type <code>sudo mkdir EXISTING PATH/CumulusMX</code> first (note that EXISTING PATH is explained above and always starts with a slash “/”).
Line 339: Line 386:
Upgrading to a new MX release is explained [[Updating_MX_to_new_version|here]], but basically follow instructions above, and install over your existing files.  The alternative is to install in a new folder (or rename the old one), and copy across files not in the release from old location to new location.
Upgrading to a new MX release is explained [[Updating_MX_to_new_version|here]], but basically follow instructions above, and install over your existing files.  The alternative is to install in a new folder (or rename the old one), and copy across files not in the release from old location to new location.


== Report and data files to copy across from any previous Cumulus location ==
==Changing location of Cumulus==
 
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.
 
 
==Moving from Microsoft Windows to Linux==
 
Skip the following sub-sections if this is your first installation of MX, or if both the old location and the new location for MX are on Linux computers.
 
===Line terminators in .txt files===
 
If you are a novice to computers, skip this sub-section and the next, go directly to [[#File Names & Paths]].
 
You need to have some technical understanding to do an action that might encounter the issues discussed here. For normal MX usage, line terminators do not matter.
 
If you are moving from Microsoft Windows to Mac OS, 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 (Carriage Return).  Cumulus can cope with both approaches for existing files, but will create new files correctly for Mac OS.
 
If you are moving from Microsoft Windows to Linux, be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed). Cumulus can cope with both approaches for existing files, but will create new files correctly for Linux.
 
If you run your Linux computer in a headless mode, accessing its files by a remote terminal session, be aware that the line terminator used by the remote computer may be applied to files affected by whatever command you do remotely. Equally, running a Cumulus executable (MX or one of the utilities) may create new files with the wrong end of line terminator. The latest releases of both "CumulusMX.exe" and "CreateMissing.exe" have been amended to create their new files with the same line terminators as are used by any existing files they read.  Older releases adopted whatever line terminator was used by the device from which the executable run instruction was issued.
 
===Reading Cumulus files using your JavaScript, your PHP scripts, and packages from third-parties===
 
If you have written a script to work for a Microsoft Windows device, it might need editing to still work in a Linux environment.  If you use a third-party provided package on your Linux computer, you may need to check if the author has coded it assuming it will be run on Microsoft Windows.
 
It is not appropriate for this Wiki page to go into full technical detail, but here is a quick summary of how unexpected line terminators can stop scripts working:
* If the script expects the Linux LF, and finds CR LF, then the final field of each CSV line has an invalid character in it, so your script will not be able to understand that field as a numerical value (or time-stamp).
* If the script expects the Mac OS CR only, and finds CR LF, then after the first line, each subsequent line starts with a “LF”. Most scripts will be processing [[Daily Summary|dayfile.txt]], [[Standard log files|MMMyylog.txt]], or [[Extra Sensor Files]], all of which have date as first field, and the "LF" prefix stops that field being seen as a date.  In the worse case scenario, it might mean the script sees empty lines between each valid line.
* If the script expects CR only, but just finds LF, the script will believe the whole file is just one line, and the fields before and after the LF will be treated as a single field (merging the last value of one line with the date that should be on next line) so your script will not be able to understand that field as a numerical value (or time-stamp).
* If the script was written for a Microsoft Windows environment, it will expect CR LF, but might be confused if the end of line is different
 
===Editing Cumulus files outside MX===
 
If you try to edit a file outside MX, the application you choose to use will normally adopt the line terminators used by the device on which you are using the application.
 
Any good quality editor should by default save the file with the same line terminator as it had before.
 
If you are using an editor designed for editing computer files, it should have an option to [[#Changing line terminators|choose which line terminator you need]].
 
===Changing line terminators===
 
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).
 
‘’’Geany’’’ is a programming development editor available for Microsoft Windows, but included by default on some Linux systems including Raspberry Pi, that can do this ('''Document''' menu, -->> '''Select Line Endings''').
 
''Notepad++'' is another editor available for multiple operating systems ('''Edit''' menu -->> '''EOL conversion'''). 
 
Both have capabilities to make such changes on either the single file that has focus, or all loaded files.
 
There are many more editors designed for programmers, and you may use one that is not listed above, so you may need to search for the relevant option.
 
 
===File Names & Paths===
 
Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
All Unix file names are Case Sensitive, and the separator is "/". 


All the (optional) files in the [[Reports folder]] can be copied across from a previous installation. If your previous installation was not on Linux, see [[#Line terminators in .txt files]]
Microsoft Windows Operating Sytem deliberately chose to be different and uses "\".  That causes a problem because "\" is also used to denote a control character (e.g. '\t' is horizontal tab, '\n' is new line) and so Unix based computers will strip out any two character sequences they recognise as representing control characters from any file paths they read.


<br>
This could be applicable if you were using Extra Web files functionality in your old Cumulus installation on a Microsoft Windows computer.  You need to go into the settings page for  '''Extra web files''', and edit each local path for it to work on your Linux computer.  If you have followed advice on [[Customised templates]] page, you will be using a location outside the MX file structure, so you knew you had to change local file paths anyway for your new MX installation.


Whilst you should copy ALL the files in the [[data folder]], from any old installation into the new installation, there are several extra considerations:
Here is an example changing the case and the separators where the path is within the MX file structure: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.
* '''Your new MX installation will ignore any entries prior to the MX Start Date''' in [[Monthly log files]], such as [[Standard log files]], and [[Extra Sensor Files]]:
 
**  See [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, edit using ''Station Settings → Common Options → Advanced Options → Records Began date''
===data sub-folder===
* Be aware your new installation has to use the same "locale" as the old installation, or MX will struggle as the locale affects how new lines are stored, and how MX expects old lines to have been stored.  
 
* Microsoft Windows uses different line terminators, see [[#Line terminators in .txt files]], although MX should cope, any third party routines reading your data files will probably not accept a line terminator change.
In general, any file in the old [[Data folder|data sub-folder]] should be copied into the new location.  This might be a straight "copy and paste", it might be a "file-transfer", or you might use a portable drive to carry the files from the old device to the your Linux computer's MX folder.
* If your previous Cumulus installation was of the legacy software, version 1.9.4, or earlier, then you need to do a lot of reading:
 
If your previous Cumulus installation was of the legacy software, version 1.9.4, or earlier, then you need to do a lot of reading:
** [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
** [[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
** [[: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
** [[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  
 
A further complication is that the legacy Cumulus software would read any [[:Category:Files with Comma Separated Values]] found in the [[Data folder|data sub-folder]], but MX ignores any of those files with dates prior to the date specified in the [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, edit this date using ''Station Settings → Common Options → Advanced Options → Records Began date''.  If you have set up MX at a different location to where it was before, then you may need to do the above edit, unless the new MX release is able to read the [[Cumulus.ini]] used in the old location - see [[#Configuration Files to copy across from any previous Cumulus installation]].
 
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).  At time of writing this, the main MX developer has proposed that the format of files with comma separated values will be fixed, so all dates will use one standard format, all numbers will use decimal points, and the field separating character will be fixed, but no public MX release has this restriction yet.
 
===web sub-folder===
 
If you are using the default web pages, you will need to create a lot of symbolic links here pointing to the temporary folder you set up in RAM if you read the technical information earlier.
 
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):
 
<code>sudo ln -s /var/tmp/availabledata.json EXISTING PATH/CumulusMX/web/availabledata.json</code>
 
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
* "EXISTING PATH" is defined elsewhere, but basically it starts with a "/" and defines the path to get to where "CumulusMX" is a sub-folder.
* The text "availabledata.json" is just one file in the set of files linked from [[:Category:JSON Files]].
 
===Report sub-folder===
 
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.
 
If your previous installation was not on Linux, see [[#Line terminators in .txt files]], because you might want to either regenerate all these files, or to open them all in an editor that can alter the line terminator.
 


==Configuration Files to copy across from any previous Cumulus installation==
==Configuration Files to copy across from any previous Cumulus installation==
Line 360: Line 492:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file
*[[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
Just copy the existing files from old to new installation, if
# Your locale is still the same
# 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)
# All files on your new install are in same paths as on your old install (some settings involve specifying paths)
# Your old installation has a relatively recent MX release (compare the "y" in 3.y.z,between old and new installation,  a difference of more than 1 means you do not have a recent release)
# Your old installation 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 Linux computer (not a computer running Microsoft Windows Operating System)
# 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.




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


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


If your old file contains any [[Cumulus.ini (Cumulus 1)|legacy read-only]] parameters not yet converted into advanced settings, or any [[Cumulus.ini (MX 3.0.0 to 3.7.0)|MX read-only parameters not yet converted into advanced settings]], you may need to manually add such missing parameters back into new file by stopping MX (after finishing all the settings you can configure in the interface), doing an external file edit, and then restarting MX
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:
| The content of "samplestring.ini" is changing as MX is developed:
* Therefore, your existing “strings.ini” might need to be modified.  
* Therefore, your existing “strings.ini” might need to be modified.  
Line 399: Line 537:
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 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.


==Moving from Microsoft Windows to Linux==
=Running MX=
 
===Line terminators in .txt files===


If you are a novice to computers, skip this sub-section and the next, go directly to [[#File Names & Paths]].  
Please read the appropriate sub-sections within this section, because the advice depends on whether MX has been run before, and how you want to run it.


You need to have some technical understanding to do an action that might encounter the issues discussed here. For normal MX usage, line terminators do not matter.
==Your first run of  MX on Linux==


If you are moving from Microsoft Windows to Linux, be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed). Cumulus can cope with both approaches for existing files, but will create new files correctly for Linux.
Once you have got all the files sorted out as described above, you need to run MX.


If you run your Linux computer in a headless mode, accessing its files by a remote terminal session, be aware that the line terminator used by the remote computer may be applied to files affected by whatever command you do remotely. Equally, running a Cumulus executable (MX or one of the utilities) may create new files with the wrong end of line terminator. The latest releases have been amended to match existing files, when they create a new file to replace an old file (or because that file is missing/corrupted).
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.


If you try to edit a file outside MX, the tool you choose to use might be able to detect that it is getting Microsoft files, and discard the extra end of line character.
Information about settings is on other Wiki pages ([[MX Administrative Interface]] and [[Cumulus.ini]]), so not much needs to be said here, except that you won't be able to '''Update Alarms''' without having first enabled and defined "Email Server Settings" on the "Internet settings" page.  The complication is that you need to go into the "Alarm Settings" page and use '''Update Alarms''' to set what is displayed on the "dashboard" page of the interface to what suits your weather staion type!


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


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


===Changing line terminators===
The simplest instruction to run Cumulus MX  is <code>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</code>. 
* This is two commands issued together, the first changes the working folder, the second actually starts the main executable


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).  
Before running MX, look up the section later that talks about optional parameters:
<code>sudo mono CumulusMX.exe [optional parameters]</code>


‘’’Geany’’’ is a programming development editor provided on some Linux systems including Raspberry Pi, that can do this ('''Document''' menu, -->> '''Select Line Endings''').
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". After that you can choose to close the terminal window.


Notepad++ is another editor available for multiple operating systems ('''Edit''' menu -->> '''EOL conversion''').   
Note that if you use a different computer to access the computer that MX runs on, what has been called "terminal window" above might be called a "Command window", a "Powershell window" or some other name.  Using control sequeNextnces on a remote session may not always be straight forward. In theory, Cumulus MX will also close tidily if you close a remote terminal window, but this may not always be true.


Both have capabilities to make such changes on either the single file that has focus, or all loaded files.


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


===File Names & Paths===
== Running another executable with a terminal session left open ==


Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Open a  terminal window, then navigate to the folder where you have installed the 3 Cumulus executables:
Linux file names are Case Sensitive, and the separator is "/" Vs "\".


This could be applicable if you are using Extra Web files.
<code>cd EXISTING PATH/CumulusMX</code>


Here is an example changing the case and the separators: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.
Next decide which executable you want to run, for [[Software#Create_Missing|Create Missing utility]], that link takes you to a section of this Wiki where there are links to more information about the utility, to run it type:


=Running MX on Linux=
<code>sudo mono CreateMissing.exe</code>


This section explores the optional parameters, and then covers 2 ways to run MX:
To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, as explained in links from that link.
# as a service and
# interactively with terminal window left open.


As a side-note, some weather station types require MX to be run with '''root''' rights, this is why ''sudo'' is included in each example command, but if you have technical knowledge and know your weather station can be run with default user, you can omit the ''sudo'' provided your user has ownership of all folders and files used by MX.
If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "EXISTING PATH/CumulusMX" folder and you may be able to omit the "sudo".


== Optional parameters to add to the instruction to run the MX engine ==
Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running.


This list of parameters covers every parameter, if you are using the latest release skip the historic 3.0.0 sub-sections.
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.


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


=== -port parameter for changing Port ===


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


=== -lang parameter for changing Locale ===
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.


Individual computers may have different default for their locale. The forum reported an issue with OS X with its default US locale even if that is not your locale.
Running interactively allows MX to display error messages to you, and to confirm when it is running normally. 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.


As MX starts its output (to diagnostic log and to any interactive terminal window) says which locale is being used, '''Current culture: English (United States)'''.  That default locale will relate to the one your computer had when mono is installed, as it is mono that tells MX all the locale settings. If you notice MX starting with wrong locale, issue the correct instruction to close MX.


You can use a '''-lang''' parameter to change the locale as you restart MX. For example, in the UK, type:
===Commands to start, stop, or restart (stop and start in one command) MX as a service===
:<code>sudo mono CumulusMX.exe -lang en-GB</code>


Other locale examples:  '''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'''.
You will need to start (or restart) MX after you have defined (or redefined) the service as instructed in next sub-sections.  The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]], here I simply repeat the basic commands that can be used with any service (start, stop, and restart), just replace [service_name] with either '''cumulusmx''' or the name of another service.


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.
* sudo systemctl start [service_name]
* sudo systemctl stop [service_name]
* sudo systemctl restart [service_name]


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.
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.  Change the "enable" into "disable" if you don't want an automatic restart, and change the name of the service to apply these commands to another service.


=== Installing/Configuring the MX service and the -service parameter===
===Defining "cumulusmx" service for "systemd"===


The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>
The MX release distribution you downloaded and unzipped earlier includes a file that can be used as a starting point for the service definition.  Find this file at ''EXISTING PATH/CumulusMX/MXutils/linux/cumulusmx.service''.


You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.
For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement].
   
   
====All users - mandatory edit of service file====
====All users - mandatory edit of service file====
For recent releases, (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement]):
 
#There is a task to do just once to configure the service
# Open the file at ''EXISTING PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor.  On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <code>sudo nano cumulusmx.service</code> to edit the service configuration file
# Within the provided file you should find a [Service] section:
# Within the provided file you should find a [Service] section:
<pre>[Service]
<pre>[Service]
Line 495: Line 624:


There are some edits needed to that section:
There are some edits needed to that section:
# Everyone must edit the line that begins with '''ExecStart='''
# ''Everyone must edit'' the line that begins with '''ExecStart='''
#* The mandatory change is to replace '''/home/install''' by what you have selected for EXISTING PATH
#* The '''mandatory''' change is to replace '''/home/install''' by what you have selected for EXISTING PATH
#* An optional change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections above
#* An '''optional''' change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections later, the example below assumes you want to add "-debug"
# The new line will then read something like '''ExecStart=/usr/bin/mono-service -d:EXISTING PATH/CumulusMX CumulusMX.exe -service -debug'''
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX)
# 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 "sytemd" 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
 
Novice users can skip the next sub-section, but if they are using a standard Raspberry Pi with some types of weather station, there is a technical change mentioned there that can be implemented to ensure that Cumulus MX does a historic data catch up if that is possible.
 


====Technical users - optional edits====
====Technical users - optional edits====


Novice users are advised to skip this sub-section.
# Open the file at ''EXISTING PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor.  On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
# Within the provided file you should find a '''[Unit]''' section:
#* Recent releases of MX have a line saying <code>After=network-online.target</code>, this was not included for all past releases
#** This line instructs "systemd" to ensure that the network service is started after the "cumulusmx" service i.e. it requests there is a connection by LAN or Wireless to the internet.
#* Technical users may wish to insert this new line before the above existing line: <code>Requires= time-sync.target  local-fs.target</code>
#**# 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 either a real-time clock chip, or the time found on the internet, i.e. this will ensure that Cumulus obtains the correct time from the computer to control all its actions
#**#* If you are using a weather station type that does not time-stamp the reading it supplies to a Raspberry Pi, adding that target reference is important
#**#* A standard RPi does not include a real time clock chip (it can be added via connections available), therefore when the RPi boots it initially uses a dummy clock, and this sets the time to when the RPi was last running.
#**#* That means without this target being included, your Cumulus MX on restarting will think the time has hardly changed, and skip the catch-up of historic data (should your weather station settings make that available). It also means that, at least means some, measurements have been logged against the wrong time.
#**#* When the Raspberry Pi does do a time-sync, 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.
 
Novice readers are advised to let Cumulus MX use the root user, following the suggestion below to change user/group entries may cause all sorts of problems and needs a good level of technical understanding to follow through all implications.
 
As a side-note, some weather station types require MX to be run with '''root''' rights, this is why ''sudo'' is included in each example command, but if you have technical knowledge and know your weather station can be run with default user, you can omit the ''sudo'' shown in many commands, provided your user has ownership of all folders and files used by MX. The default service definition file assigns the ownership of all files that MX creates to the root user, this means you may not be able to edit Cumulus files outside MX because you are by default a user with restricted rights.  


In the ''[Service]'' section of same file:
# Within the provided file you should find a [Service] section (see the contents in previous sub-section)
# Technical users might want to edit the '''User=root''' line so that the service will run as a different user, just change the name that appears after the "=" sign.
# Technical users might want to edit the '''User=root''' line so that the service will run as a different user, just change the name that appears after the "=" sign.
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX)
# 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 "sytemd" 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
== Optional parameters to add to the instruction to run the MX engine ==
This list of parameters covers every parameter, if you are using the latest release skip the historic 3.0.0 sub-sections.
Note that you ''may'' need to supply your root password after typing any 'sudo ...' command line if the instruction changes something set by another package (e.g. changing the locale for MX from the locale set by mono). The system will prompt you for this if it is needed.
=== -port parameter for changing Port ===
When Cumulus starts, it will display the URL of the interface where you change the settings. he web server that MX initiates runs on port 8998 by default; if this is not suitable for some reason you can change it using the '-port' parameter on the command line if running interactively, or within the service definition file (see [[#All users - mandatory edit of service file]] if running as a service.
e.g. to use port 9999 instead:
<pre>sudo mono CumulusMX.exe -port 9999</pre>
=== The -service parameter===
You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.


In the '''[Unit]''' section  of same file:
See [[#Defining "cumulusmx" service for "systemd"]] and [[#All users - mandatory edit of service file]] for where "CumulusMX.exe -service" is used.
* Depending on which release of MX you are using, you may, or may not, have a line saying <code>After=network-online.target</code>
* Technical users may wish to edit this line into <code>After=network-online.target local-fs.target time-sync.target</code>
*# The '''network-online.target''' specifies that the ''cumulusmx'' service will only start '''After''' the network service has started, i.e. there is a connection by LAN or Wireless to the internet.
*# The '''local-fs.target''' specifies that the ''cumulusmx'' service will only start '''After''' the file service has started, i.e. your computer can read files
*# The '''time-sync.target''' specifies that the ''cumulusmx'' service will only start '''After''' the computer has synced with either a real-time clock chip, or the time found on the internet, i.e. will ensure that Cumulus obtains the correct time from the computer to control all its actions


====Completing the service file edit====
=== -lang parameter for changing Locale ===


Regardless of whether you simply edited the path in the ''[Service]'' section, or you have also done some more technical edits:
Individual computers may have different default for their locale.  The forum reported an issue with OS X with its default US locale even if that is not your locale.
# Next save file with a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX
 
# Now copy file to where it is needed to run the service <code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx_edited.service /etc/systemd/system/cumulusmx.service</code>
As MX starts its output (to diagnostic log and to any interactive terminal window) says which locale is being used, '''Current culture: English (United States)'''. That default locale will relate to the one your computer had when mono is installed, as it is mono that tells MX all the locale settings. If you notice MX starting with wrong locale, issue the correct instruction to close MX.
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to start after a reboot
 
You can use a '''-lang''' parameter to change the locale as you restart MX. This parameter can be added to the service definition file (see [[#All users - mandatory edit of service file]], or it can be used in your command to start MX interactively. For example, in the UK, type:


If Cumulus MX is already running as a service, then the service is already defined, and to pick up the new definition:
:<code>sudo mono CumulusMX.exe -lang en-GB</code>
* Either reboot the computer
* Or type <code>sudo systemctl daemon-reload</code>


====Commands to start, stop, or restart (stop and start in one command) MX as a service====
Other locale examples:  '''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'''.


You will need to start (or restart) MX after you have defined (or redefined) the service as instructed above. The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]], here I simply repeat the basic commands that can be used with any service (start, stop, and restart), so you might change the '''cumulusmx''' to the name of another service.
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.  


* sudo systemctl start cumulusmx
Note that this does not affect the language used by Cumulus MX (although it may in the future), it currently affects the decimal separator and the list separator. Also note that the developer has announced that in a future release of MX, all [[:Category:Files with Comma Separated Values|Files with Comma Separated Values]] will have a fixed format, i.e. it will no longer be possible to use a decimal comma within Cumulus files, and various other fields (like dates) will always have the same format.  At the time this was written, there is no date set for this change.
* sudo systemctl stop cumulusmx
* sudo systemctl restart cumulusmx


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.


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


=== -debug parameter for adding debugging ===
=== -debug parameter for adding debugging ===


This is only available for [https://cumulus.hosiene.co.uk/viewtopic.php?p=138839#p138839 release 3.4.4 - Build 3068] onwards. This switches on debug and data logging from the start-up of Cumulus MX by adding a parameter:
This is only available for [https://cumulus.hosiene.co.uk/viewtopic.php?p=138839#p138839 release 3.4.4 - Build 3068] onwards. This switches on debug and data logging from the start-up of Cumulus MX by adding a parameter within the service definition file (see [[#All users - mandatory edit of service file]] if running as a service.
 
If running MX interactively, then add as a parameter on the command line:  
 
:<code>sudo mono CumulusMX.exe -debug</code>
:<code>sudo mono CumulusMX.exe -debug</code>


MX has a default level of logging that stores in the [[MXdiags_folder]] folder a log file that shows some of the interaction with the weather station and some of the output actions done as MX runs. A new log is started each time MX is restarted.
MX has a default level of logging that stores in the [[MXdiags_folder]] folder a log file that shows some of the interaction with the weather station and some of the output actions done as MX runs. A new log is started each time MX is restarted.


If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[:Category:Diagnostics]] page for details) or the above command.
If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[:Category:Diagnostics]] page for details) or by using the "-debug" parameter as explained above.


=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===
=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===
Line 561: Line 731:
Note use of this parameter is now deprecated, as it has been incorporated into '''-debug''', see above.
Note use of this parameter is now deprecated, as it has been incorporated into '''-debug''', see above.


== Running any MX executable with a terminal session left open ==
This is alternative to the running as service as described above.
The simplest instruction to run Cumulus MX  is <code>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</code>. 
* This is two commands issued together, the first changes the working folder, the second actually starts the main executable
** To run "Create Missing" or '''ExportToMySQL''', just edit what appears after "mono" to the correct executable name
* If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "EXISTING PATH/CumulusMX" folder and you can omit the "sudo".
* You can add parameters after "CumulusMX.exe"  (select from '''-debug''', -locale, -port) as described in sub-sections above
Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running.
You can start it off directly on your Pi, and then
*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.
Use <code>'''ps -ef | grep -i cumulus | grep -v grep'''</code> to see if Cumulus is running or not.


= Operating a web site with uploads from MX engine =
= Operating a web site with uploads from MX engine =
Sfws
5,838

edits

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