Cumulus Wiki

MX on Linux: Difference between revisions

MX on Linux (view source)

Revision as of 10:31, 21 April 2021

660 bytes added ,  10:31, 21 April 2021
m
change sequence
m (change sequence)
Line 15: Line 15:
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 operating system. In the Cumulus support forum, there are many posts from people who are struggling with using Windows PCs, and it seems a lot of them find "installing" and using MX difficult with Microsoft Windows.
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 operating system. In the Cumulus support forum, there are many posts from people who are struggling with using Windows PCs, and it seems a lot of them find "installing" and using MX difficult with Microsoft Windows.


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


As an example, this page picks a tiny,but powerful, computer that is called the Raspberry Pi (RPi), running the Raspberry Pi Operating System, but most of the guidance here will apply to other devices. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the RPi. Although it is intended that this page should cover all Linux-based devices, the content here is based on experience of those who have contributed to this page. To be more comprehensive, it needs contributions from users of other devices to be prepared to edit this page.
The notes here will generally apply to any version of Linux, although the configuration editor described is only on the RPi.  


Although it is intended that this page should cover all Linux-based devices, the content here is based on experience of those who have contributed to this page. To be more comprehensive, it needs contributions from users of other devices to be prepared to edit this page.


'''Perhaps, you my reader, can add sub-sections to this page adding any alterative guidance for other Linux running devices.'''
 
'''Perhaps, you my reader, can add sub-sections to this page adding any alternative guidance for other Linux running devices.'''
 
==How to read this page==
 
This page is deliberately arranged so the key information about installing MONO and MX comes first, and you may not need to read beyond that.
 
===A tiny Linux computer===
 
To install MX on a Linux computer, you obviously need a computer.  After this page has covered MX, scroll down, and a long section (should you wish to read it) tells you everything about a tiny,but powerful, computer that is called the Raspberry Pi (RPi), running the Raspberry Pi Operating System, but most of the guidance here will apply to other devices.
 
===Other information on this page===
 
After that comes a section on Linux commands, if you carry on reading.
 
This page ends with text about what else you can do with your Linux computer. This is not about using word-processors, but about optionally running your own web server and database server.


{{TOCright}}
{{TOCright}}
= Checking all packages are up to date =
Periodically, and before you add new software, it is worth getting your RPi to check its respositories to see if everything already installed is using latest release.
Note these commands do not update the kernal. You do NOT need to reboot your Linux computer for any package these commands change. (Only a kernal update needs a reboot, and a Kernal update is so complicated it is not described here).
'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.
= Installing Mono =
Sponsored by Microsoft, Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
== Preparing for Mono installation ==
Quite often when we try to install, or update, packages on our Pi we will see messages about dependencies, and in some cases error messages saying the installation has failed or been aborted. This is why you are advised to do both '''apt-get update''' and ''apt-get upgrade'' first.
Before we can install many packages, we need to install certificates and tell our RPi where to download from.
For Mono, these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian Mono download instructions for Raspberry Pi]. Here are the latest 2 options when this article was updated (if your Mono installation fails, then you selected wrong one):
For Raspberry Operating System 9 (stretch):
<pre>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
sudo apt update
</pre>
For Raspberry Operating System 10 (buster):
<pre>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
sudo apt update</pre>
== Installing Mono instruction ==
With all the pre-requisites correct as in previous steps, you can install mono package by simply typing <tt>sudo apt-get install -y mono-complete</tt>.
*The "sudo" part of this gives us super-user rights when executing the instruction that follows
*The "apt-get" is one of the ways to search the Raspberry repository for applications, it is more powerful than just "apt"
*The "install" is the action we want to do
*The '''-y''' flag means the installation will happen without us needing to confirm we want it to install the packages identified.
*The "mono-complete" is the package we want.
With latest installs of rPi, you can also use <tt>sudo apt install mono-complete -y</tt>
It is important to note that MX requires the ''complete'' edition of mono. (There is also a cut-down developer edition of Mono that can be downloaded/installed, and that is the default installation).
==Tidying Mono  Installation==
Installing mono-complete has probably added some components not needed for your particular Linux distribution. To remove unneeded components type <tt>sudo autoremove</tt>.
Now you have what is needed to run any executable related to Cumulus, not just '''CumulusMX.exe'''.
= Completing Package Installation =
As the Pi does not know exactly which components are needed when multiple packages are installed with various dependencies, sometimes extra components are installed which in the end are not needed when you complete all your installations.
To clear up, delete any components that are not included in dependencies by typing <tt>sudo apt autoremove</tt>.
=Cumulus MX =
Now you have your Linux computer set up, it is ready for MX, so this section is the important one.
== Where to install MX? ==
For simplicity, MX can be installed into standard Pi user's home directory ('''~/CumulusMX''') here, as that simplifies permissions, you don't need super user privileges to write in the home directory. However, instead of using '''"~/"''', the following notes will use '''EXISTING PATH''', so the notes are equally valid should you install elsewhere.
The image that Mark Crossley provides has MX pre-installed into '''/opt/CumulusMX'''.
You might choose to install it on an external drive which has two significant advantages:
#there are certain files within MX that are updated very frequently, such constant rewriting can lead to a shorter life for your micro-SD card,
#*by using an external drive for MX, MX files are less likely to be lost, and you keep MX and your operating system on separate drives, so are less likely to wear out your micro-SD card
#if you accidentally were to corrupt a critical file on your Raspberry Pi, you would need to rebuild the operating system image, and that deletes all existing files on the micro-SD card, including any related to MX, and you don't want to lose your precious Cumulus data
Both the optional "data" directory created by NOOBS, and any external drive that has been mounted, normally appear within "/media/pi" in the file structure so EXISTING PATH might be "/media/pi/mount_name", but the exact path depends on your set-up, and might not be as predicted here.
== Downloading and Unzipping MX Distribution ==
The download and unzip procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir EXISTING PATH/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution into home directory ('''~''').
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#Download the MX distribution from the link that appears there, Mark will update it for each release he makes.
If the latest release has bugs (it is impossible for the developer to check all the ways in which versatile MX can be used), you can Download whatever older version of MX you have decided to install from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
#If you are downloading the distribution on your Pi, the easiest option is to download into '''~/downloads''' folder.
#* Whether this location is the default, or you are asked to select location will depend on whether your browser's default settings have been changed.
#When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
#Ensure the file unzips into your personal home directory "/home/pi", although you could place it elsewhere, this is the easiest place to find (because it can also be represented by "~").
==Upgrading to a new release==
Follow above instructions, again.
'''Either''' install new release on top of old release, '''or''' install in new place (follow all instructions as if new installation for adding existing log files) remembering that <tt>sudo mono CumulusMX.exe</tt> instruction has to be issued in new place.
== MX Back-up issues ==
You should ensure that you backup the critical files ([[Cumulus.ini]], [[strings.ini]], all files in '''data''' folder, any files in '''Report''' folder) on a regular basis to another computer (or to your web site) and not rely on any back-ups that MX does.
== Configuration issues ==
To learn more about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
In the earlier MX releases, some settings can be changed in the admin graphical interface (these are labelled read-write), but some (labelled read-only) must be configured by stopping Cumulus and editing the configuration file.
More recent releases simplify the process, all settings can be configured using the interface.  So if this is your first use of Cumulus MX (even if you used the legacy Cumulus before), then on first starting the software, you can configure all the settings. Now stop and restart MX to ensure all those settings are picked up.
===General Issues when configuring===
'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions may save you from days of issues:
*The settings available will vary depending on which release of MX you are installing/running
**You need to work through all the settings web pages in the interface, to ensure that you have made all the settings needed for your set up.
**Please note that some settings are related (e.g. you need to enable real-time before any real-time actions can be selected; equally you need to enable moon image generation before you can tick the moon upload option; these are just the 2 most common errors)
*For general advice relating to [[:Category:Cumulus MX| various MX issues]], study all the links in that category
*For [[What to do when I have a problem with MX]], follow that link
*An article that needs someone to spend a lot of time improving it is [[Cumulus MX FAQ]], but the article could be useful
*If you were using the original (now leagcy) 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, it will help you understand configuration differences.
*If you previously ran MX on a Microsoft Windows PC, and now intend to run MX on your RPi, be aware that the characters terminating each line in any files copied across may need editing (see next sub-section).
===Configuration Issues when moving from Windows to Linux===
Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. 
Whilst you will find using the admin interface to make changes is easiest because it (in many cases) limits the selections to those that are valid.
However, editing the Cumulus.ini file directly might be easier if you want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
Here are the main points (based on MX being installed in home folder):
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]]. 
*For '''Extra Web Files''', local file names will look like ''/home/pi/CumulusMX/web/trendsT.htm'' for the standard templates, or it might be something like '''/home/pi/cumulus_Templates/valuesRecentForDetailT.js''' if you have created your own templates.
**''Please note'' that Cumulus MX program code DOES NOT recognise "'''~/'''" as shorthand for '''/home/pi/'''.
**Your remote file names, if you have a local server as set up in the notes in the optional sections later, will look like ''/var/www/html/weather/trends.html'' or '''/var/www/html/weather/js/valuesRecentForTrends.js''', depending on your folder structure. 
**If you pay for a commercial web server, remote file names will be as specified by them and not dependent on what device MX is on.
**Remember ''if web site is on your Pi'', MX needs full '''rw''' permissions to the HTML folder on your web site,  so give permissions recursively using <tt>sudo chmod -R ugo+rw /var/www/html</tt> for Cumulus MX to successfully copy there.
== Keeping existing data and Reports files ==
'''If you have used Cumulus before''', you will be seeking to keep your existing log files.
To get the entire content of your existing  '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card, or a memory stick, (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).
Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, and your files were created by Microsoft Windows, then ideally all your files should be edited so they simply use Line_feed (LF) to terminate all lines. This can be easily done on your RPi by opening each file in an editor like '''Geany'' (part of the programming collection in the full RPi OS installation that is designed for computer files. Geany can be set to always save every file with '''LF''' only on every line regards of what was used on any individual line when file was read; plus it can have multiple files open.
If you are editing on another operating system, '''Notepad++''' is an easy to use editor that is designed for computer files. It has some capabilities to do changes to all open files.
If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed a  Windows OS on your Raspberry Pi.
If you are a novice and your files contain both '''CR''' and '''LF''', the Linux will only use the '''LF''' as end of line character, and will treat the '''CR''' as an indication the file is not in Linux format. This might give problems if you try to use one of the basic text editors provided with RPi OS, but MX will cope.
===using file transfer===
On a Microsoft Windows PC, [https://winscp.net/eng/download.php WinSCP] is a popular choice for file transfer (FTP and SFTP). It can be done using command lines in a (Powershell, Command, or Terminal) window.  Alternatively, it uses a Graphical User Interface, that can support multiple tabs, and background. For full features see [https://winscp.net/eng/docs/feature_index here]. As it is designed just for Windows, it can appear in right click menus. Another benefit is that it shares some settings with [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html Putty SSH client], if you will use that to link to your RPi.
A common FTP client, available on most devices is FileZilla Client.
First of all you need to configure your FTP client, unless you have done that previously and saved the configuration:
*The quickest way in FileZilla is to fill out the "quick connect boxes".
*The quickest way in WinSCP is to use its command line options.
*The following apply to all clients using GUI.
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, (and I have not said how you can change this on a RPi!)
Click the button to '''Connect''' and you should see the local files in the left frame and your Pi home files in the right frame. The easiest way is to find the folder called '''data''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.
If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).
== Running Cumulus MX ==
This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and
#directly with terminal window left open.
=== Optional parameters to add to the instruction to run the MX engine ===
Beta builds in MX version 3.0.0 had an optional parameter <tt>-wsport nnnn</tt> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''WebSockets'''. That parameter is now deprecated as WebSockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. The remaining parameters that are still available are described in subsequent sub-sections.
==== Parameter for changing Port ====
When Cumulus starts, it will display the URL of the user interface. It runs on port 8998 by default; if this is not suitable for some reason you can over-ride it using the '-port' parameter on the command line, e.g. to use port 9999 instead:
<pre>sudo mono CumulusMX.exe -port 9999</pre>
==== Parameter for adding debugging ====
MX has a default level of logging that stores in  the [[MXDiags_folder]] folder a log file that shows some of the interaction with the weather station and some of the output actions done as MX runs. A new log is started each time MX is restarted.
If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings ('''options''' section of ''station settings'') in admin interface  while MX is running, or by adding 1 or 2 parameters when you start MX.  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. Whether you start it with a parameter or enable it within settings, stopping MX will end the extra debugging, and on restart it will default back to no debugging unless turned on again with parameter or setting.
You can also add  '''CumulusMX.exe -debug''' (to have full debugging of actions by MX turned on as MX starts), and/or '''CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).
<pre>sudo mono CumulusMX.exe -debug -Logging=1</pre>
Since this parameter is applied when you start MX, it applies while MX continues to run. Obviously, it must be applied every time you start MX if you want this increased level of logging to continue every time you restart MX.
The comments in the MX source suggests -debug turns on both debug and data logging (see [[MX_Administrative_Interface#Options|Station_Settings#Options]] in admin interface settings), but I believe that is wrong as per example above, there are 2 separate parameters.
==== 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>
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.
=== Setting up as a service ===
Unless you are running a very old release, MX has ability to run as a service.
#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 <tt>sudo nano cumulusmx.service</tt> 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
:<tt>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</tt>
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 <tt>sudo systemctl enable cumulusmx</tt> 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 <tt>sudo systemctl start cumulusmx</tt>
Use <tt>systemctl status cumulusmx.service</tt> 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 <tt>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</tt>.  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
*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 <tt>'''ps -ef | grep -i cumulus | grep -v grep'''</tt> to see if Cumulus is running or not.


=The Raspberry Pi micro-computer=
=The Raspberry Pi micro-computer=
Line 363: Line 643:
Select ‘Finish’.
Select ‘Finish’.


= Checking all packages are up to date =
Periodically, and before you add new software, it is worth getting your RPi to check its respositories to see if everything already installed is using latest release.
Note these commands do not update the kernal. You do NOT need to reboot your Linux computer for any package these commands change. (Only a kernal update needs a reboot, and a Kernal update is so complicated it is not described here).
'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.
= Installing Mono =
Sponsored by Microsoft, Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
== Preparing for Mono installation ==
Quite often when we try to install, or update, packages on our Pi we will see messages about dependencies, and in some cases error messages saying the installation has failed or been aborted. This is why you are advised to do both '''apt-get update''' and ''apt-get upgrade'' first.
Before we can install many packages, we need to install certificates and tell our RPi where to download from.
For Mono, these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian Mono download instructions for Raspberry Pi]. Here are the latest 2 options when this article was updated (if your Mono installation fails, then you selected wrong one):
For Raspberry Operating System 9 (stretch):
<pre>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
sudo apt update
</pre>
For Raspberry Operating System 10 (buster):
<pre>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
sudo apt update</pre>
== Installing Mono instruction ==
With all the pre-requisites correct as in previous steps, you can install mono package by simply typing <tt>sudo apt-get install -y mono-complete</tt>.
*The "sudo" part of this gives us super-user rights when executing the instruction that follows
*The "apt-get" is one of the ways to search the Raspberry repository for applications, it is more powerful than just "apt"
*The "install" is the action we want to do
*The '''-y''' flag means the installation will happen without us needing to confirm we want it to install the packages identified.
*The "mono-complete" is the package we want.
With latest installs of rPi, you can also use <tt>sudo apt install mono-complete -y</tt>
It is important to note that MX requires the ''complete'' edition of mono. (There is also a cut-down developer edition of Mono that can be downloaded/installed, and that is the default installation).
==Tidying Mono  Installation==
Installing mono-complete has probably added some components not needed for your particular Linux distribution. To remove unneeded components type <tt>sudo autoremove</tt>.
Now you have what is needed to run any executable related to Cumulus, not just '''CumulusMX.exe'''.
= Completing Package Installation =
As the Pi does not know exactly which components are needed when multiple packages are installed with various dependencies, sometimes extra components are installed which in the end are not needed when you complete all your installations.
To clear up, delete any components that are not included in dependencies by typing <tt>sudo apt autoremove</tt>.
=Cumulus MX =
Now you have your Linux computer set up, it is ready for MX, so this section is the important one.
== Where to install MX? ==
For simplicity, MX can be installed into standard Pi user's home directory ('''~/CumulusMX''') here, as that simplifies permissions, you don't need super user privileges to write in the home directory. However, instead of using '''"~/"''', the following notes will use '''EXISTING PATH''', so the notes are equally valid should you install elsewhere.
The image that Mark Crossley provides has MX pre-installed into '''/opt/CumulusMX'''.
You might choose to install it on an external drive which has two significant advantages:
#there are certain files within MX that are updated very frequently, such constant rewriting can lead to a shorter life for your micro-SD card,
#*by using an external drive for MX, MX files are less likely to be lost, and you keep MX and your operating system on separate drives, so are less likely to wear out your micro-SD card
#if you accidentally were to corrupt a critical file on your Raspberry Pi, you would need to rebuild the operating system image, and that deletes all existing files on the micro-SD card, including any related to MX, and you don't want to lose your precious Cumulus data
Both the optional "data" directory created by NOOBS, and any external drive that has been mounted, normally appear within "/media/pi" in the file structure so EXISTING PATH might be "/media/pi/mount_name", but the exact path depends on your set-up, and might not be as predicted here.
== Downloading and Unzipping MX Distribution ==


The download and unzip procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir EXISTING PATH/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution into home directory ('''~''').
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#Download the MX distribution from the link that appears there, Mark will update it for each release he makes.
If the latest release has bugs (it is impossible for the developer to check all the ways in which versatile MX can be used), you can Download whatever older version of MX you have decided to install from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].
#If you are downloading the distribution on your Pi, the easiest option is to download into '''~/downloads''' folder.
#* Whether this location is the default, or you are asked to select location will depend on whether your browser's default settings have been changed.
#When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
#Ensure the file unzips into your personal home directory "/home/pi", although you could place it elsewhere, this is the easiest place to find (because it can also be represented by "~").
==Upgrading to a new release==
Follow above instructions, again.
'''Either''' install new release on top of old release, '''or''' install in new place (follow all instructions as if new installation for adding existing log files) remembering that <tt>sudo mono CumulusMX.exe</tt> instruction has to be issued in new place.
== MX Back-up issues ==
You should ensure that you backup the critical files ([[Cumulus.ini]], [[strings.ini]], all files in '''data''' folder, any files in '''Report''' folder) on a regular basis to another computer (or to your web site) and not rely on any back-ups that MX does.
== Configuration issues ==
To learn more about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
In the earlier MX releases, some settings can be changed in the admin graphical interface (these are labelled read-write), but some (labelled read-only) must be configured by stopping Cumulus and editing the configuration file.
More recent releases simplify the process, all settings can be configured using the interface.  So if this is your first use of Cumulus MX (even if you used the legacy Cumulus before), then on first starting the software, you can configure all the settings. Now stop and restart MX to ensure all those settings are picked up.
===General Issues when configuring===
'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions may save you from days of issues:
*The settings available will vary depending on which release of MX you are installing/running
**You need to work through all the settings web pages in the interface, to ensure that you have made all the settings needed for your set up.
**Please note that some settings are related (e.g. you need to enable real-time before any real-time actions can be selected; equally you need to enable moon image generation before you can tick the moon upload option; these are just the 2 most common errors)
*For general advice relating to [[:Category:Cumulus MX| various MX issues]], study all the links in that category
*For [[What to do when I have a problem with MX]], follow that link
*An article that needs someone to spend a lot of time improving it is [[Cumulus MX FAQ]], but the article could be useful
*If you were using the original (now leagcy) 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, it will help you understand configuration differences.
*If you previously ran MX on a Microsoft Windows PC, and now intend to run MX on your RPi, be aware that the characters terminating each line in any files copied across may need editing (see next sub-section).
===Configuration Issues when moving from Windows to Linux===
Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. 
Whilst you will find using the admin interface to make changes is easiest because it (in many cases) limits the selections to those that are valid.
However, editing the Cumulus.ini file directly might be easier if you want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
Here are the main points (based on MX being installed in home folder):
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]]. 
*For '''Extra Web Files''', local file names will look like ''/home/pi/CumulusMX/web/trendsT.htm'' for the standard templates, or it might be something like '''/home/pi/cumulus_Templates/valuesRecentForDetailT.js''' if you have created your own templates.
**''Please note'' that Cumulus MX program code DOES NOT recognise "'''~/'''" as shorthand for '''/home/pi/'''.
**Your remote file names, if you have a local server as set up in the notes in the optional sections later, will look like ''/var/www/html/weather/trends.html'' or '''/var/www/html/weather/js/valuesRecentForTrends.js''', depending on your folder structure. 
**If you pay for a commercial web server, remote file names will be as specified by them and not dependent on what device MX is on.
**Remember ''if web site is on your Pi'', MX needs full '''rw''' permissions to the HTML folder on your web site,  so give permissions recursively using <tt>sudo chmod -R ugo+rw /var/www/html</tt> for Cumulus MX to successfully copy there.
== Keeping existing data and Reports files ==
'''If you have used Cumulus before''', you will be seeking to keep your existing log files.
To get the entire content of your existing  '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card, or a memory stick, (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).
Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, and your files were created by Microsoft Windows, then ideally all your files should be edited so they simply use Line_feed (LF) to terminate all lines. This can be easily done on your RPi by opening each file in an editor like '''Geany'' (part of the programming collection in the full RPi OS installation that is designed for computer files. Geany can be set to always save every file with '''LF''' only on every line regards of what was used on any individual line when file was read; plus it can have multiple files open.
If you are editing on another operating system, '''Notepad++''' is an easy to use editor that is designed for computer files. It has some capabilities to do changes to all open files.
If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed a  Windows OS on your Raspberry Pi.
If you are a novice and your files contain both '''CR''' and '''LF''', the Linux will only use the '''LF''' as end of line character, and will treat the '''CR''' as an indication the file is not in Linux format. This might give problems if you try to use one of the basic text editors provided with RPi OS, but MX will cope.
===using file transfer===
On a Microsoft Windows PC, [https://winscp.net/eng/download.php WinSCP] is a popular choice for file transfer (FTP and SFTP). It can be done using command lines in a (Powershell, Command, or Terminal) window.  Alternatively, it uses a Graphical User Interface, that can support multiple tabs, and background. For full features see [https://winscp.net/eng/docs/feature_index here]. As it is designed just for Windows, it can appear in right click menus. Another benefit is that it shares some settings with [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html Putty SSH client], if you will use that to link to your RPi.
A common FTP client, available on most devices is FileZilla Client.
First of all you need to configure your FTP client, unless you have done that previously and saved the configuration:
*The quickest way in FileZilla is to fill out the "quick connect boxes".
*The quickest way in WinSCP is to use its command line options.
*The following apply to all clients using GUI.
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, (and I have not said how you can change this on a RPi!)
Click the button to '''Connect''' and you should see the local files in the left frame and your Pi home files in the right frame. The easiest way is to find the folder called '''data''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.
If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).
== Running Cumulus MX ==
This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and
#directly with terminal window left open.
=== Optional parameters to add to the instruction to run the MX engine ===
Beta builds in MX version 3.0.0 had an optional parameter <tt>-wsport nnnn</tt> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''WebSockets'''. That parameter is now deprecated as WebSockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. The remaining parameters that are still available are described in subsequent sub-sections.
==== Parameter for changing Port ====
When Cumulus starts, it will display the URL of the user interface. It runs on port 8998 by default; if this is not suitable for some reason you can over-ride it using the '-port' parameter on the command line, e.g. to use port 9999 instead:
<pre>sudo mono CumulusMX.exe -port 9999</pre>
==== Parameter for adding debugging ====
MX has a default level of logging that stores in  the [[MXDiags_folder]] folder a log file that shows some of the interaction with the weather station and some of the output actions done as MX runs. A new log is started each time MX is restarted.
If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings ('''options''' section of ''station settings'') in admin interface  while MX is running, or by adding 1 or 2 parameters when you start MX.  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. Whether you start it with a parameter or enable it within settings, stopping MX will end the extra debugging, and on restart it will default back to no debugging unless turned on again with parameter or setting.
You can also add  '''CumulusMX.exe -debug''' (to have full debugging of actions by MX turned on as MX starts), and/or '''CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).
<pre>sudo mono CumulusMX.exe -debug -Logging=1</pre>
Since this parameter is applied when you start MX, it applies while MX continues to run. Obviously, it must be applied every time you start MX if you want this increased level of logging to continue every time you restart MX.
The comments in the MX source suggests -debug turns on both debug and data logging (see [[MX_Administrative_Interface#Options|Station_Settings#Options]] in admin interface settings), but I believe that is wrong as per example above, there are 2 separate parameters.
==== 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>
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.
=== Setting up as a service ===
Unless you are running a very old release, MX has ability to run as a service.
#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 <tt>sudo nano cumulusmx.service</tt> 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
:<tt>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</tt>
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 <tt>sudo systemctl enable cumulusmx</tt> 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 <tt>sudo systemctl start cumulusmx</tt>
Use <tt>systemctl status cumulusmx.service</tt> 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 <tt>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</tt>.  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
*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 <tt>'''ps -ef | grep -i cumulus | grep -v grep'''</tt> to see if Cumulus is running or not.


= A very quick introduction to Linux =
= A very quick introduction to Linux =
Sfws
5,838

edits

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