Cumulus Wiki - User contributions [en]

Pop-Up Graphs - Gauges Page

2023-01-22T22:49:45Z

Phil23: /* Basic Overview. */

== Introduction. ==
This page attempts to describe step by step how to setup the Pop-up Graphs that can be seen on the Gauges pages when hovering the mouse over a particular gauge.
Theses are more correctly referred to as '''''Server Generated Graphs''''', as they are created on the Web Hosting Server. 

There is a lot of detail in [https://cumulus.hosiene.co.uk/viewtopic.php?p=103317#p103317 this thread in the forum], which now spans 6 years.

=== Basic Overview. ===

Re-Visiting this during a Hosting Migration.

Requirements:-

JpGraph, from here...
https://jpgraph.net/download/

Cumulus-MX-Gauge-Graphs, from here...
https://github.com/mcrossley/Cumulus-MX-Gauge-Graphs

Pop-Up Graphs - Gauges Page

2021-08-31T10:12:19Z

Phil23:

Pop-Up Graphs - Gauges Page

2021-08-31T10:05:28Z

Phil23: /* To be Created. */

Pop-Up Graphs - Gauges Page

2021-08-31T09:53:21Z

Phil23:

== To be Created. ==
(As soon as I get the work flow finalised & get a handle on creating an entire page)....

Pop-Up Graphs - Gauges Page

2021-08-31T09:52:30Z

Phil23: Created page with "To be Created. (As soon as I get the work flow finalised & get a handle on creating an entire page)...."

To be Created.
(As soon as I get the work flow finalised & get a handle on creating an entire page)....

MX on Linux

2021-07-25T04:06:14Z

Phil23: /* USB HID */

{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.

{{TOCright}}
=Page Content=

This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables

There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page

=Using MX on UNIX-derived Operating Systems=

MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

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

: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?==

Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

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

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

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

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? =

New hardware might come preloaded with an operating system, or might allow you to choose which operating system to install on it.

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

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

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

==The various components to commands for installation==

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

===sudo===

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

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

If we are working away from the folder(s) owned by the default user, we can consider whether we want to change the ownership of these parts of the file system (how to do this for a MX installation is explained later) so that we can access the files with our default user without using "sudo" for file/folder commands.

In some limited cases, it might make sense to just change "read" rights,so that the default user can read a file/folder, but other actions are not possible without using "sudo" prefix. This limits our ability to accidentally delete files that other processes need.

===apt===

The second part of our installation commands 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 a little technical explanation at the end of this page if this really worries you.

===install===

The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.

For the record only, here is full list of what can follow “apt”:

{| class="wikitable" border="1"
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|update
| The "source list" [[#The various components to commands for installation|mentioned earlier]] that references the repositories from which software packages can be installed, needs to be updated periodically so it reflects any changes within those repositories. The instruction "update" is included after "apt" to make sure your computer has up to date information about repositories installed, and to report if these contain packages that can be upgraded
|-
|upgrade
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions
|-
|autoremove
| 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.

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

=== Flags ===

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.

=== Name ===

The final part of the package command is the name of the package or component that we want to install/upgrade/purge/show/remove or search for.

=Install starts here=

If your computer has the pre-installed image, or you have installed MX before, you can skip the sub-sections that follow on here and continue reading at [[#Cumulus packages]].

== Preparing for an install==

Before we do an install of a new package, we typically use this series of commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>
Each of those can be understood from information in previous section.

If you are installing onto a Pi zero, or similar slow computer, please ensure the size of the swapfile is as big as possible, as the mono-complete we will install is large. In linux, we type <code>free -m</code> to see our RAM size and our swapfile size.

To change swapfile size on the Raspberry Pi, you need to edit a file <code>sudo nano /etc/dphys-swapfile</code>. Move the cursor down line by line until it reaches '''CONF_SWAPSIZE=100'''. That is showing that the swapfile is only 99 mb by default in the Raspberry Pi Operating System. Now move the cursor to the 100, and change it to "512" which is enough for mono even on a Pi zero. Next, stop, and restart the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>. That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.

=== USB HID ===

There is one more prerequisite package for MX with some weather station types.

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

To check your USB devices, type <code>sudo lsusb -t</code>.

To check HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.

Optionally read about [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=14310&p=111593&hilit=libudev.so.1#p111593 Oregon Scientific] issues.

To read about [https://cumulus.hosiene.co.uk/viewtopic.php?p=107913#p107913 Fine Offset issues and the (file may need to be linked to where MX wants it) file link instructions]

=== Changing the Source List ===

The "source list" [[#The various components to commands for installation|mentioned earlier]] may not contain all the repositories we need for our installations.

Consequently, type <code>sudo apt search mono-complete</code>, to find out whether the mono package is available from one of the repositories already in our source list, and if the version available is compatible with MX (Release announcements for MX should specify which versions of Mono will work). Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which Linux kernel is used by our Operating System.

There are a number of sub-sections below, please check which applies to you, and only read that one.

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

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

# the first line (in each case) installs a certificate
# the echo line defines a repository to add to the sources list.
{| class="wikitable"
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch) !! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code> || <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code>
|-
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code> || <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</code> || <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</code>
|-
| <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code> || <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code>
|-
| <code>sudo apt update</code> || <code>sudo apt update</code>
|}
{|
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch)
! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| style="height:50px;| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
|-
| style="height:100px; |<code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| style="height:50px;| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</nowiki>
| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</nowiki>
|-
| style="height:50px;|sudo tee /etc/apt/sources.list.d/mono-official-stable.list
| sudo tee /etc/apt/sources.list.d/mono-official-stable.list
|}

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

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

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

Others can be found by choosing other tabs on any of those links.

== Installing Mono instruction ==

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

: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 a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

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

=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 "CumulusMX".

==Handling zip files==

Each release is presented as a zip.

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.

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

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

==Where to install all packages?==

For simplicity on this page EXISTING PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.

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

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

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

==Packages to install==

<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX’’’:
#* '''CumulusMX.exe’’’ is written in C#
#* Download '''CumulusMX zip file’’’ from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is another C# package
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki (it will populate missing fields in [[standard log files]] and/or missing lines in [[dayfile.txt]]),
#* Simple Instructions for using this executable are on the github page where they are found, you can find the link for that at [[Software#Create_Missing]] in this Wiki.
# '''ExportToMySQL'''
#* '''ExportToMySQL.exe''' is also written in C#
#* Download '''ExportToMySQL.exe''' package from [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.

As at 9 March 2020, there is another utility, '''CreateRecord''', initialised in the Github areas managed by the developer where Cumulus is worked on. This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]]. However, at the time of writing this, it is nothing more than a concept that needs to be coded, and (as far as I know) there has been no progress on that utility for at least 4 months.

===Alternative download link for older MX releases===

Skip this sub-section if either you have installed the "pre-built disc image", or the current MX release is stable (it has been available for a while and nobody has reported any bugs).

Check if posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX that you intend to use.

Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:
* Different weather station types (the developer only has a Davis),
* Different computer types (development is mostly on Microsoft Windows),
* Plus a whole host of optional features, and different external upload sites, (typically each of these optional features are only used by a sub-set of Cumulus users).

Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities that matches your older MX.

==Upgrading a Cumulus package==

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

== Report and data files to copy across from any previous Cumulus location ==

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

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

If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

==Configuration Files to copy across from any previous Cumulus installation==

There are two configuration files that are not included in any MX release:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

If you are upgrading from an older release, please read the next 2 sub-sections for advice.

===strings.ini===

'''This is an optional file'''. Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.

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

The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. So be cautious if you try to use a "strings.ini" file originally created by the legacy software, check whether the parameters you used before are still available in the latest "samplestrings.ini".

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

===Cumulus.ini===

If your old release was 3.8.0 or later, then copy the [[Cumulus.ini]] file used in that old installation into your new one. The file is growing with lots of new parameters, and the tables on the page I have just linked indicated when parameters were introduced, and where those settings may be changed to make it simple for you to ensure all settings are right for your new release.

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

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

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

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.

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

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

===File Names & Paths===

Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".

This could be applicable if you are using Extra Web files.

Here is an example changing the case and the separators: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.

=Running MX on Linux=

This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and
# interactively with terminal window left open.

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

IMPORTANT: The "sudo" prefix shown in code examples for the various parameters can be omitted if the user that is running MX owns the folder "CumulusMX" and all its contents. In the [[#Where to install all packages?|installation notes earlier]] possible locations and ownership issues were mentioned. That earlier section also defined EXISTING PATH, if that is not mentioned in the code examples, it is assumed you have already issued a <code>cd EXISTING PATH</code> to be in the right folder for issuing the command.

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

=== Parameter for changing Port ===

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 changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
:<code>sudo mono CumulusMX.exe -lang en-GB</code>

Other locale examples: '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''', '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

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.

=== Parameter for running as service ===

The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>

You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.

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

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

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

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

[Install]
WantedBy=multi-user.target</pre>

== Setting up as a service in release 3.8.0 ==

Skip this sub-section for latest release.

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

=== Parameter for adding debugging ===

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>sudo mono CumulusMX.exe -debug</code>

=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===

The following two parameters cannot be used with MX since it came out of 3.0.0 beta.

==== web sockets ====

Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono EXISTING PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.

That parameter [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 is now deprecated as Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see -port parameter described earlier.

==== Debugging of data flow between station and MX====

Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated.

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

==Running as a service==

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

The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]],they are not duplicated here, so there is only one place to do any update.

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

== Running 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 =

== The standard web pages ==

=== From release 3.10.1 ===

The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].

Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.

=== Until release 3.9.7 ===

The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.

Please read [[Customised_templates]] for further information about the various pages originally provided, and how you could customise them to suit you.

=== Comparison with legacy Cumulus 1 web pages ===

* Note that any web files, designed for Cumulus 1, cannot be used with MX, for multiple reasons
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are rather like the stand alone [[SteelSeries Gauges|SteelSeries gauges]] you could optionally add to Cumulus 1, but the MX ones are different.
** The new default gauges page does not display a graph when you hover over a gauge (Cumulus 1 generated some images that the stand alone Steel Series gauges page could use)
* The various charts pages for MX rely on MX to generate files with time and value pairs, these are stored in json format, the various web pages use a library package (Highstocks) to draw graphs from those data pairs.
** (The Trends page provided as standard in Cumulus 1 simply displayed images of graphs uploaded to the web server)

== Alternative ways to obtain web pages ==

You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].

== Using your own web pages ==

* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

=That is enough folks=

If you have read up to here, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

=Technical Extra=

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

== A very quick introduction to Linux ==

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

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

=== su and sudo ===

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

Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

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

=== ~ and / ===

The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.

To reference a folder in root or any other area, the prefix is always '''/'''.

If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.

In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.

=== folder commands ===

To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.

To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!

To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>.

An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

=== editing files ===

*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.

There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

====nano====

The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>.

After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.

You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

====Geany====

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

== removing an unwanted file ==

You can remove a file with various commands, including <code>sudo rm filename</code>.

=== external storage ===

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].

Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.

== Package Manager – a brief technical aside==

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

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

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

===Debian as used by Raspberry Pi===

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

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

===Ubuntu===

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

===Mint===

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.

MX on Linux

2021-07-25T03:48:25Z

Phil23:

{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.

{{TOCright}}
=Page Content=

This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables

There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page

=Using MX on UNIX-derived Operating Systems=

MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

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

: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?==

Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

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

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

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

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? =

New hardware might come preloaded with an operating system, or might allow you to choose which operating system to install on it.

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

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

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

==The various components to commands for installation==

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

===sudo===

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

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

If we are working away from the folder(s) owned by the default user, we can consider whether we want to change the ownership of these parts of the file system (how to do this for a MX installation is explained later) so that we can access the files with our default user without using "sudo" for file/folder commands.

In some limited cases, it might make sense to just change "read" rights,so that the default user can read a file/folder, but other actions are not possible without using "sudo" prefix. This limits our ability to accidentally delete files that other processes need.

===apt===

The second part of our installation commands 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 a little technical explanation at the end of this page if this really worries you.

===install===

The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.

For the record only, here is full list of what can follow “apt”:

{| class="wikitable" border="1"
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|update
| The "source list" [[#The various components to commands for installation|mentioned earlier]] that references the repositories from which software packages can be installed, needs to be updated periodically so it reflects any changes within those repositories. The instruction "update" is included after "apt" to make sure your computer has up to date information about repositories installed, and to report if these contain packages that can be upgraded
|-
|upgrade
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions
|-
|autoremove
| 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.

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

=== Flags ===

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.

=== Name ===

The final part of the package command is the name of the package or component that we want to install/upgrade/purge/show/remove or search for.

=Install starts here=

If your computer has the pre-installed image, or you have installed MX before, you can skip the sub-sections that follow on here and continue reading at [[#Cumulus packages]].

== Preparing for an install==

Before we do an install of a new package, we typically use this series of commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>
Each of those can be understood from information in previous section.

If you are installing onto a Pi zero, or similar slow computer, please ensure the size of the swapfile is as big as possible, as the mono-complete we will install is large. In linux, we type <code>free -m</code> to see our RAM size and our swapfile size.

To change swapfile size on the Raspberry Pi, you need to edit a file <code>sudo nano /etc/dphys-swapfile</code>. Move the cursor down line by line until it reaches '''CONF_SWAPSIZE=100'''. That is showing that the swapfile is only 99 mb by default in the Raspberry Pi Operating System. Now move the cursor to the 100, and change it to "512" which is enough for mono even on a Pi zero. Next, stop, and restart the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>. That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.

=== USB HID ===

There is one more prerequisite package for MX with some weather station types.

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

To check your USB devices, type <code>sudo lsusb -t</code).

To check HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.

Optionally read about [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=14310&p=111593&hilit=libudev.so.1#p111593 Oregon Scientific] issues.

To read about [https://cumulus.hosiene.co.uk/viewtopic.php?p=107913#p107913 Fine Offset issues and the (file may need to be linked to where MX wants it) file link instructions]

=== Changing the Source List ===

The "source list" [[#The various components to commands for installation|mentioned earlier]] may not contain all the repositories we need for our installations.

Consequently, type <code>sudo apt search mono-complete</code>, to find out whether the mono package is available from one of the repositories already in our source list, and if the version available is compatible with MX (Release announcements for MX should specify which versions of Mono will work). Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which Linux kernel is used by our Operating System.

There are a number of sub-sections below, please check which applies to you, and only read that one.

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

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

# the first line (in each case) installs a certificate
# the echo line defines a repository to add to the sources list.
{| class="wikitable"
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch) !! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code> || <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code>
|-
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code> || <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</code> || <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</code>
|-
| <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code> || <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code>
|-
| <code>sudo apt update</code> || <code>sudo apt update</code>
|}
{|
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch)
! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| style="height:50px;| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
|-
| style="height:100px; |<code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| style="height:50px;| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</nowiki>
| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</nowiki>
|-
| style="height:50px;|sudo tee /etc/apt/sources.list.d/mono-official-stable.list
| sudo tee /etc/apt/sources.list.d/mono-official-stable.list
|}

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

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

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

Others can be found by choosing other tabs on any of those links.

== Installing Mono instruction ==

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

: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 a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

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

=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 "CumulusMX".

==Handling zip files==

Each release is presented as a zip.

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.

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

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

==Where to install all packages?==

For simplicity on this page EXISTING PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.

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

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

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

==Packages to install==

<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX’’’:
#* '''CumulusMX.exe’’’ is written in C#
#* Download '''CumulusMX zip file’’’ from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is another C# package
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki (it will populate missing fields in [[standard log files]] and/or missing lines in [[dayfile.txt]]),
#* Simple Instructions for using this executable are on the github page where they are found, you can find the link for that at [[Software#Create_Missing]] in this Wiki.
# '''ExportToMySQL'''
#* '''ExportToMySQL.exe''' is also written in C#
#* Download '''ExportToMySQL.exe''' package from [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.

As at 9 March 2020, there is another utility, '''CreateRecord''', initialised in the Github areas managed by the developer where Cumulus is worked on. This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]]. However, at the time of writing this, it is nothing more than a concept that needs to be coded, and (as far as I know) there has been no progress on that utility for at least 4 months.

===Alternative download link for older MX releases===

Skip this sub-section if either you have installed the "pre-built disc image", or the current MX release is stable (it has been available for a while and nobody has reported any bugs).

Check if posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX that you intend to use.

Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:
* Different weather station types (the developer only has a Davis),
* Different computer types (development is mostly on Microsoft Windows),
* Plus a whole host of optional features, and different external upload sites, (typically each of these optional features are only used by a sub-set of Cumulus users).

Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities that matches your older MX.

==Upgrading a Cumulus package==

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

== Report and data files to copy across from any previous Cumulus location ==

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

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

If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

==Configuration Files to copy across from any previous Cumulus installation==

There are two configuration files that are not included in any MX release:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

If you are upgrading from an older release, please read the next 2 sub-sections for advice.

===strings.ini===

'''This is an optional file'''. Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.

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

The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. So be cautious if you try to use a "strings.ini" file originally created by the legacy software, check whether the parameters you used before are still available in the latest "samplestrings.ini".

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

===Cumulus.ini===

If your old release was 3.8.0 or later, then copy the [[Cumulus.ini]] file used in that old installation into your new one. The file is growing with lots of new parameters, and the tables on the page I have just linked indicated when parameters were introduced, and where those settings may be changed to make it simple for you to ensure all settings are right for your new release.

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

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

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

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.

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

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

===File Names & Paths===

Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".

This could be applicable if you are using Extra Web files.

Here is an example changing the case and the separators: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.

=Running MX on Linux=

This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and
# interactively with terminal window left open.

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

IMPORTANT: The "sudo" prefix shown in code examples for the various parameters can be omitted if the user that is running MX owns the folder "CumulusMX" and all its contents. In the [[#Where to install all packages?|installation notes earlier]] possible locations and ownership issues were mentioned. That earlier section also defined EXISTING PATH, if that is not mentioned in the code examples, it is assumed you have already issued a <code>cd EXISTING PATH</code> to be in the right folder for issuing the command.

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

=== Parameter for changing Port ===

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 changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
:<code>sudo mono CumulusMX.exe -lang en-GB</code>

Other locale examples: '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''', '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

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.

=== Parameter for running as service ===

The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>

You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.

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

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

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

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

[Install]
WantedBy=multi-user.target</pre>

== Setting up as a service in release 3.8.0 ==

Skip this sub-section for latest release.

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

=== Parameter for adding debugging ===

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>sudo mono CumulusMX.exe -debug</code>

=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===

The following two parameters cannot be used with MX since it came out of 3.0.0 beta.

==== web sockets ====

Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono EXISTING PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.

That parameter [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 is now deprecated as Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see -port parameter described earlier.

==== Debugging of data flow between station and MX====

Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated.

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

==Running as a service==

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

The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]],they are not duplicated here, so there is only one place to do any update.

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

== Running 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 =

== The standard web pages ==

=== From release 3.10.1 ===

The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].

Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.

=== Until release 3.9.7 ===

The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.

Please read [[Customised_templates]] for further information about the various pages originally provided, and how you could customise them to suit you.

=== Comparison with legacy Cumulus 1 web pages ===

* Note that any web files, designed for Cumulus 1, cannot be used with MX, for multiple reasons
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are rather like the stand alone [[SteelSeries Gauges|SteelSeries gauges]] you could optionally add to Cumulus 1, but the MX ones are different.
** The new default gauges page does not display a graph when you hover over a gauge (Cumulus 1 generated some images that the stand alone Steel Series gauges page could use)
* The various charts pages for MX rely on MX to generate files with time and value pairs, these are stored in json format, the various web pages use a library package (Highstocks) to draw graphs from those data pairs.
** (The Trends page provided as standard in Cumulus 1 simply displayed images of graphs uploaded to the web server)

== Alternative ways to obtain web pages ==

You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].

== Using your own web pages ==

* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

=That is enough folks=

If you have read up to here, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

=Technical Extra=

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

== A very quick introduction to Linux ==

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

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

=== su and sudo ===

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

Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

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

=== ~ and / ===

The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.

To reference a folder in root or any other area, the prefix is always '''/'''.

If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.

In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.

=== folder commands ===

To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.

To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!

To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>.

An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

=== editing files ===

*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.

There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

====nano====

The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>.

After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.

You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

====Geany====

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

== removing an unwanted file ==

You can remove a file with various commands, including <code>sudo rm filename</code>.

=== external storage ===

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].

Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.

== Package Manager – a brief technical aside==

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

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

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

===Debian as used by Raspberry Pi===

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

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

===Ubuntu===

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

===Mint===

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.

MX on Linux

2021-07-25T03:37:42Z

Phil23: /* Add the Mono repository for a Raspberry Pi */

{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.

{{TOCright}}
=Page Content=

This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables

There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page

=Using MX on UNIX-derived Operating Systems=

MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

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

: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?==

Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

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

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

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

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? =

New hardware might come preloaded with an operating system, or might allow you to choose which operating system to install on it.

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

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

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

==The various components to commands for installation==

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

===sudo===

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

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

If we are working away from the folder(s) owned by the default user, we can consider whether we want to change the ownership of these parts of the file system (how to do this for a MX installation is explained later) so that we can access the files with our default user without using "sudo" for file/folder commands.

In some limited cases, it might make sense to just change "read" rights,so that the default user can read a file/folder, but other actions are not possible without using "sudo" prefix. This limits our ability to accidentally delete files that other processes need.

===apt===

The second part of our installation commands 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 a little technical explanation at the end of this page if this really worries you.

===install===

The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.

For the record only, here is full list of what can follow “apt”:

{| class="wikitable" border="1"
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|update
| The "source list" [[#The various components to commands for installation|mentioned earlier]] that references the repositories from which software packages can be installed, needs to be updated periodically so it reflects any changes within those repositories. The instruction "update" is included after "apt" to make sure your computer has up to date information about repositories installed, and to report if these contain packages that can be upgraded
|-
|upgrade
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions
|-
|autoremove
| 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.

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

=== Flags ===

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.

=== Name ===

The final part of the package command is the name of the package or component that we want to install/upgrade/purge/show/remove or search for.

=Install starts here=

If your computer has the pre-installed image, or you have installed MX before, you can skip the sub-sections that follow on here and continue reading at [[#Cumulus packages]].

== Preparing for an install==

Before we do an install of a new package, we typically use this series of commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>
Each of those can be understood from information in previous section.

If you are installing onto a Pi zero, or similar slow computer, please ensure the size of the swapfile is as big as possible, as the mono-complete we will install is large. In linux, we type <code>free -m</code> to see our RAM size and our swapfile size.

To change swapfile size on the Raspberry Pi, you need to edit a file <code>sudo nano /etc/dphys-swapfile</code>. Move the cursor down line by line until it reaches '''CONF_SWAPSIZE=100'''. That is showing that the swapfile is only 99 mb by default in the Raspberry Pi Operating System. Now move the cursor to the 100, and change it to "512" which is enough for mono even on a Pi zero. Next, stop, and restart the relevant service using <code>sudo /etc/init.d/dphys-swapfile stop && sudo /etc/init.d/dphys-swapfile start</code>. That should complete quickly, and we can type <code>free -m</code> again to see the 99 we saw previously has been replaced by 511.

=== USB HID ===

There is one more prerequisite package for MX with some weather station types.

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

To check your USB devices, type <code>sudo lsusb -t</code).

To check HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.

Optionally read about [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=14310&p=111593&hilit=libudev.so.1#p111593 Oregon Scientific] issues.

To read about [https://cumulus.hosiene.co.uk/viewtopic.php?p=107913#p107913 Fine Offset issues and the (file may need to be linked to where MX wants it) file link instructions]

==Changing the Source List==

The "source list" [[#The various components to commands for installation|mentioned earlier]] may not contain all the repositories we need for our installations.

Consequently, type <code>sudo apt search mono-complete</code>, to find out whether the mono package is available from one of the repositories already in our source list, and if the version available is compatible with MX (Release announcements for MX should specify which versions of Mono will work). Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which Linux kernel is used by our Operating System.

There are a number of sub-sections below, please check which applies to you, and only read that one.

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

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

# the first line (in each case) installs a certificate
# the echo line defines a repository to add to the sources list.
{| class="wikitable"
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch) !! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code> || <code>sudo apt install apt-transport-https dirmngr gnupg ca-certificates</code>
|-
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code> || <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</code> || <code>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</code>
|-
| <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code> || <code>sudo tee /etc/apt/sources.list.d/mono-official-stable.list</code>
|-
| <code>sudo apt update</code> || <code>sudo apt update</code>
|}
{|
|-
! scope="col" style="width:450px; color:blue" | Raspberry Operating System 9 (stretch)
! scope="col" style="width:450px; color:navy" | Raspberry Operating System 10 (buster)
|-
| style="height:50px;| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
| sudo apt install apt-transport-https dirmngr gnupg ca-certificates
|-
| style="height:100px; |<code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
| <code>sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF</code>
|-
| style="height:50px;| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main"</nowiki>
| <nowiki>echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main"</nowiki>
|-
| style="height:50px;|sudo tee /etc/apt/sources.list.d/mono-official-stable.list
| sudo tee /etc/apt/sources.list.d/mono-official-stable.list
|}

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

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

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

Others can be found by choosing other tabs on any of those links.

== Installing Mono instruction ==

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

: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 a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

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

=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 "CumulusMX".

==Handling zip files==

Each release is presented as a zip.

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.

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

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

==Where to install all packages?==

For simplicity on this page EXISTING PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.

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

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

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

==Packages to install==

<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX’’’:
#* '''CumulusMX.exe’’’ is written in C#
#* Download '''CumulusMX zip file’’’ from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is another C# package
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki (it will populate missing fields in [[standard log files]] and/or missing lines in [[dayfile.txt]]),
#* Simple Instructions for using this executable are on the github page where they are found, you can find the link for that at [[Software#Create_Missing]] in this Wiki.
# '''ExportToMySQL'''
#* '''ExportToMySQL.exe''' is also written in C#
#* Download '''ExportToMySQL.exe''' package from [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.

As at 9 March 2020, there is another utility, '''CreateRecord''', initialised in the Github areas managed by the developer where Cumulus is worked on. This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]]. However, at the time of writing this, it is nothing more than a concept that needs to be coded, and (as far as I know) there has been no progress on that utility for at least 4 months.

===Alternative download link for older MX releases===

Skip this sub-section if either you have installed the "pre-built disc image", or the current MX release is stable (it has been available for a while and nobody has reported any bugs).

Check if posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX that you intend to use.

Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:
* Different weather station types (the developer only has a Davis),
* Different computer types (development is mostly on Microsoft Windows),
* Plus a whole host of optional features, and different external upload sites, (typically each of these optional features are only used by a sub-set of Cumulus users).

Anyway, '''you can download any earlier build, without the bug''', from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities that matches your older MX.

==Upgrading a Cumulus package==

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

== Report and data files to copy across from any previous Cumulus location ==

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

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

If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

==Configuration Files to copy across from any previous Cumulus installation==

There are two configuration files that are not included in any MX release:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

If you are upgrading from an older release, please read the next 2 sub-sections for advice.

===strings.ini===

'''This is an optional file'''. Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.

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

The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. So be cautious if you try to use a "strings.ini" file originally created by the legacy software, check whether the parameters you used before are still available in the latest "samplestrings.ini".

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

===Cumulus.ini===

If your old release was 3.8.0 or later, then copy the [[Cumulus.ini]] file used in that old installation into your new one. The file is growing with lots of new parameters, and the tables on the page I have just linked indicated when parameters were introduced, and where those settings may be changed to make it simple for you to ensure all settings are right for your new release.

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

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

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

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.

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

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

===File Names & Paths===

Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".

This could be applicable if you are using Extra Web files.

Here is an example changing the case and the separators: ''Web\extrapageT.htm'' in Windows, changed to read '''web/extrapageT.htm''' in Linux.

=Running MX on Linux=

This section explores the optional parameters, and then covers 2 ways to run MX:
# as a service and
# interactively with terminal window left open.

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

IMPORTANT: The "sudo" prefix shown in code examples for the various parameters can be omitted if the user that is running MX owns the folder "CumulusMX" and all its contents. In the [[#Where to install all packages?|installation notes earlier]] possible locations and ownership issues were mentioned. That earlier section also defined EXISTING PATH, if that is not mentioned in the code examples, it is assumed you have already issued a <code>cd EXISTING PATH</code> to be in the right folder for issuing the command.

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

=== Parameter for changing Port ===

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 changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
:<code>sudo mono CumulusMX.exe -lang en-GB</code>

Other locale examples: '''CumulusMX.exe Current culture: English (United States)''', '''CumulusMX.exe -lang de-DE''', '''CumulusMX.exe -lang el-GR''' (this is one of the locales that reads numbers with '''integer,decimal''' format), '''CumulusMX.exe -lang nl-NL'''.

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

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.

=== Parameter for running as service ===

The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>

You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.

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

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

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

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

[Install]
WantedBy=multi-user.target</pre>

== Setting up as a service in release 3.8.0 ==

Skip this sub-section for latest release.

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

=== Parameter for adding debugging ===

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>sudo mono CumulusMX.exe -debug</code>

=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===

The following two parameters cannot be used with MX since it came out of 3.0.0 beta.

==== web sockets ====

Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono EXISTING PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.

That parameter [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 is now deprecated as Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see -port parameter described earlier.

==== Debugging of data flow between station and MX====

Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated.

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

==Running as a service==

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

The full set of commands to use with this service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]],they are not duplicated here, so there is only one place to do any update.

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

== Running 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 =

== The standard web pages ==

=== From release 3.10.1 ===

The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].

Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.

=== Until release 3.9.7 ===

The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.

Please read [[Customised_templates]] for further information about the various pages originally provided, and how you could customise them to suit you.

=== Comparison with legacy Cumulus 1 web pages ===

* Note that any web files, designed for Cumulus 1, cannot be used with MX, for multiple reasons
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are rather like the stand alone [[SteelSeries Gauges|SteelSeries gauges]] you could optionally add to Cumulus 1, but the MX ones are different.
** The new default gauges page does not display a graph when you hover over a gauge (Cumulus 1 generated some images that the stand alone Steel Series gauges page could use)
* The various charts pages for MX rely on MX to generate files with time and value pairs, these are stored in json format, the various web pages use a library package (Highstocks) to draw graphs from those data pairs.
** (The Trends page provided as standard in Cumulus 1 simply displayed images of graphs uploaded to the web server)

== Alternative ways to obtain web pages ==

You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].

== Using your own web pages ==

* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

=That is enough folks=

If you have read up to here, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

=Technical Extra=

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

== A very quick introduction to Linux ==

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

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

=== su and sudo ===

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

Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

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

=== ~ and / ===

The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.

To reference a folder in root or any other area, the prefix is always '''/'''.

If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.

In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.

=== folder commands ===

To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.

To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!

To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>.

An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

=== editing files ===

*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.

There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

====nano====

The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>.

After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.

You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

====Geany====

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

== removing an unwanted file ==

You can remove a file with various commands, including <code>sudo rm filename</code>.

=== external storage ===

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].

Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.

== Package Manager – a brief technical aside==

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

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

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

===Debian as used by Raspberry Pi===

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

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

===Ubuntu===

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

===Mint===

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.

MX on Linux

2021-07-21T20:41:13Z

Phil23: /* Add the Mono repository for a Raspberry Pi */

{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.

=Using MX on UNIX-derived Operating Systems=

MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

==Device Coverage==

This page is intended to cover all Linux-based devices, but the content here is based on experience of those who have contributed to this page.

Linux is available in a multitude of different kernels, on a multitude of devices, but this Wiki page will largely ignore any technical variations (some included at end of page) and focus on giving some background content to support the basics.

The Raspberry Pi Operating System is based on Debian, one of the Linux kernels. Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].

If you use a different kernel, or feel that this page inadequately covers what you want to know, can you add sub-sections to this page to ensure it covers the Linux device you use?

: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?==

Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

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

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

=Page Content=
{{TOCright}}

This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables

There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page

=For those using Raspberry Pi computers=

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.

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? =

Is your Linux computer already working? Or does it need an Operating System to be installed?

An operating system is the is is the software that is loaded onto your computer to provide commands and everything else that males a computer work.

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

=Ready to install MX?=

Assuming our Linux computer has a kernel, how do we add packages to our system? We need a short technical digression to explain the command, skip this next section if you already know how to install packages.

==The various components to commands for installation==

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

===sudo===

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

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

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

There is a longer technical explanation towards the end of this page, all I will say here is that you might see “apt-get” used in some on-line examples. I suggest you replace “apt” where “apt-get” is seen as generally “apt” is more friendly. Equally, “apt” can replace “apt-cache”, which I won’t explain.

===install===

The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.

For the record only, here is full list of what can follow “apt”:

{| class="wikitable" border="1"
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|update
|To make sure your computer has up to date information about repositories installed and to report if these contain packages that can be upgraded
|-
|upgrade
|To see which of your packages have newer versions now available in repositories, and to replace those packages with the newer versions
|-
|autoremove
|To check all components in the packages you have installed and remove those components that are not needed by the dependencies of the packages you use.

As an example, when you install mono-complete, there might be components that are never used, and “autoremove” can be used to tidy up when you finish all your installations
|-
|remove
|If you want to remove just one component manually, use “remove” followed by the name of component you no longer want
|-
|purge
|To remove any installed package and delete all related configuration files
|-
|search
|To search in repositories in source list for a package you specify after “search”
|-
|show
|To show any information available about a package that you name after the “show”
|}

=== Flags ===

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

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

=== Name ===

The final part of the installation command is the name of the package or component that we want to install.

== Preparing for an install==

Before we do an install of a new package, we typically use some of these commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>

Each of these can be understood from information in previous section.

= Which software packages will we install?=

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

# Our first task will be to install the appropriate mono repository, if that is not already in our source list
# Our second task will install a package called ‘’’mono-complete’’’ from the repository we just installed, (this is needed to run software written in the C# languages)

==Changing the Source List==

If you type <code>sudo apt search mono-complete</code>, you will find out whether the package is available from one of the repositories already in our source list. Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which kernel we have, so choose the right sub-section below.

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

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

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

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

echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
</code>
|}

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

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

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

Others can be found by choosing other tabs on any of those links.

== Installing Mono instruction ==

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

: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 a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

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

=Cumulus packages=

Note use of plural in section name above, the following sub-sections will install MX and the other packages already mentioned, all by Developer Mark Crossley.

Our next task is to install the Cumulus software listed on [[Software]] page:
# '''CumulusMX’’’, this is written in C# and we download it from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''CreateMissing.exe''']], another C# package (it will populate missing fields or missing lines in log files), Simple Instructions for using this executable is on the github page where they are found, again linked from '''Software''' page in this Wiki.
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.
# Finally, install ‘’’Export (old data) To a Maria (or other MySQL) database server’’’ package downloaded from [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.

==Where to install all packages?==

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

==Alternative download link for older MX releases==

For completeness, you may have discovered (from posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] that the current release of MX has a bug that affects an aspect of MX that you intend to use. Remember, it is impossible for the developer to check all the ways in which versatile MX can be used (different weather station types, different computer types, plus a whole host of features, and different external upload sites, that are only used by a sub-set of people).

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

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities.

==Handling zip files==

Each release is presented as a zip.

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

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

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

==Where to install MX==

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

It was also mentioned before that you can create the folder to hold the packages in advance using <code>sudo mkdir EXISTING PATH/CumulusMX</code>, and you can change its permissions using <code>chmod ugo+rwx CumulusMX</code>.

==Upgrading a Cumulus package==

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

==Configuration Files to copy across from any previous Cumulus installation==

There are two configuration files that are not included in any MX release:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

If you are upgrading from an older release, please read the next 2 sub-sections for advice.

===strings.ini===

'''This is an optional file'''. Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.

You create a “strings.ini” file by selecting some of the parameters from the [[samplestrings.ini]] file that is included in each MX release, and modifying the value for the listed attributes.

The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. They may also be change drastically be one MX release and the next. Therefore, your existing “strings.ini” might need to be modified.

There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.

Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is in “samplestring.ini” of your new install. You may also find parameters in “samplestring.ini” that you need to add to your “strings.ini” file.

===Cumulus.ini===

Since release 3.8.0, many people prefer to omit their existing “Cumulus.ini” file when upgrading from an old release, or making an install on a new device. Instead, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.

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

There were significant changes to “Cumulus.ini” when moving from 1.9.4 to 3.0.0, see [[Cumulus_3_(MX)_beta_documentation]] and [[Migrating_from_Cumulus_1_to_MX]] pages. As described [[Updating_MX_to_new_version|on upgrading advice page]] in this Wiki, moving from 1.9.4 to MX is best done gradually upgrading through releases, as a number of Cumulus files (e.g. [[Amending_dayfile#Date_Separator_in_MX|dayfile.txt]]), and any database tables you are using, may also need adjusting as you progress up through releases, and that is best done at correct in-between releases (see individual MX release announcements in support forum). Documentation for the 1.9.4 '''cumulus.ini''' file can be found [[Cumulus.ini_(Cumulus_1)|here]] should you need to work on your old legacy file.

See also the note below relating to File Paths in Windows Vs Linux, as you probably need to edit paths if you did not use Linux before.

There were gradual changes to “Cumulus.ini” as releases went from 3.0.0 to 3.7.0, documentation can be found [[Cumulus.ini (MX_3.0.0_to_3.7.0)| here]] where, hopefully, the changes are made clear. ''Within that range of releases, you should continue to use any existing '''Cumulus.ini''' file, as you might lose vital "read-only" parameters by starting a new file.'' As mentioned before, the [[Updating_MX_to_new_version|upgrading advice page]] is the best place to seek advice on which releases to upgrade to which, rather than attempting to directly upgrade to latest release.

The documentation for various later MX releases (covering just 3.8.0 to 3.12.0 at the time this paragraph was last updated) can be found at [[Cumulus.ini]]. ''If you previously used Cumulus 1.x.y, or a release before 3.8.0, please note that there have been '''major changes''' to the parameters included in the file. You must proceed with caution if you want to use a file created by an older release as it will lack loads of new parameters that are now mandatory in MX''. However, [[Cumulus.ini|the configuration file page]] does include advice on (while MX is running) you can automatically update, either an existing file, or to create a new file, the described approach will add all the new parameters (although some will not receive valid values, and others might default away from your preferences). This automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.

==Folders to copy across from previous Cumulus installations==

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

If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

If you are using the optional “NOAA report” functionality, you must also transfer the whole [[Reports folder|Reports]] sub-folder.

===Line terminators in these files===

If you are moving from Microsoft Windows to Linux, you need to be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed).

The kernel in your Linux computer might be able to detect that it is getting Microsoft files, and discard the extra end of line character.

However, if you are reading that file in a script, it might not detect the end of line encoding. So if that script expects “LF” to terminate each line, when the script is reading the final field of each line, the script will find that final field has an unwanted “CR” in it and not recognise it as a numerical value (or time-stamp). Equally, if the script expects “CR” as line terminator, then the first field of the each line (except the first line) starts with a “LF” and the script will not recognise it as a date (or section name).

In each case, any checking for numerical input might fail, and any attempt to check/extract characters from these fields might fail because their position relative to start/end is changed.

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

===Changing line terminators===

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

===File Names & Paths===

Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".

This could be applicable if you are using Extra Web files.

So if the ini file reads
Web\extrapageT.htm in Windows,
it must be changed to read web/extrapageT.htm in Linux.

=Running MX on Linux=

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

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>

=== Beta builds of MX ===

The following two parameters cannot be used with MX since it came out of 3.0.0 beta.

==== web sockets ====

Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

That parameter is now deprecated as Web Sockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see Port parameter below.

==== Debugging of data flow between station and MX====

Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated.

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

=== Parameter for changing Port ===

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

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable

=== Parameter for adding debugging ===

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>sudo mono CumulusMX.exe -debug</code>

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

Since this parameter is applied when you start MX, it applies all the time MX continues to run. Obviously this log file continues to grow, the longer MX is left running, and if debugging is switched on the file will grow in size must faster. Consequently, the default is not to add the extra debugging information and the settings can be used to switch it off again if you do have it switched on.

=== Parameter for changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
<pre>
sudo mono CumulusMX.exe -lang en-GB
</pre>

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

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

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.

Note that you ''may'' need to supply your administrator password after typing the 'sudo ...' command line. The system will prompt you for this if it is needed.

=== Parameter for running as service ===

Use of this is explained next. The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>

== Setting up as a service ==

If you have installed MX release 3.8.0 or later, you can set up MX to run as a service.

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

A better way (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 this later release announcement]:
#There is a task to do just once to configure the service
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <code>sudo nano cumulusmx.service</code> to edit the service configuration file
# Look for '''ExecStart=/usr/bin/mono-service -d:'''
#* Replace the path that follows the above text with the path to your CumulusMX.exe, add the '''-service''' and optionally add any other parameter (e.g. '''-debug''', -locale, -port) as described in sub-sections above.
#save file
#now copy file
:<code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</code>

If you upgrade to a new release, the file in EXISTING PATH will be overwritten, but the critical file in "/etc/sytemd/system" will not be affected.

==Running as a service==

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

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

Use <code>systemctl status cumulusmx.service</code> in a terminal session to see status of Cumulus service

The full set of commands is at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]]

== Running with a terminal session left open ==

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

Whichever operating system you are using, to run MX requires an instruction that changes to the directory (EXISTING PATH) where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].

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

You can start it off directly on your Pi, and then
*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 =

== The standard web pages ==

=== From release 3.10.1 ===

The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].

Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.

=== Until release 3.9.7 ===

The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.

Please read [[Customised_templates]] for further information about the various pages provided, and how you can customise them to suit you.

=== Comparison with legacy Cumulus 1 web pages ===

* Note that the MX web files are not the same as the ones for Cumulus 1,
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are now the SteelSeries gauges. The default gauges page does not display a graph when you hover over a gauge (as happened when you added the stand-alone Steel Series gauges to Cumulus 1).
* The trends web page in Cumulus 1 relied on that software generating graphs as images.
** In MX, the software generates files with time and value pairs, these are stored in json format, the trends page then uses a library package (Highstocks) to draw graphs from those data pairs.

== Alternative ways to obtain web pages ==

You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].

== Using your own web pages ==

* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

=That is enough folks=

If you have read up to here, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

=Technical Extra=

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

== A very quick introduction to Linux ==

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

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

=== su and sudo ===

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

Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

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

=== ~ and / ===

The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.

To reference a folder in root or any other area, the prefix is always '''/'''.

If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.

In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.

=== folder commands ===

To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.

To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!

To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>.

An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

=== editing files ===

*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.

There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

====nano====

The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>.

After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.

You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

====Geany====

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

== removing an unwanted file ==

You can remove a file with various commands, including <code>sudo rm filename</code>.

=== external storage ===

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].

Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.

== Package Manager – a brief technical aside==

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

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

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

===Debian as used by Raspberry Pi===

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

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

===Ubuntu===

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

===Mint===

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.

MX on Linux

2021-07-09T01:07:02Z

Phil23:

{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead.

=Using MX on UNIX-derived Operating Systems=

MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

==Device Coverage==

This page is intended to cover all Linux-based devices, but the content here is based on experience of those who have contributed to this page.

Linux is available in a multitude of different kernels, on a multitude of devices, but this Wiki page will largely ignore any technical variations (some included at end of page) and focus on giving some background content to support the basics.

The Raspberry Pi Operating System is based on Debian, one of the Linux kernels. Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].

If you use a different kernel, or feel that this page inadequately covers what you want to know, can you add sub-sections to this page to ensure it covers the Linux device you use?

: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?==

Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

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

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

=Page Content=
{{TOCright}}

This page:
* describes the options available for installing MX, and the other Cumulus packages
* describes the pre-requisite '''MONO''' software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
* explains the few key Linux commands it uses
* describes the administrative interface and instructions for configuring MX
* it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
* describes the various options available to run MX
* describes the optional parameters you can add when starting MX
* describes the other executables

There are various related pages to get more information:
*Go to [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
*Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
*[[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
*Go to [[:Category:Cumulus Files]] for links to all pages describing the sub-folders and files used by MX
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
*If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page

=For those using Raspberry Pi computers=

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.

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? =

Is your Linux computer already working? Or does it need an Operating System to be installed?

An operating system is the is is the software that is loaded onto your computer to provide commands and everything else that males a computer work.

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

=Ready to install MX?=

Assuming our Linux computer has a kernel, how do we add packages to our system? We need a short technical digression to explain the command, skip this next section if you already know how to install packages.

==The various components to commands for installation==

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

===sudo===

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

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

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

There is a longer technical explanation towards the end of this page, all I will say here is that you might see “apt-get” used in some on-line examples. I suggest you replace “apt” where “apt-get” is seen as generally “apt” is more friendly. Equally, “apt” can replace “apt-cache”, which I won’t explain.

===install===

The third part of our installation instruction is “install”, which tells our package manager what we are trying to do.

For the record only, here is full list of what can follow “apt”:

{| class="wikitable" border="1"
|-
!style="width:30px" | Instruction following “apt”
!style="width:300px" | Description
|-
|install
|To install a package and its dependencies
|-
|update
|To make sure your computer has up to date information about repositories installed and to report if these contain packages that can be upgraded
|-
|upgrade
|To see which of your packages have newer versions now available in repositories, and to replace those packages with the newer versions
|-
|autoremove
|To check all components in the packages you have installed and remove those components that are not needed by the dependencies of the packages you use.

As an example, when you install mono-complete, there might be components that are never used, and “autoremove” can be used to tidy up when you finish all your installations
|-
|remove
|If you want to remove just one component manually, use “remove” followed by the name of component you no longer want
|-
|purge
|To remove any installed package and delete all related configuration files
|-
|search
|To search in repositories in source list for a package you specify after “search”
|-
|show
|To show any information available about a package that you name after the “show”
|}

=== Flags ===

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

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

=== Name ===

The final part of the installation command is the name of the package or component that we want to install.

== Preparing for an install==

Before we do an install of a new package, we typically use some of these commands to ensure our computer is in the best state to work out dependencies of what we are about to install:
<code>
sudo apt update
sudo apt -y upgrade
sudo apt autoremove
</code>

Each of these can be understood from information in previous section.

= Which software packages will we install?=

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

# Our first task will be to install the appropriate mono repository, if that is not already in our source list
# Our second task will install a package called ‘’’mono-complete’’’ from the repository we just installed, (this is needed to run software written in the C# languages)

==Changing the Source List==

If you type <code>sudo apt search mono-complete</code>, you will find out whether the package is available from one of the repositories already in our source list. Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which kernel we have, so choose the right sub-section below.

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

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

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

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

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

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

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

Others can be found by choosing other tabs on any of those links.

== Installing Mono instruction ==

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:
: <code>sudo apt install -y mono-complete</code>.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

: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 a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

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

=Cumulus packages=

Note use of plural in section name above, the following sub-sections will install MX and the other packages already mentioned, all by Developer Mark Crossley.

Our next task is to install the Cumulus software listed on [[Software]] page:
# '''CumulusMX’’’, this is written in C# and we download it from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''CreateMissing.exe''']], another C# package (it will populate missing fields or missing lines in log files), Simple Instructions for using this executable is on the github page where they are found, again linked from '''Software''' page in this Wiki.
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.
# Finally, install ‘’’Export (old data) To a Maria (or other MySQL) database server’’’ package downloaded from [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.

==Where to install all packages?==

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

==Alternative download link for older MX releases==

For completeness, you may have discovered (from posts in the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] that the current release of MX has a bug that affects an aspect of MX that you intend to use. Remember, it is impossible for the developer to check all the ways in which versatile MX can be used (different weather station types, different computer types, plus a whole host of features, and different external upload sites, that are only used by a sub-set of people).

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

You need to ensure that you use the right version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities for the MX release you are running, so if you are using an old MX release, you will need to go directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities.

==Handling zip files==

Each release is presented as a zip.

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

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

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

==Where to install MX==

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

It was also mentioned before that you can create the folder to hold the packages in advance using <code>sudo mkdir EXISTING PATH/CumulusMX</code>, and you can change its permissions using <code>chmod ugo+rwx CumulusMX</code>.

==Upgrading a Cumulus package==

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

==Configuration Files to copy across from any previous Cumulus installation==

There are two configuration files that are not included in any MX release:
*[[strings.ini]] (note all lower case) – optional file to customise output
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

If you are upgrading from an older release, please read the next 2 sub-sections for advice.

===strings.ini===

'''This is an optional file'''. Its [[strings.ini|purpose]] is to allow customisation of some of the outputs from Cumulus. You might want to use customisation to abbreviate (or extend) some outputs, or to change those outputs into another language.

You create a “strings.ini” file by selecting some of the parameters from the [[samplestrings.ini]] file that is included in each MX release, and modifying the value for the listed attributes.

The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. They may also be change drastically be one MX release and the next. Therefore, your existing “strings.ini” might need to be modified.

There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.

Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is in “samplestring.ini” of your new install. You may also find parameters in “samplestring.ini” that you need to add to your “strings.ini” file.

===Cumulus.ini===

Some people prefer to omit their existing “Cumulus.ini” file from their new install. Instead, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.

If you previously used an older release of Cumulus, but in this new installation will be using the latest release, you may want to read up on all the changes.

There were significant changes to “Cumulus.ini” when moving from 1.9.4 to 3.0.0, see [[Cumulus_3_(MX)_beta_documentation]] and [[Migrating_from_Cumulus_1_to_MX]] pages. Documentation for the 1.9.4 file can be found [[Cumulus.ini_(Cumulus_1)|here]].

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

The documentation for the latest MX release can be found at [[Cumulus.ini]], note that it does include advice on (while MX is running) you can automatically update the file. This automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.

See also the note below relating to File Paths in Windows Vs Linux.

==Folders to copy across from previous Cumulus installations==

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

If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date

If you are using the optional “NOAA report” functionality, you must also transfer the whole [[Reports folder|Reports]] sub-folder.

===Line terminators in these files===

If you are moving from Microsoft Windows to Linux, you need to be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed).

The kernel in your Linux computer might be able to detect that it is getting Microsoft files, and discard the extra end of line character.

However, if you are reading that file in a script, it might not detect the end of line encoding. So if that script expects “LF” to terminate each line, when the script is reading the final field of each line, the script will find that final field has an unwanted “CR” in it and not recognise it as a numerical value (or time-stamp). Equally, if the script expects “CR” as line terminator, then the first field of the each line (except the first line) starts with a “LF” and the script will not recognise it as a date (or section name).

In each case, any checking for numerical input might fail, and any attempt to check/extract characters from these fields might fail because their position relative to start/end is changed.

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

===Changing line terminators===

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

===File Names & Paths===

Another issue that may be encountered when moving from Windows to Linux is the difference in File Names & Paths.
Linux file names are Case Sensitive, and the separator is "/" Vs "\".

This could be applicable if you are using Extra Web files.

So if the ini file reads
Web\extrapageT.htm in Windows,
it must be changed to read web/extrapageT.htm in Linux.

=Running MX on Linux=

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

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>

=== Beta builds of MX ===

The following two parameters cannot be used with MX since it came out of 3.0.0 beta.

==== web sockets ====

Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

That parameter is now deprecated as Web Sockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see Port parameter below.

==== Debugging of data flow between station and MX====

Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).

Note use of this parameter is now deprecated.

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

=== Parameter for changing Port ===

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

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable

=== Parameter for adding debugging ===

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (on recent MX releases this is on '''Program Settings''' page of admin interface - please see [[MXdiags_folder]] page for details) or by adding a parameter:
:<code>sudo mono CumulusMX.exe -debug</code>

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

Since this parameter is applied when you start MX, it applies all the time MX continues to run. Obviously this log file continues to grow, the longer MX is left running, and if debugging is switched on the file will grow in size must faster. Consequently, the default is not to add the extra debugging information and the settings can be used to switch it off again if you do have it switched on.

=== Parameter for changing Locale ===

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:
<pre>
sudo mono CumulusMX.exe -lang en-GB
</pre>

You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.

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

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.

Note that you ''may'' need to supply your administrator password after typing the 'sudo ...' command line. The system will prompt you for this if it is needed.

=== Parameter for running as service ===

Use of this is explained next. The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>

== Setting up as a service ==

If you have installed MX release 3.8.0 or later, you can set up MX to run as a service.

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

A better way (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 this later release announcement]:
#There is a task to do just once to configure the service
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <code>sudo nano cumulusmx.service</code> to edit the service configuration file
# Look for '''ExecStart=/usr/bin/mono-service -d:'''
#* Replace the path that follows the above text with the path to your CumulusMX.exe, add the '''-service''' and optionally add any other parameter (e.g. '''-debug''', -locale, -port) as described in sub-sections above.
#save file
#now copy file
:<code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</code>

If you upgrade to a new release, the file in EXISTING PATH will be overwritten, but the critical file in "/etc/sytemd/system" will not be affected.

==Running as a service==

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

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

Use <code>systemctl status cumulusmx.service</code> in a terminal session to see status of Cumulus service

== Running with a terminal session left open ==

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

Whichever operating system you are using, to run MX requires an instruction that changes to the directory (EXISTING PATH) where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].

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

You can start it off directly on your Pi, and then
*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 =

== The standard web pages ==

=== From release 3.10.1 ===

The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].

Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.

=== Until release 3.9.7 ===

The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.

Please read [[Customised_templates]] for further information about the various pages provided, and how you can customise them to suit you.

=== Comparison with legacy Cumulus 1 web pages ===

* Note that the MX web files are not the same as the ones for Cumulus 1,
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are now the SteelSeries gauges. The default gauges page does not display a graph when you hover over a gauge (as happened when you added the stand-alone Steel Series gauges to Cumulus 1).
* The trends web page in Cumulus 1 relied on that software generating graphs as images.
** In MX, the software generates files with time and value pairs, these are stored in json format, the trends page then uses a library package (Highstocks) to draw graphs from those data pairs.

== Alternative ways to obtain web pages ==

You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].

== Using your own web pages ==

* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.

You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.

=That is enough folks=

If you have read up to here, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

=Technical Extra=

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

== A very quick introduction to Linux ==

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

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

=== su and sudo ===

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

Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

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

=== ~ and / ===

The tilde symbol '''~''' denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by '''~/documents''' or similar notation.

To reference a folder in root or any other area, the prefix is always '''/'''.

If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.

In a terminal environment, to see what files and folders are in the current directory, type <code>dir</code> for just names or <code>ls</code> for details.

=== folder commands ===

To make a new folder in the current directory, type <code>sudo mkdir folder_name</code>.

To remove a folder, that has no files in it, type in a particular path, type <code>sudo rmdir /path/directory</code>.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -r /path/directory</code>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!

To copy folders/files from one directory to another use something like <code>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</code>

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is <code>ln -s /path/elsewhere path/pointer_location</code>.

An example might be '''ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <code>rm filename</code> will remove a file even if it is write protected, for nano you need to change the file permissions with <code>sudo chmod -R ugo+rw ~/CumulusMX</code> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* '''+''' = add permission
* '''-''' = remove permission
*letters indicating what permission is being changed
** '''r''' = read [4]
** '''w''' = write [2]
** '''x''' = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. '''666''' is equivalent to '''ugo+rw'''. The first digit in the number relates to ''u'', the second to ''g'' and the last to ''o''. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

=== editing files ===

*Do remember that file names are case sensitive.
*If you use the wrong case in a path/file name, it will be treated as a different "new" file.
*If a file editor does not display content you were expecting, look in case "new file" message appears because you have made a typo in the path/file name.

There are various text editors available on a Pi,
*if you have a mouse and click on a file, you should see "text editor" listed, that loads '''Mousepad''' which has a menubar at the top of its "Windows" like interface.
*in terminal mode '''nano''' is a text editor that by default lists the actions available making it easier for a novice to use.
*in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors can create a file when a file does not exist and edit (subject to file permissions) an existing file. Use prefix of 'sudo' to give you access to any file irrespective of ownership, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

====nano====

The full syntax is <code>sudo nano -B Path_file_name</code> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <code>sudo nano /var/www/html/index.php</code>.

After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*First is '''^O''' which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press '''Enter''' then that file will be overwritten.
**it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type '''Y''' to continue saving).
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.

You might find it useful to type <code>sudo nano /etc/nanorc</code> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

====Geany====

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

== removing an unwanted file ==

You can remove a file with various commands, including <code>sudo rm filename</code>.

=== external storage ===

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. '''gparted''' [https://gparted.org/ partition editor].

Alternatively, you can use a terminal session, and lots of commands:
#connect your external storage
#type '''su''' to gain administrative access
#enter your RPi password
#type '''fdisk -l''' (this is only available to root user) to see names for all storage your Linux computer can see
#an external drive will be named something like ''/dev/sd''''a''''' although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
# if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <code>umount /dev/sda</code>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <code>fdisk /dev/sda</code>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''p''' to make this the primary partition on this drive
#* type '''1''' to make this the first partition
#*accept default offered for first cylinder
#*accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
#*for simplicity, this guidance will not cover the possibility of multiple partitions
#*type '''t''' to say you are specifying the way you want this partition to be specified in partition table
#*optionally type '''L''' to see what file system types are available for the partition table
#*to select a "Linux" partition, type '''83'''
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <code>mkfs.ext4 /dev/sda1</code>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <code>mount /dev/sda1 /media/pi/my_short_name</code>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <code>nano /etx/fstab</code>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
#* exit nano by holding control key and pressing "x" key.

== Package Manager – a brief technical aside==

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

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

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

===Debian as used by Raspberry Pi===

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

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

===Ubuntu===

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

===Mint===

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.

Raspberry Pi Image

2021-06-18T23:07:57Z

Phil23: /* Starting Cumulus MX from the command line */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from the [[Software#Current_Release|Software Download page]].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, scroll down to the bottom of the list and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - do not unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt filename extension 
* Eject the SD card from your computer. Insert it into your Raspberry Pi and power up.

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* It's a good idea to check/configure your RPi for your locale and timezone settings. The default is for en_UK UTF-8 locale and GMT timezone. Use '''sudo raspi-config''' 5. Localization Options, L1 Locale (select en_US ISO-8851-1 for USA if needed) and L2 Timezone (select the appropriate timezone), then '''sudo reboot''' if needed to engage the new settings.
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow '''[https://cumuluswiki.org/a/Cumulus.ini#Cumulus_MX this guide for configuring your station].'''
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudo systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it 
(Noting it is case sensitive).
cd /opt/CumulusMX
sudo mono CumulusMX.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Category:User Contributions

2019-12-31T23:56:20Z

Phil23: /* User contributions to Cumulus */

= User contributions to Cumulus =

Files and add-ons contributed by Cumulus users. the following links will take you to web sites or forum threads, where you can read about and download the item.

*[[WeatherConsole]] Text-based ‘live’ weather display for a web site
*[https://cumulus.hosiene.co.uk/viewtopic.php?f=4&t=2144 Cumulus Realtime Gadget] A Windows desktop gadget
*[[ICumulus_for_iPhone]] An iPhone friendly web interface
*[http://www.screenlets.org/index.php/Sunbird Sunbird – Ubuntu Screenlet] A ‘Screenlet’ for Ubuntu Linux
*[https://cumulus.hosiene.co.uk/viewtopic.php?f=14&t=832 XHTML 1.1 compliant Ajax framework] Ajax XML HTML webserver frameset that displays dynamic realtime data on your web pages
*[[Toolbox]] Cumulus Toolbox contains a variety of extra features to enhance the power of Cumulus by providing a number of automated processes
*[http://meteoduquebec.com/ Météo du Québec] Traduction et adaptation française de Cumulus Icônes, librairies et Modules exclusifs à Cumulus Forum de discussion en français. Ouvert à la francophonie!
*[http://saratoga-weather.org/wxtemplates/index.php AJAX/PHP Multilingual Website Templates] A set of configurable templates to create a full ‘real time’ web site.
*[http://weatherbyyou.com/ Weather by You!] Alternative web site templates for use with Cumulus, many different styles.
*[https://play.google.com/store/apps/details?id=com.gmail.theocapps.homeweather Home Weather Station] An Android app for displaying Cumulus data.
*[https://weather34.com/homeweatherstation/ Weather34 Dashboard] by Brian Underdown. A clean, attractive template for displaying Cumulus data using realtime.txt. You can read more about this in the [https://cumulus.hosiene.co.uk/viewtopic.php?f=14&t=15136 forum]. Download the official latest Cumulus version here: [[HomeWeatherStationTemplate|Home Weather Station Template light and dark themes]]
*[https://cumulus.hosiene.co.uk/viewtopic.php?f=14&t=11397 Yet Another Dayfile Reader] PHP Dayfile Reader with Monthly & Seasonal Display
*[https://cumulus.hosiene.co.uk/viewtopic.php?f=14&t=17573 Cumulusutils] Generates a Fire Weather page Plus much more. See the linked Forum Post for full details.

Cumulus Users

2019-12-27T23:52:20Z

Phil23: Add site to User List

'''Cumulus Users''' is a list of sites powered by [[About Cumulus|Cumulus]].

Users are grouped by geographical region and by country.

These tables were created showing all users having no webcam, but as sites checked they will be updated to indicate if they have not webcam, or if the webcam link is still pointing to the default Sanday webcam.

== Users & Locations ==

=== Africa ===

==== South Africa ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://dieterlubbe.dyndns.org Sonneglans, Johannesburg, Gauteng]
| Nil
| [https://www.google.co.za/maps/place/38+Witdoring+Rd,+Randburg,+2188/@-26.0730892,27.9666189,515m/data=!3m1!1e3!4m5!3m4!1s0x1e9575b26defe91b:0x7725a044cff7f3f8!8m2!3d-26.0730099!4d27.9676835]
|}

=== Asia ===

==== Japan ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://multibox727.com/weather Lake Hamana,Kosai Shizuoka]
| Nil
| [http://maps.google.com/maps?sll=34.722232,137.529945&z=18&t=h&q=Cumulus%20User@34.722232,137.529945]
|}

=== Europe ===

==== Austria ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://wetter.eile.at Vienna]
| Nil
| [http://maps.google.com/maps?sll=48.22544,16.34036&z=18&t=h&q=Cumulus%20User@48.22544,16.34036]
|}

==== Belgium ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://users.skynet.be/fa843465 Heulebrug Knokke-Heist weather station]
| Nil
| [http://maps.google.com/maps?sll=51.330277777778,3.2438888888889&z=18&t=h&q=Cumulus%20User@51.330277777778,3.2438888888889]
|-
| [http://www.weerstation-maarkedal.be/ Maarkedal]
| Nil
| [https://www.google.co.uk/maps/place/Maarkedal,+Belgium/@50.7975098,-0.8376771,6z/data=!4m2!3m1!1s0x47c3057d00e37a49:0x1b8092cb903c0d2b]
|}

==== Bulgaria ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.jerbils.info/saratoga/wxindex.php Zlatina]
| Yes
| [https://www.google.co.uk/maps/place/Zlatina,+Bulgaria/@43.2370974,22.9293192,6z/data=!4m2!3m1!1s0x40a5bce1e991abab:0xa00a014cd0e4e20]
|}

==== Czech Republic ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://meteo.amut.net Amut.NET]
| Yes
| [http://maps.google.com/maps?sll=49.30543137,4.16422367&z=18&t=h&q=Cumulus%20User@49.30543137,4.16422367]
|-
| [http://meteostanice.wrp.cz/ Holice]
| Nil
| [http://maps.google.com/maps?sll=50.0875,15.996944444444&z=18&t=h&q=Cumulus%20User@50.0875,15.996944444444]
|-
| [http://pocasi.ok5aw.cz/meteo/ Nova Paka]
| Yes
| [http://maps.google.com/maps?sll=50.4970450,15.5063000&z=18&t=h&q=Cumulus%20User@50.4970450,15.5063000]
|-
| [http://meteo.ponik.net Plzeň - Radčice]
| Yes
| [http://maps.google.com/maps?sll=49.764333,13.325533&z=18&t=h&q=Cumulus%20User@49.764333,13.325533]
|-
| [http://www.sudislav.cz/meteo/ Sudislav nad Orlicí]
| Yes
| [http://maps.google.com/maps?sll=49.987222222222,16.319722222222&z=18&t=h&q=Cumulus%20User@49.987222222222,16.319722222222]
|}

==== Denmark ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.baekgaarden.eu/weather/ Baekgaarden Weather]
| Nil
| [http://maps.google.com/maps?sll=55.205,10.300833333333&z=18&t=h&q=Cumulus%20User@55.205,10.300833333333]
|-
| [http://www.ibtest.dk/cumulus/ Gilleleje]
| Nil
| [http://maps.google.com/maps?sll=56.083888888889,12.3180555555556&z=18&t=h&q=Cumulus%20User@56.083888888889,12.3180555555556]
|-
| [http://home1.stofanet.dk/korsholm53/weather Hals Golf Klub-Korsholm]
| Yes
| [http://maps.google.com/maps?sll=56.995,10.3225&z=18&t=h&q=Cumulus%20User@56.995,10.3225]
|-
| [http://www.kvistgaardvejr.dk Kvistgaard]
| Default
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=55.99224+12.490421&aq=&sll=55.991145,12.490575&sspn=0.007261,0.020084&g=55.99+12.49&ie=UTF8&ll=55.998381,12.524414&spn=14.912068,57.875977&z=5]
|}

==== Finland ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.netikka.net/mpa Helsingby weather]
| Nil
| [http://maps.google.com/maps?sll=63.024444444444,21.803333333333&z=18&t=h&q=Cumulus%20User@63.024444444444,21.803333333333]
|-
| [http://www.kolumbus.fi/chivaario/weather/index.htm Järvenpää-Isokytö Weather]
| Nil
| [http://maps.google.com/maps?sll=60.483055555556,25.1125&z=18&t=h&q=Cumulus%20User@60.483055555556,25.1125]
|-
| [http://www.karsaa.com/cumulus/ Kärsämäki Sääasema]
| Yes
| [http://maps.google.com/maps?sll=63.973333333333,25.741666666667&z=18&t=h&q=Cumulus%20User@63.973333333333,25.741666666667]
|}

==== France ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.meteo-caylus.fr/index.htm Caylus Météo]
| Nil
| [http://maps.google.com/maps?sll=44.248888888889,1.8066666666667&z=18&t=h&q=Cumulus%20User@44.248888888889,1.8066666666667]
|-
| [http://www.franceability.eu/weather/ Lapeyrouse]
| Yes
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=Lapeyrouse&sll=53.800651,-4.064941&sspn=19.196147,49.570312&ie=UTF8&hq=&hnear=Lapeyrouse,+Puy-de-D%C3%B4me,+Auvergne,+France&ll=46.225453,2.878418&spn=11.203207,24.785156&z=6]
|-
| [http://www.del-rio.net/cumulus/CumulusRealtime.html Rue des Myosotis à Lille]
| Nil
| [http://maps.google.com/maps?sll=50.613611111111,3.0422222222222&z=18&t=h&q=Cumulus%20User@50.613611111111,3.0422222222222]
|}

==== Greece ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://weather.magla.gr Agios Dimitrios - Athens]
| Nil
| [http://maps.google.com/maps?sll=37.933888888889,23.741666666667&z=18&t=h&q=Cumulus%20User@37.933888888889,23.741666666667]
|-
| [http://alepochori.meteoclub.gr Alepochori - Megara]
| Nil
| [http://maps.google.com/maps?sll=38.057198,23.254829&z=18&t=h&q=Cumulus%20User@38.057198,23.254829]
|-
| [http://chalandri.meteoclub.gr Chalandri - Athens]
| Nil
| [http://maps.google.com/maps?sll=38.053611111111,24.331944444444&z=18&t=h&q=Cumulus%20User@38.053611111111,24.331944444444]
|-
| [http://www.metar.gr/ws/chios/ Chios weather]
| Default
| [http://maps.google.com/maps?sll=38.3725,-26.130833333333&z=18&t=h&q=Cumulus%20User@38.3725,-26.130833333333]
|-
| [http://www.galaxidion.gr/meteo Galaxidi]
| Yes
| [http://maps.google.com/maps?sll=38.37711,22.38342&z=18&t=h&q=Cumulus%20User@38.37711,22.38342]
|-
| [http://larisa.meteoclub.gr Larisa]
| Nil
| [http://maps.google.com/maps?sll=39.625277777778,22.411388888889&z=18&t=h&q=Cumulus%20User@39.625277777778,22.411388888889]
|-
| [http://marathonas.meteoclub.gr Marathonas - Athens]
| Yes
| [http://maps.google.com/maps?sll=38.116944444444,23.989166666667&z=18&t=h&q=Cumulus%20User@38.116944444444,23.989166666667]
|-
| [http://nikaia.meteoclub.gr Nikaia - Perivolaki]
| Nil
| [http://maps.google.com/maps?sll=37.9675,23.656388888889&z=18&t=h&q=Cumulus%20User@37.9675,23.656388888889]
|-
| [http://pireas.meteoclub.gr Pireas]
| Nil
| [http://maps.google.com/maps?sll=37.953333333333,23.630555555556&z=18&t=h&q=Cumulus%20User@37.953333333333,23.630555555556]
|}

==== Italy ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://sbonweb.altervista.org/meteo/index.htm Albizzate, VA]
| Nil
| [http://maps.google.com/maps?sll=45.725555555556,8.7958333333333&z=18&t=h&q=Cumulus%20User@45.725555555556,8.7958333333333]
|}

==== Lithuania ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://noway.lt/weather Vilnius]
| Nil
| [http://maps.google.com/maps?sll=54.703888888889,25.227777777778&z=18&t=h&q=Cumulus%20User@54.703888888889,25.227777777778]
|}

==== Netherlands ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.goetweer.nl Andelst, Overbetuwe]
| Nil
| [http://maps.google.com/maps?sll=51.9075,5.7306&z=18&t=h&q=Cumulus%20User@51.9075,5.7306]
|-
| [http://www.apeldoornmeteo.nl/ Apeldoorn]
| Yes
| [https://www.google.co.uk/maps/place/Apeldoorn,+Netherlands/@52.2114039,1.4973809,6z/data=!4m2!3m1!1s0x47c7b8284d1487cb:0x400de5a8d1e65b0]
|-
| [http://77.169.67.221/ Boelenslaan]
| No
| [https://www.google.com/maps/place/53%C2%B005'34.4%22N+6%C2%B004'12.4%22E/@53.0929032,1.5876727,6z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://www.meteozusterhof.nl Weerstation Zusterhof Leiden]
| Yes
| [http://maps.google.com/maps?sll=52.1541,4.49081&z=18&t=h&q=Cumulus%20User@52.1541,4.49081]
|}

==== Norway ====

{| class="wikitable FCK__ShowTableBorders"
|-
! style="width: 350px;" | User
! style="width: 100px;" | Webcam
! style="width: 100px;" | Map
|-
| [http://jmsweb.no/weather Hunstad, Bodø, Norge]
| Nil
| [http://maps.google.com/maps?sll=67.280555555556,14.548611111111&z=18&t=h&q=Cumulus%20User@67.280555555556,14.548611111111]
|-
| [http://www.jaed.no/weather Follebu, Gausdal]
| No
| [http://maps.google.com/maps?sll=61.21055555555,10.2783333333333&z=18&t=h&q=Cumulus%20User@61.21055555555,10.2783333333333]
|-
| [http://www.linesoy.com/trollskaret/ Trollskaret, Linesøya]
| No
| [http://maps.google.com/maps?sll=64.017,9.890&z=18&t=h&q=Cumulus%20User@64.017,9.890]
|}

==== Poland ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://zielona10.pl/ Piaseczno]
| Nil
| [https://www.google.co.uk/maps/place/Piaseczno,+Poland/@52.0733894,18.7759485,7z/data=!4m7!1m4!3m3!1s0x0:0x0!2zNTLCsDA0JzI2LjAiTiAyMcKwMDInMzQuMCJF!3b1!3m1!1s0x47192e390fc40201:0x88c75a9c7e7a1bf5]

|-
| [http://meteo.sokolowsko.pl Sokolowsko PL]
| Yes
| [http://maps.google.com/maps?sll=50.68501663,16.22915268&z=18&t=h&q=Cumulus%20User@50.68501663,16.22915268]
|-
| [http://www.meteo-sulejowek.ugu.pl Sulejówek near Warsaw]
| Nil
| [http://maps.google.com/maps?sll=52.244166666667,21.28&z=18&t=h&q=Cumulus%20User@52.244166666667,21.28]
|}

==== Slovenia ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://home.amis.net/magerls/vreme/current.html Dobrava, Slovenske Konjice]
| Nil
| [http://maps.google.com/maps?sll=46.351388888889,15.401111111111&z=18&t=h&q=Cumulus%20User@46.351388888889,15.401111111111]
|}

==== Spain ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.wheelocknet.net/cumulus/now.htm L'Estartit - Illes Medes]
| Nil
| [http://maps.google.com/maps?sll=42.054829392751,3.19638848304748&z=18&t=h&q=Cumulus%20User@42.054829392751,3.19638848304748]
|-
| [http://www.meteotortosa.cat MeteoTortosa]
| Nil
| [http://maps.google.com/maps?sll=40.83,0.53&z=18&t=h&q=Cumulus%20User@40.83,0.53]
|-
| [http://www.vipapi.com/meteoc/index.htm Palma - Sa Indioteria]
| Nil
| [http://maps.google.com/maps?sll=39.611991,2.675093&z=18&t=h&q=Cumulus%20User@39.611991,2.675093]
|}

==== Sweden ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.anglaberga.se/vws/weather/index.htm Änglaberga, Scania]
| Yes
| [http://maps.google.com/maps?sll=56.054444444444,13.082777777778&z=18&t=h&q=Cumulus%20User@56.054444444444,13.082777777778]
|-
| [http://www.kagevader.se/index.php Kåge väder]
| Yes
| [http://maps.google.com/maps?sll=64.833611111111,20.981666666667&z=18&t=h&q=Cumulus%20User@64.833611111111,20.981666666667]
|-
| [http://home.swipnet.se/gubbfot Lilla Foss Munkedal]
| Yes
| [http://maps.google.com/maps?sll=58.475278,11.670278&z=18&t=h&q=Cumulus%20User@58.475278,11.670278]
|-
| [http://www.sm3ode.se/weather SM3ODE Bollnäs]
| Nil
| [http://maps.google.com/maps?sll=61.364444444444,16.393888888889&z=18&t=h&q=Cumulus%20User@61.364444444444,16.393888888889]
|}

==== Switzerland ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://meteo.cavagnago.ch/index.php?p=main&l=en Cavagnago, Ticino]
| No
| [http://maps.google.co.uk/maps?q=N+46%C2%B0+24'+48%22+E+08%C2%B0+52'+50%22&hl=en&ie=UTF8&ll=46.413333,8.880556&spn=18.672678,42.626953&sll=46.416667,8.883333&sspn=0.03645,0.083256&t=v&z=5]
|-
| [http://www.urs-ingold.ch/cumulus/index.htm Löhliwetter Sumiswald]
| Default
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=%2B47%C2%B0+2'+8.02%22,+%2B7%C2%B0+44'+43.43%22&sll=48.980217,8.635254&sspn=4.82396,10.447998&ie=UTF8&ll=47.035571,7.745278&spn=10.01812,20.895996&z=6]
|-
| [http://Wetter.Fun-Car-Team.ch CH-4316 Hellikon Wetter]
| Default
| [http://maps.google.com/maps?sll=47.506111111111,7.9275&z=18&t=h&q=Cumulus%20User@47.506111111111,7.9275]
|}

==== United Kingdom and Ireland ====

===== Channel Islands =====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://mu0zvv.co.uk/weather/ St Sampsons, Guernsey]
| Nil
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=St.+Sampson,+Guernsey&sll=49.479279,-2.520332&sspn=0.073834,0.154324&ie=UTF8&hq=&hnear=St+Sampson,+Guernsey,+United+Kingdom&ll=49.482401,-2.515869&spn=4.725593,9.876709&z=7]
|}

 

===== England =====

{| class="wikitable"
|-
! style="width: 350px;" | User
! style="width: 100px;" | Webcam
! style="width: 100px;" | Map
|-
| [http://wx.species5618.net/ Abbeymead Gloucester]
| Nil
| [http://maps.google.co.uk/maps?hl=en&ie=UTF8&ll=51.850687,-2.197506&spn=0.000845,0.001725&t=h&z=19]
|-
| [http://www.affetside.org.uk/weather/index.htm AffetsideWX]
| Yes
| [http://maps.google.co.uk/maps?hl=en&ie=UTF8&ll=53.618964,-2.371405&spn=0.000845,0.001725&t=h&z=19]
|-
| [http://www.nelsonm.plus.com/weather/index.htm Audley Weather]
| Yes
| [http://maps.google.com/maps?sll=53.055,-2.3008333333333&z=18&t=h&q=Cumulus%20User@53.055,-2.3008333333333]
|-
| [http://www.glyn.me/weather Banbury Weather]
| Nil
| [http://maps.google.com/maps?sll=52.056666666667,-1.3575&z=18&t=h&q=Cumulus%20User@52.056666666667,-1.3575]
|-
| [http://www.mecol.co.uk/weather Blakedown, Worcs]
| Nil
| [http://maps.google.com/maps?sll=52.402576,-2.174656&z=18&t=h&q=Cumulus%20User@52.402576,-2.174656]
|-
| [http://www.vivatek.co.uk/Cumulus Blagdon, Somerset]
| Nil
| [http://maps.google.com/maps?sll=51.32316,-2.70424&z=18&t=h&q=Cumulus%20User@51.32316,-2.70424]
|-
| [http://www.bramptonweather.co.uk/cumulus/ Brampton Weather]
| Yes
| [http://maps.google.com/maps?sll=54.93514,-2.734957&z=18&t=h&q=Cumulus%20User@54.93514,-2.734957]
|-
| [http://branksomeweather.co.uk/ Branksome, Dorset]
| Nil
| [http://maps.google.com/maps?sll=50.728055555556,-1.9125&z=18&t=h&q=Cumulus%20User@50.72795,-1.91250]
|-
| [http://www.bredfield.org.uk/weather Bredfield, Woodbridge, Suffolk]
| Yes
| [http://maps.google.com/maps?sll=52.12972,1.31323&z=18&t=h&q=Cumulus%20User@52.12972,1.31323]
|-
| [http://www.weather.globalict.org.uk Broadwey, Dorset]
| Nil
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=broadwey&sll=53.800651,-4.064941&sspn=19.175733,39.506836&ie=UTF8&hq=&hnear=Broadwey,+Weymouth,+Dorset,+United+Kingdom&ll=50.649847,-2.471115&spn=0.160217,0.308647&t=k&z=12]
|-
| [http://www.keleven.co.uk/weather Burstwick]
| Default
| [http://maps.google.com/maps?sll=53.733333333333,-0.133611111111111&z=18&t=h&q=Cumulus%20User@53.733333333333,-0.133611111111111]
|-
| [http://www.craythorneweather.info Craythorne]
| Nil
| [http://maps.google.com/maps?sll=52.840277777778,-1.6347222222222&z=18&t=h&q=Cumulus%20User@52.840277777778,-1.6347222222222]
|-
| [http://www.ttnt.co.uk/weather/ Farlington, Hants.]
| Yes
| [http://maps.google.com/maps?sll=50.84722,-1.025&z=18&t=h&q=Cumulus%20User@50.84722,-1.025]
|-
| [http://myweb.tiscali.co.uk/m1byt/weather Garforth]
| Nil
| [http://maps.google.com/maps?sll=53.4739,-1.2243&z=18&t=h&q=Cumulus%20User@53.4739,-1.2243]
|-
| [http://www.furball.co.uk/weatherlive Greenford, West London]
| Nil
| [http://maps.google.com/maps?sll=51.554444444444,-0.32777777777778&z=18&t=h&q=Cumulus%20User@51.554444444444,-0.32777777777778]
|-
| [http://www.glossover.co.uk/weather Hastings, E. Sussex]
| No
| [http://maps.google.com/maps?sll=50.882947,0.562545&z=18&t=h&q=TN37Weather%20(Cumulus%20User)@50.882947,0.561700]
|-
| [http://www.rainlater.co.uk/ High Wycombe, Buckinghamshire]
| Nil
| [http://maps.google.com/maps?sll=51.638333333333,-0.77666666666667&z=18&t=h&q=Cumulus%20User@51.638333333333,-0.77666666666667]
|-
| [http://weather.mountpleasanthouse.uk/ Hoarwithy, the Wye valley, Herefordshire]
| Yes
| [https://www.google.co.uk/maps/place/Hoarwithy,+Hereford,+Herefordshire+HR2/@51.9614681,-7.1429188,6z/data=!4m2!3m1!1s0x4871b4f2a9f38bb5:0x9e49f54705503300]

|-
| [http://grid1.co.uk/weather/ Kettering UK]
| Yes
| [http://maps.google.com/maps?sll=52.391666666667,-0.73888888888889&z=18&t=h&q=Cumulus%20User@52.391666666667,-0.73888888888889]
|-
| [http://www.stewpott.com/weather Kirkstall, Leeds, West Riding of Yorkshire]
| Nil
| [http://maps.google.com/maps?sll=53.810833333333,-1.5847222222222&z=18&t=h&q=Cumulus%20User@53.810833333333,-1.5847222222222]
|-
| [http://www.laindonweather.co.uk Laindon, South Essex]
| Nil
| [http://maps.google.com/maps?sll=51.577222222222,0.41861111111111&z=18&t=h&q=Cumulus%20User@51.577222222222,0.41861111111111]
|-
| [http://www.ecats.co.uk/weather Long Melford Station, Suffolk]
| Nil
| [http://maps.google.com/maps?sll=52.066666666667,-0.71666666666667&z=18&t=h&q=Cumulus%20User@52.066666666667,-0.71666666666667]
|-
| [http://www.whatstheweatherlike.co.uk Milcombe Weather]
| Nil
| [http://maps.google.com/maps?sll=52.009444444444,-1.4027777777778&z=18&t=h&q=Cumulus%20User@52.009444444444,-1.4027777777778]
|-
| [http://www.zen55853.zen.co.uk/camera/coffee_1.htm Mobberley, Cheshire]
| Yes
| [http://maps.google.com/maps?sll=53.313888888889,-2.330556&z=18&t=h&q=Cumulus%20User@53.313888888889,-2.330556]
|-
| [http://www.newton-poppleford-weather.co.uk Newton Poppleford, Devon]
| [http://www.newton-poppleford-weather.co.uk/wxwebcam.php Yes]
| [http://maps.google.com/maps?sll=50.70189285,-3.30849957&z=18&t=h&q=Cumulus%20User@52.955833333333,-1.31361111]
|-
| [http://www.twelvehouses.co.uk New Stanton, Derbyshire]
| Nil
| [http://maps.google.com/maps?sll=52.955833333333,-1.31361111&z=18&t=h&q=Cumulus%20User@52.955833333333,-1.31361111]
|-
| [http://queensbury-weather.org.uk/ Queensbury, West Yorkshire]
| Nil
| [https://www.google.co.uk/maps/place/53%C2%B046'12.1%22N+1%C2%B049'43.4%22W/@53.7700271,-4.0699329,7z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://www.warman.org.uk/weatherhome.htm Rippingale Lincolnshire]
| Nil
| [http://maps.google.com/maps?sll=52.836,-0.377&z=18&t=h&q=Cumulus%20User@52.836,-0.377]
|-
| [http://www.thanetweather.co.uk/weather/index.htm Saint Peters Broadstairs Kent]
| Default
| [http://maps.google.com/maps?sll=51.366666666667,1.4166666666667&z=18&t=h&q=Cumulus%20User@51.366666666667,1.4166666666667]
|-
| Sheffield City Council - Emergency Services
| Nil
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=53.2154,+-1.2760&sll=53.210145,-1.381531&sspn=2.368803,4.850464&ie=UTF8&ll=53.215492,-1.276501&spn=2.368439,4.850464&z=8]
|-
| [http://www.shotwicksailing.org/weather/ Shotwick Lake]
| Nil
| [http://maps.google.com/maps?sll=53.243611111111,-3.03&z=18&t=h&q=Cumulus%20User@53.243611111111,-3.03]
|-
| [http://skegnessweather.info Skegness Weather]
| Nil
| [http://maps.google.com/maps?sll=53.153611111111,0.32805555555556&z=18&t=h&q=Cumulus%20User@53.153611111111,0.32805555555556]
|-
| [http://www.dmjsystems.co.uk/weather/ Somerset, Mendip Hills]
| Nil
| [https://www.google.co.uk/maps/place/Mendip+Hills,+Wells,+Somerset+BA5/@51.2974926,-4.9708037,7z/data=!4m2!3m1!1s0x487221c9e834a6cf:0xa591c9f318940667]
|-
| [http://www.stella-maris.org.uk/wx.phtml Stella Maris - Broadstairs]
| Nil
| [http://maps.google.com/maps?sll=51.363333333333,1.4402777777778&z=18&t=h&q=Cumulus%20User@51.363333333333,1.4402777777778]
|-
| [http://www.users.waitrose.com/~g4mix/weather Swanton Farm, Dover, Kent]
| Nil
| [http://maps.google.com/maps?sll=51.1575,1.4138&z=18&t=h&q=Cumulus%20User@51.1575,1.4138]
|-
| [http://home.btconnect.com/kophill/ Summertown, Oxford]
| Nil
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=summertown,+uk&sll=35.434799,-87.312791&sspn=0.86828,1.234589&ie=UTF8&hq=&hnear=Summertown,+Sandford-on-Thames,+Oxfordshire,+United+Kingdom&ll=51.77008,-1.262559&spn=2.63791,4.938354&z=8]
|-
| [http://www.warehamwx.co.uk/cumulus Wareham, Dorset]
| Yes
| [http://maps.google.com/maps?sll=50.6866666666666667,-2.1127777777777778&z=18&t=h&q=Cumulus%20User@50.6866666666666667,-2.1127777777777778]
|-
| [http://weather.wilmslowastro.com Wilmslow, Cheshire]
| Nil
| [http://maps.google.com/maps?sll=53.325125,-2.24263&z=18&t=h&q=Cumulus%20User@53.325125,-2.24263]
|-
| [http://www.woodfordwellsweather.co.uk Woodford Wells Essex]
| Nil
| [http://maps.google.com/maps?sll=51.613055555556,0.023333333333333&z=18&t=h&q=Cumulus%20User@51.613055555556,0.023333333333333]
|-
| [http://www.worsley-weather.co.uk Worsley, Manchester]
| Nil
| [http://maps.google.com/maps?sll=53.524444444444,-2.3858333333333&z=18&t=h&q=Cumulus%20User@53.524444444444,-2.3858333333333]
|}

===== Northern Ireland =====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.darkmoon.org.uk/weather Bangor]
| Yes
| [http://maps.google.com/maps?sll=54.6341666666666667,-5.6716666666666667&z=18&t=h&q=Cumulus%20User@54.6341666666666667,-5.6716666666666667]
|}

===== Scotland =====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.southqueensferryweather.co.uk/ Edinburgh (South Queensferry) ]
| Yes
| [http://maps.google.co.uk/maps?q=55.990827,-3.413867&hl=en&ll=55.986092,-3.405762&spn=1.88368,7.761841&t=h&z=8]
|-
| [http://www.floodaction.org.uk/blog/weather/ Freuchie, Fife - Freuchie Mill]
| [http://www.floodaction.org.uk/blog/webcam/ Yes]
| [http://maps.google.com/maps?sll=56.2463,-3.1475&z=18&t=h&q=Cumulus%20User@56.2463,-3.1475]
|-
| [http://kippfordWeather.uk Kippford, Dumfries & Galloway]
| No
| [https://www.google.co.uk/maps/place/Kippford,+Dalbeattie,+Dumfries+and+Galloway+DG5/@54.8800492,-6.056103,7z/data=!4m2!3m1!1s0x4862db154667d8c3:0x1c650d52b9f9be36]

|-
| [http://www.knaven-weather.co.uk Knaven, Aberdeenshire]
| Nil
| [http://maps.google.com/maps?sll=57.471388888889,-2.184448&z=18&t=h&q=Cumulus%20User@57.471388888889,-2.184448]
|-
| [http://www.sanday.org.uk/weather Orkney Isles - Sandaysoft]
| Yes
| [http://maps.google.com/maps?sll=59.2425,-2.5877777777778&z=18&t=h&q=Cumulus%20User@59.2425,-2.5877777777778]
|-
| [http://weather.penicuik.org/ Penicuik, Midlothian]
| No
| [https://www.google.com/maps/place/55%C2%B050'02.8%22N+3%C2%B012'12.6%22W/@55.8334412,-4.3304793,7.99z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://ken555.plus.com/weather/index.htm Pitmedden, Aberdeenshire]
| [http://ken555.plus.com/index.html Yes]
| [http://maps.google.com/maps?sll=57.33889,-2.184167&z=18&t=h&q=Cumulus%20User@57.33889,-2.184167]
|-
| [http://www.stirlingweather.co.uk Stirling, Stirlingshire]
| Nil
| [http://maps.google.com/maps?&sll=56.1165,-3.9550&z=18&t=h&q=Cumulus%20User@56.1165,-3.9550]
|}

===== Wales =====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.hosiene.co.uk/weather/ Ystrad, Rhondda Cynon Taff]
| Nil
| [https://www.google.co.uk/maps/@51.6480374,-3.4804831,15z]
|-
| [http://www.llandudno.eu.pn Llandudno]
| Yes
| [http://maps.google.com/maps?sll=53.316666666667,-3.8333333333333&z=18&t=h&q=Cumulus%20User@53.316666666667,-3.8333333333333]
|-
| [http://www.aqsj01.dsl.pipex.com/weather Llantwit Fardre]
| Default
| [http://maps.google.com/maps?sll=51.553333333333,-3.3344444444444&z=18&t=h&q=Cumulus%20User@51.553333333333,-3.3344444444444]
|-
| [http://nusc.co.uk/weather/index.htm Newport Uskmouth Sailing Club]
| Yes
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=newport&aq=&sll=53.800651,-4.064941&sspn=17.235515,41.484375&ie=UTF8&hq=&hnear=Newport,+United+Kingdom&ll=52.321911,-4.020996&spn=8.896784,29.11377&z=6]
|-
| [http://www.bblist.co.uk/weather/ Vale of Glamorgan]
| Default
| [http://maps.google.com/maps?sll=51.469167,-3.432222&z=18&t=h&q=Cumulus%20User@51.469167,-3.432222]
|-
| [http://www.moelycrio.co.uk Moelycrio]
| Nil
| [http://maps.google.com/maps?sll=53.2,-3.2&z=18&t=h&q=Cumulus%20User@53.2,-3.2]
|-
| [http://www.winterman.org.uk/weather Spittal Weather - Pembrokeshire]
| Default
| [http://maps.google.com/maps?sll=51.871666666667,-4.9380555555556&z=18&t=h&q=Cumulus%20User@51.871666666667,-4.9380555555556]
|}

=== North America ===

==== Canada ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.genisim.com/weather/index.htm Jonquiere Quebec - GeniSim]
| Yes
| [http://maps.google.com/maps?sll=48.435277777778,-71.200277777778&z=18&t=h&q=Cumulus%20User@48.435277777778,-71.200277777778]
|-
| [http://www.komokaweather.com/ Komoka, ON]
| Nil
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&q=Komoka,+Middlesex+Centre,+Middlesex+County,+Ontario,+Canada&sll=37.0625,-95.677068&sspn=50.777825,79.013672&ie=UTF8&cd=1&geocode=FeRWjwIdQGMl-w&split=0&hq=&hnear=Komoka,+Middlesex+Centre,+Middlesex+County,+Ontario,+Canada&ll=42.948324,-81.43584&spn=5.918291,9.876709&t=h&z=7]
|-
| [http://pages.videotron.com/meteo/ Lévis, QC]
| Nil
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=Levis,+Quebec,+Canada&aq=0&sll=37.0625,-95.677068&sspn=50.910968,78.486328&ie=UTF8&hq=&hnear=L%C3%A9vis,+Desjardins,+Quebec,+Canada&ll=46.800059,-71.630859&spn=42.037232,111.972656&t=h&z=4]
|-
| [http://weather.bpsmicro.com Newmanville (Ottawa), ON]
| Nil
| [http://maps.google.com/maps?sll=44.928055555556,-75.75777777778&z=18&t=h&q=Cumulus%20User@44.928055555556,-75.75777777778]
|-
| [http://meteo.spudman.ca Quebec City]
| Yes
| [http://maps.google.com/maps?sll=46.889444,-71.193611&z=18&t=h&q=Cumulus%20User@46.889444,-71.193611]
|-
| [http://members.shaw.ca/seabreeze3/meteo Saanichton, British Columbia]
| Nil
| [http://maps.google.com/maps?sll=48.59188,-123.40015&z=18&t=h&q=Cumulus%20User@48.59188,-123.40015]
|-
|}

==== United States ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://berkland.net Arlington, VA]
| No
| [http://maps.google.co.uk/maps?q=38.88,+-77.102222&hl=en&ll=38.88,-77.102222&spn=12.016521,21.533203&sll=57.746995,-4.687341&sspn=8.25173,21.533203&t=v&z=6]
|-
| [http://www.tigerdenweb.com/tigerdenwx/ Aurora, Colorado]
| No
| [https://www.google.co.uk/maps/place/Aurora,+CO,+USA/@39.6887508,-122.6165289,4z/data=!4m2!3m1!1s0x876c588622ba2b9b:0x8441e0688ba2e678]
|-
| [http://branfordwx.com/cumulus/index.htm Branford, CT]
| Yes
| [http://maps.google.com/maps?sll=41.276111,-72.828333&z=18&t=h&q=Cumulus%20User@41.276111,-72.828333]
|-
| [http://www.jandanet.com/weather/cumulus/ Cloverville - Fruitport Township, MI]
| Nil
| [http://maps.google.com/maps?sll=43.190555555556,-86.165277777778&z=18&t=h&q=Cumulus%20User@43.190555555556,-86.165277777778]
|-
| [http://www.kd0bik.com/denwx/ Denver, CO]
| Default
| [http://maps.google.com/maps?sll=39.634166666667,-104.88972222222&z=18&t=h&q=Cumulus%20User@39.634166666667,-104.88972222222]
|-
| [http://www.chucksweather.com/cumulus Glendive, Montana - Chucks Weather]
| Default
| [http://maps.google.com/maps?sll=47.119722222222,-104.70314789&z=18&t=h&q=Cumulus%20User@47.119722222222,-104.70314789]
|-
| [http://cumulus.tnetweather.com Mesa, AZ - TNETWeather]
| Nil
| [http://maps.google.com/maps?sll=33.40231,-111.8831&z=18&t=h&q=Cumulus%20User@33.40231,-111.8831]
|-
| [http://www.moutoncoveweather.com/ Mouton Cove, Abbeville, LA]
| [http://www.moutoncoveweather.com/webcam.php Yes]
| [http://maps.google.com/maps?sll=37.95645,86.572266&z=18&t=h&q=Cumulus%20User@37.956457,86.572266]
|-
| [http://robsweather.no-ip.org/cumulusweb/index.htm Moraine, OH]
| Nil
| [http://maps.google.com/maps?sll=39.691388888889,-84.206111111111&z=18&t=h&q=Cumulus%20User@39.691388888889,-84.206111111111]
|-
| [http://dantinconsulting.com Prospect, KY - Timber Ridge Weather]
| Nil
| [http://maps.google.com/maps?sll=38.33235,-85.61603&z=18&t=h&q=Cumulus%20User@38.33235,-85.61603]
|-
| [http://weather.ejmj.net Reklaw, Texas]
| Nil
| [http://maps.google.com/maps?sll=31.84348611,-94.96843888&z=18&t=h&q=Cumulus%20User@31.84348611,-94.96843888]
|-
| [http://www.royalmountainresources.com/weather Royal Mountain, Bailey, CO]
| No
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=Bailey,+CO,+United+States&sll=39.3173,-105.331421&sspn=2.813262,4.674683&ie=UTF8&hq=&hnear=Bailey,+Park,+Colorado&ll=39.419221,-105.46875&spn=11.231107,18.69873&z=6]
|-
| [http://smlweather.com/cumulus/index.htm Smith Mountain Lake, VA]
| Nil
| [http://maps.google.com/maps?sll=37.1526,-79.678&z=18&t=h&q=Cumulus%20User@37.1526,-79.678]
|-
|}

=== Oceania ===

==== Australia ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.brisbaneliveweather.com Brisbane, QLD]
| Yes
| [http://maps.google.com/maps?sll=-27.294606,152.933897&z=18&t=h&q=Cumulus%20User@-27.294606,152.933897]
|-
| [http://www.sedgleymanor.com/wx Bunbury, WA]
| Yes
| [http://maps.google.com/maps?sll=-33.37861,115.65194&z=18&t=h&q=Cumulus%20User@-33.37861,115.65194]
|-
| [http://www.users.on.net/~mpaton/weather/ Bushland Beach, Qld]
| Nil
| [http://maps.google.com/maps?sll=-19.198055555556,146.676111&z=18&t=h&q=Cumulus%20User@-19.198055555556,146.676111]
|-
| [http://www.azer.com.au/weather_carrum/ Carrum, Victoria]
| Yes
| [http://maps.google.co.uk/maps?q=Carrum,+Victoria&hl=en&ll=-38.076027,145.123199&spn=12.151038,21.533203&sll=-33.708009,150.974708&sspn=25.579176,43.066406&t=v&hnear=Carrum+Victoria,+Australia&z=6]
|-
| [http://members.ozemail.com.au/~storerfamily/weather/ Crafers, SA]
| Yes
| [http://maps.google.com/maps?sll=-34.989444,138.727778&z=18&t=h&q=Cumulus%20User@-34.989444,138.727778]
|-
| [http://weather.inverellit.com/ Inverell, NSW]
| Yes
| [https://www.google.com/maps/place/Ross+St,+Inverell+NSW+2360/@-29.7732835,151.1194221,17z/data=!3m1!4b1!4m5!3m4!1s0x6ba1f7461c668835:0x86b3447dd776ecb8!8m2!3d-29.7732835!4d151.1216108]
|-
| [http://www.azer.com.au/weather/ Langwarrin, Victoria]
| Yes
| [http://maps.google.co.uk/maps?q=Langwarrin,+victoria&hl=en&ll=-33.708009,150.974708&spn=25.579176,43.066406&sll=57.746995,-4.687341&sspn=8.25173,21.533203&t=v&hnear=Langwarrin+Victoria,+Australia&z=5]
|-
| [http://users.tpg.com.au/howesij/weather/index.htm Nomads Weather - Ferny Grove, QLD]
| Yes
| [http://maps.google.com/maps?sll=-27.395833333333,152.91861111111&z=18&t=h&q=Cumulus%20User@-27.395833333333,152.91861111111]
|-
| [http://weather.gktnet.com North Bayswater, Victoria]
| No
| [http://maps.google.com/maps?sll=-37.823611111111,145.29638888889&z=18&t=h&q=Cumulus%20User@-37.823611111111,145.29638888889]
|-
| [http://members.westnet.com.au/paul.anderson/weather/ Perth]
| No
| [http://maps.google.com/maps?f=q&source=s_q&hl=en&geocode=&q=perth,+australia&sll=37.0625,-95.677068&sspn=45.822921,85.166016&ie=UTF8&hq=&hnear=Perth+Western+Australia,+Australia&ll=-31.952162,115.400391&spn=45.595762,118.652344&z=4]
|-
| [http://www.users.on.net/~rolf/cumulus/ Rosetta, Glenorchy, Tasmania]
| Yes
| [https://goo.gl/maps/SMxemgd5bxS2]
|-
| [http://tonyf.customer.netspace.net.au/weather/ Sale, Gippsland, Victoria]
| Nil
| [http://maps.google.co.uk/maps?f=q&source=s_q&hl=en&geocode=&q=-38.1008+147.075556&sll=-35.029996,130.605469&sspn=0.18161,0.452156&ie=UTF8&ll=-38.134557,138.779297&spn=44.181081,115.751953&t=h&z=4]
|-
| [http://www.wunderground.com/weatherstation/WXDailyHistory.asp?ID=I3099STR2 Strathewen, Melbourne]
| Nil
| [http://maps.google.com/maps?sll=-37.523,145.281&z=18&t=h&q=Cumulus%20User@-37.523,145.281]
|-
| [https://southfranklinweather.com South Franklin, Huon Valley, Tasmania]
| Yes
| [https://www.google.co.uk/maps/place/43%C2%B007'17.8%22S+146%C2%B059'20.9%22E/@-43.121605,111.1297573,3z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://weather.gkt.net.au/ Wyndham Vale, VIC]
| No
| [http://maps.google.com/maps?sll=-37.896988,144.616897&z=18&t=h&q=Cumulus%20User@-37.896988,144.616897]
|-
| [http://users.on.net/~freespirit/weather Fern Tree, Tas]
| No
| [http://maps.google.com.au/maps?f=q&source=s_q&hl=en&geocode=&q=fern+tree+tasmania&sll=-25.335448,135.745076&sspn=56.198906,79.013672&ie=UTF8&hq=&hnear=Fern+Tree+Tasmania&ll=-42.92334,147.260742&spn=0.011486,0.01929&t=h&z=16]
|}

==== Indonesia ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.ubudweather.com/ Ubud, Bali]
| No
| [https://www.google.com/maps/place/8%C2%B031'40.5%22S+115%C2%B015'00.1%22E/@-8.5279162,114.1294222,8z/data=!4m2!3m1!1s0x0:0x0?hl=en]
|}

==== New Zealand ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.janter.co.nz/weather/index.htm Farm Cove, Auckland]
| Yes
| [https://www.google.com/maps/place/36%C2%B032'03.5%22S+174%C2%B032'03.5%22E/@-36.5342957,172.2930836,7z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://www.silveracorn.nz/weather/index.php Royal Oak, Auckland]
| No
| [https://www.google.com/maps/place/36%C2%B032'03.5%22S+174%C2%B032'03.5%22E/@-36.909691,174.771256,7z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://wairoaweather.net/frasertown/index.htm Frasertown, Hawkes Bay]
| Nil
| [http://maps.google.com/maps?sll=-38.965818666666,177.40800977777&z=18&t=h&q=Cumulus%20User@-38.965818666666,177.40800977777]
|-
| [http://www.gabbie.nz/ Hamilton]
| No
| [http://www.google.co.uk/maps/dir//-37.7948899,175.2711855/@-37.7985524,175.2673231,3z]
|-
| [http://wairoaweather.net/gisborne-west/index.php Gisborne West, Poverty Bay]
| Nil
| [https://www.google.com/maps/place/38%C2%B023'07.8%22S+177%C2%B035'35.2%22E/@-38.3854958,173.1106727,6z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://nzpws.net/mahia/index.htm Mahia Heights, Northern Hawkes Bay ]
| Nil
| [https://www.google.com/maps/place/39%C2%B003'06.8%22S+177%C2%B031'26.8%22E/@-39.0518958,173.0335206,6z/data=!4m2!3m1!1s0x0:0x0]

|-
| [http://homepages.xnet.co.nz/~wheels/weather/ Otatara, Invercargill - Wayne's Weather]
| Nil
| [http://maps.google.com/maps?sll=-46.431667,168.292222&z=18&t=h&q=Cumulus%20User@-46.431667,168.292222]
|-
| [http://www.wunderground.com/weatherstation/WXDailyHistory.asp?ID=IMANAWAT1 Palmerston North]
| Nil
| [http://maps.google.com/maps?sll=-40.352222222222,175.635&z=18&t=h&q=Cumulus%20User@-40.352222222222,175.635]
|-
| [http://www.pare361.co.nz Paremoremo, Auckland]
| Yes
| [http://maps.google.com/maps?sll=-36.7575,174.665&z=18&t=h&q=Cumulus%20User@-36.7575,174.665]
|-
| [http://wairoa.net/weather/index.htm Wairoa, Northern Hawkes Bay Weather Live]
| Yes
| [http://maps.google.com/maps?sll=-39.045166022222,177.42639166667&z=18&t=h&q=Cumulus%20User@-39.045166022222,177.42639166667]
|-
| [http://nzpws.net/gisborne/index.htm Whataupoko, Gisborne Weather]
| Nil
| [https://www.google.com/maps/place/38%C2%B023'31.6%22S+178%C2%B001'15.6%22E/@-38.3920958,175.7797836,7z/data=!4m2!3m1!1s0x0:0x0]
|-
| [http://weather.magnumimports.co.nz Whitemans Valley Upper Hutt]
| Nil
| [http://maps.google.com/maps?sll=-41.1971658635502,175.027792405373&z=18&t=h&q=Cumulus%20User@-41.1971658635502,175.027792405373]
|}

=== South America ===

==== Argentina ====

{| class="wikitable"
|-
! style="width:350px" | User
! style="width:100px" | Webcam
! style="Width:100px" | Map
|-
| [http://www.meteobaires.webcindario.com Bellavista, Provincia de Buenos Aires]
| Yes
| [http://maps.google.com/maps?sll=-34.553055555556,-58.696388888889&z=18&t=h&q=Cumulus%20User@-34.553055555556,-58.696388888889]
|-
| [http://www.arecoclima.com.ar Buenos Aires - Areco747 Weather Station]
| Nil
| [http://maps.google.com/maps?sll=-34.2442,-59.4763&z=18&t=h&q=Cumulus%20User@-34.2442,-59.4763]
|-
| [http://www.viapatagonica.com.ar/clima/ Via Patagonica]
| Nil
| [http://maps.google.com/maps?sll=-47.750277777778,-65.893888888889&z=18&t=h&q=Cumulus%20User@-47.750277777778,-65.893888888889]
|-
| [http://cipometeo.webcindario.com/ estacion cipolletii privada tiempo]
| Default
| [http://maps.google.com/maps?sll=-38.937,-67.979&z=18&t=h&q=Cumulus%20User@-38.937,-67.979]
|}

== Further Additions ==

Your Username & Location can be added to this list by Contacting [[User:Daj]] or if you are a registered user, editing this page yourself.

'''Note:''' ''The links to the location have the user latitude and longitude in them twice, once for centreing the map, the second time for the marker location. These are given in decimal degrees. +ve for Northern latitudes and Eastern longitudes, -ve for Southern latitudes and Western longitudes. Use the co-ordinates you have entered into your Cumulus Station configuration.''