MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
 
(169 intermediate revisions by 7 users not shown)
Line 1: Line 1:
=Using MX on UNIX-derived Operating Systems=
=Using MX on UNIX-derived Operating Systems=
[[Category:Cumulus MX]]
MX runs on any UNIX-derived operating systems (OS):
* including those found on Apple Mac computers,
* and those found on a multitude of devices running Linux.


UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn just once and then you can normally continue to use what you have learnt.
MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.


Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.
==This article focuses on a computer called the Raspberry Pi==


Although the article focusses on one computer type, the Raspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to another Unix-derived devices.


==Why install MX on Linux?==
In the Cumulus support forum, there are many posts from people who are struggling with using Windows PCs, and it seems a lot of them find "installing" MX difficult.


Contributions to the [https://cumulus.hosiene.co.uk/viewforum.php?f=40 Cumulus Support Forum] suggest that:
The same forum reveals few posts from people struggling with setting up the Raspberry Pi, and several posts reporting success with using MX on this small computer.
*Use on a Raspberry Pi (RPi) computer is very popular
*In general, people find installing, and running, MX on Linux is easy
*The few people who do have difficulties are those who have good knowledge of Microsoft systems and therefore are so convinced they cannot cope with a swap to something different, that they give up too easily!


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


You may know that this Wiki started with a single page covering MX regardless on which operating system was used, that did not work.
{{TOCright}}
*The Raspberry Pi is a simple computer that is far easier to learn than a complicated machine like a Personal Computer (PC) running Windows.
*You can choose either to install the Windows operating system on your Raspberry Pi or to install the simpler Raspberry Pi operating system (based on debian Linux).
**This article focusses on the latter as another article covers Windows.
**You don't need to learn much Linux, but this article does cover some commands.
*The Raspberry Pi is ideal to run Cumulus MX
**The Raspberry Pi is a computer that is better for the environment, unlike a PC manufactured with lot of components, and a PC wastes a lot of electricity if left running.
**Downloading the release distribution, and unzipping the files, is the same on any device
**On Linux you need to (simply) manually install one extra component (Mono-complete), while the equivalent component (.NET) is automatically installed on Windows.
**Running MX is same on any device (precise command syntax to start it varies, but what MX does when running does not depend on device)
*It is simplest to connect keyboard and monitor to the Raspberry Pi so all actions are done directly on it.
*Some optional topics are also covered.
**One option covered is adding a web server and a database server
**Another option discussed is using a PC to control a "headless" Raspberry Pi (i.e. one without keyboard and without monitor).


If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the [[MX on Windows OS]] page instead. In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs. It appears this is not because Microsoft computers are so more readily available and therefore known about; but because people often find “installing”, and using, MX is more difficult when using the more complex Microsoft Windows operating system, and people tend not to understand basic issues such as avoiding "Program Files".
==Introduction==




{{Template:Version badge Mx}}'''This page focuses on aspects of MX that are specific to the Linux operating systems.'''
It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).


Still believe it will be too complex for you? The developer has created [[Software#Raspberry_Pi_Image|an image you can download]] for those prepared to run two computers (a RPi for actually running MX and another computer for all interactions with MX). Read all about it, on [[Raspberry_Pi_Image]] page, and decide if that is for you.
In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi.


==Device Coverage==
The Apple Mac runs its own version of Unix, and while standard Unix uses Line_Feed to terminate lines in files, the Mac uses Carriage_Return. Hopefully someone will write an article about the Mac in this Wiki, but in meantime this is closest you can get.


Linux is available based on a multitude of different kernels (the building block for the operating system), on a multitude of devices.
The article will give you some guidance on:
*Choosing a Pi model to buy
*Setting up a Raspberry Pi,
*Installing OS (the NOOBS described here can install various OS, you choose which one you want)
*Installing Mono (needed on any Linux based OS, but can even run on Windows!)
*Installing MX
*Running MX (these notes apply to any Linux OS, but some hints need consideration even in Windows)


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


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


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


==Further Information==
=Which Raspberry Pi to buy=


There are various related pages to get more information:
A standard desktop computer consumes at least 200 Watts of power (that is when it is idle, it will increase depending on peripherals attached and any processing being done) all the time it is switched on. A Pi Zero W consumes half a Watt when idle, and up to 1.78 Watt when running tasks or connected to peripherals. A Pi model 4 B (the latest model at time of writing) consumes 2.85 to 80 Watt depending on whether it is idle or working hard. Although Cumulus MX does not need to run 24/7, derived values like highest, lowest, average, and so on, will be more accurately calculated if MX is left running. Although the Pi is not the only small computer model available, it is probably the most popular and the easiest one to use if you do want to run MX all the time and not wreck the planet!
* If you encounter a problem when running MX, please see [[What to do when I have a problem with MX]]
* If MX gives you a message saying "you are not running the latest version", please see [[Updating_MX_to_new_version|Guide to upgrading MX]]
* If you are puzzled by the terminology, please see [[:Category:Terminology]] for links to pages that explain terminology used by Cumulus (these pages were written for the legacy Cumulus 1 and may need updating for MX)
* If you need to know more about files in the installation, please see [[:Category:Cumulus Files]] for links to all Wiki pages describing the sub-folders and files used by MX
* Go to [[:Category:Cumulus MX]] for links to all pages in this Cumulus Wiki that relate specifically to MX
* [[MX Administrative Interface|Admin interface]] provides information on configuration and web pages for viewing your weather data locally
* The [[Cumulus MX FAQ]] page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
* If you were using the original (now legacy) Cumulus software, please read [[Migrating_from_Cumulus_1_to_MX]], although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
* If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page
* If you will be using the standard web pages (from release 3.10.1) see [[New_Default_Web_Site_Information|this page]]
* If you want to write your own customised templates, read [[Customised_templates]].
* If you want to explore alternative web pages from third-parties, start [[:Category:User Contributions|on User Contributions page]].


==First make a list of what you need==


*Do you want to use a mouse and key board?
** If so, a model with multiple USB sockets is advisable (like 3B+)
** This also applies if you want to be able to plug in a USB stick (perhaps for transferring files between devices, e.g. Cumulus configuration and data folder files)
*Do you want a wired connection to your hub or router?
** Maybe you are going to update external sites, a wired connection may provide a faster and more dependable communication than a wireless link
** If so, a model including an Ethernet socket is advisable (like 3 B+)
** Remember that if you are operating the pi in headless mode, a wired or wireless connection to your LAN is needed for your other device to communicate with the Pi
*Will your MX need to update a database, feed data to a web site, upload to external sites, or control other devices?
** If so, a model Zero will have to do each task in turn, and you will see some delay in information updates, plus you will need to use a larger time between updates
** If so, a model Three (or Four) will be noticeably faster, and support all options in MX, and can update external sites more frequently
* What interface does your weather station use?
** If your station communicates to MX via wireless, then you choose a model that supports wireless at the right frequency, all models support basic wireless
** If your station communicates via Ethernet, then either a wired, or wireless, connection is possible between router/hub and Pi as the station will be plugged into your hub or router
** If your station communicates to MX via USB, then choose between the model 0W with one USB socket, and the model 3B+ with 4 USB sockets depending on whether you might want to use another USB socket ever
** If your station uses another communication port (such as serial interface), then you need the additional components that support that interface


=Preparing your computer for installing the Cumulus MX suite=
== Now research how the various models relate to your needs ==


Please see [[Preparing your Linux computer for MX]] page if you have not installed MX on Linux before.
You can look up online what features are included in the various Pi models, and how they differ in power consumption, and cost. But your decision also needs to consider what you need. Here, I won't describe all the different models, but concentrate on just 2 for simplicity.


That page covers:
The model Zero W is appealing as it has low power consumption, it is perfectly adequate for running MX (but has limited speed, it runs the various threads MX uses sequentially) especially if you only use standard MX functionality and don't ask MX to do all the optional extras, and has limited interfaces for peripherals.
* [[Preparing your Linux computer for MX#Operating systems|Installing Operating Systems]]
* Package manager
** [[Preparing your Linux computer for MX#Interactive Package management on RPi|Interactive version]]
** [[Preparing your Linux computer for MX#Using Package Manager in terminal mode|Terminal version]]
** [[Preparing your Linux computer for MX#The various components to commands for installation|Commands]]
* [[Preparing your Linux computer for MX#USB HID|Human Interface Devices]]
* [[Preparing your Linux computer for MX#Installing Mono instruction|'''Installing Mono''']]
* [[Preparing your Linux computer for MX#Moving from Microsoft Windows to Linux|Preparing Microsoft Windows files for Linux]]
* [[Preparing your Linux computer for MX#File Names & Paths|Guide to file names and paths]]


The model Three B plus is appealing as it has medium power consumption, but can cope better with the multiple threads that MX starts, and has more interfaces built in, such as 4 USB 2 ports (useful if you want to connect a weather station using USB and connect a keyboard).


While both models support wireless links and Bluetooth, the latter model also allows a wired Ethernet connection, and that may be useful if that is how you connect to your weather station (an Ethernet connection is also advisable if you want to install a web server, on your Pi). Having an Ethernet connection, as explained later, makes it possible to easily install the Windows Operating System on your Raspberry Pi on first boot.


Please be advised some of the above is rather technical reading, but ''Mono is required to run the Cumulus packages'' described next. So do ensure that you installed Mono before continuing.
* Raspberry Pi Zero W
** Pi Zero W has WiFi and one micro-USB port which is all that is needed for headless running.
** Installing onto a faster Pi might speed parts of the installation process, but for actual ‘production’ running this slower, and simpler, Pi will be perfectly adequate.
** It could run a web server, but that might really slow it down.
** If you run this headless, all updates are done remotely, so the connectivity and speed of the actual Pi are less important
* Raspberry Pi Three B Plus
** The faster speed of this Pi although NOT necessary for running Cumulus MX, will cope better if you are asking MX to do lots of processing (e.g. updating database tables or external sites as well as standard processing).
** Pi Three B Plus has a socket for an external power supply, Ethernet socket (supports wired link); a HDMI socket for audio/video to TV, or computer monitor; a standard jack audio socket for external headphone, or speaker; 4 standard USB type 2 sockets for weather station, mouse, keyboard, USB stick, or other storage device; plus other connections (e.g. camera).
** This might be better if you also want to run a web server, and if you want to do other tasks (e.g. word processing - '''Libre Office''' is installed as standard on a Pi) on the same Pi.
** Also consider this model if it is to be used on a remote site so when you visit it is useful to be able to plug in a monitor and other peripherals, and to spend as little time on updating as possible.


==Technical aside==
Other models are available, but you need to check their specification against your needs. For example, the current model Four has more capabilities, but may be less appealing as it also consumes more power.


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


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


For the purposes of this Wiki, the terminology "operating system" is used for the whole Linux distribution, you will find that Linux technical people prefer to talk about Linux distributions including:
Generally buying as a kit is cheaper than buying items individually. A typical kit includes the Pi board with components and interfaces on it, a power supply (with a plug suitable for your mains sockets), a micro-SD card (see later sub-section), some connection leads, and a case that you can fit the board into to protect it.
# a "kernel" for the underlying handling of files, network and so on;
# one or more "shell" components for the handling of commands entered in terminal mode, including those that run programs (whether included in distribution or added later);
# an optional graphical user interface for simpler access to commands and programs.


For simplicity the terminology "terminal" is used for how you access the shell, this term refers to seeing the command prompt if your Linux is running without a graphical user interface, or to a window that you can open within the graphical interface where commands can be typed. Depending on your Linux, that window might be called "Terminal", "Konsole", "xterm", "gnome-terminal", "uxterm", or even something else. If you are accessing your Linux computer over a network from a computer running Microsoft Windows, then again you may encounter a number of terms for how to access the shell on your Linux computer, "Command Window", "Windows Powershell", or "Windows Terminal". Equally you may use software that calls it a teletype mode, e.g. PuTTY software.
You may want to buy a case, that will protect your Pi from accidental damage. A case specifically designed for your Pi model will have cut-outs in the right place for each interface connection, and will have sufficient ventilation for the electrical components to not over-heat. Some designs have additional holes for securing peripherals.


=Cumulus packages=
You may need a power supply.
*This could be an official Raspberry Pi power supply.
*Alternatively, any power supply unit that has a micro USB connector will do, the power consumption of a Pi (whichever model) is fairly small, but it will be powered on 24/7, so a low power consumption ‘switched mode’ type is preferred – i.e. one that does not become warm when plugged in with nothing attached.
**You may have a suitable one left over from an earlier mobile phone.


* This section covers:
You may need to buy connection leads:
** CumulusMX.exe
*You may need a HDMI lead to connect your PI to your TV or a spare computer monitor.
** ExportToMySQL.exe
*You may need a USB lead to connect to your weather station (the Pi model Zero requires a micro USB, the Pi model 3 requires a standard A end USB) and your station probably has a USB A end connection.
** CreateMissing.exe
*If your weather station connects by Ethernet, you will need one lead to connect the station to the router and possibly another to connect the hub or router to the Pi.


(At time of writing this "CreateRecords.exe" is proposed, and under development, but not released).
If you do choose a model 3 (or later), consider whether you do want to buy a USB mouse and USB keyboard to use with it.
Finally, you may wish to buy a second micro-SD unit as a spare, or some other USB connected (or network connected) storage for back-ups and extra storage needs.


= Setting up your Pi =


==Handling zip files==
You can find, online, instructions (and videos) about setting up a Pi. A search engine will give you multiple choices!


Each release is presented as a zip. It does not matter which device (if you have two or more computers), or which browser (it can be default browser for your device or the browser you like best) you use for the download. When your browser saves the zip it might be into a folder called “downloads” on your computer, or you may be able to save into another folder that you prefer (perhaps on a different partition). Your browser might even remember the folder you used before for files of type zip.
*The obvious place to look is [https://www.raspberrypi.org/documentation/setup/ the manufacturer's web site], they have the same documentation on [https://github.com/raspberrypi/documentation/blob/master/setup/README.md their github page].
*You may prefer to look at [http://www.okdo.com/gettingstarted or another supplier's web site],
* or you can always look various general sources of "how to" advice.


In general, any device will load a suitable application to use to unzip the package when you click on a filename that ends in '''.zip'''. You might need to do a "right click" and choose the application, it depends on your settings.
In this article, each step in installation is covered, but there is now an alternative to installing operating system, mono, and MX separately, a single '''image''' that contains all elements needed can be downloaded from the [[Software#Current_Release|Software page Current_Release section]], read about using it in [[Raspberry_Pi_Image]] article.


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


For example on the Raspberry Pi operating system, there is a package called '''xarchiver''', in its Graphical User Interface (GUI), there is a menu called "Action", and the final option in that menu is "Preferences". There, in "Archive" section, you can select "zip" as the preferred archive format (using a drop-down) and whether you want the application to confirm with you before deleting any files; in "Advanced" section, you can select the directory to use for the extraction. If you are using the lite version of the RPi OS, then you need to edit the '''/home/pi/.config/xarchiver/xarchiverrc''' file to set preferences, before you use the archiver package. Once you have started the archiver package, and told it which file to process, you can click on '''Extract files''',
You will need a micro-SD card (preferably class 10, the class number indicates the relative speed of read/write compared to original design, so this class is 10 times faster).
the GUI presents a screen of options:
* "Extract to:", use the icon to browse to the required location if it has not been set up in preferences
* "Ensure a containing directory", tick this if it has not been set in the configuration file
* "Files", select "All files", the advice is to overwrite all of any existing files if you are upgrading, but you definitely need all files if this is a new install
* "Options"
** Tick "Extract files with full path", this is essential if you are going to successfully install any of the Cumulus software
** Tick "Overwrite existing files", the advice is to overwrite all of any existing files if you are upgrading, it may not always be clear which files have been updated since an earlier release, and there are a lot of interdependencies between different files


It is worth stressing here, if you decide to customise any files that are included in a release distribution, then you should at the very least add something like an "_" character to the file name to make your tailored file different to the standard file. The best practice is to put any files you tailor, or any additional files you create, outside the CumulusMX folder.
#A Pi will work with either a class 4 (only 4 times faster), or a class 10, micro-SD card.
#Just for the standard install you need a card with a '''minimum of 8 GB'''.
#Given we are going to add Mono and Cumulus MX to the card, I advise you buy a card with at least 16 GB (as the default operating system installation takes up almost half of that),
#* but you might prefer to buy a 32 GB or 64 GB (or add an external USB drive or USB memory stick) if you intend to keep a lot of data on the Pi.


If you have chosen to do the download on a different device to that on which you will install, you can unzip on either device. To transfer either the downloaded .zip file, or the extracted file structure, between devices, you can use a file transfer package, or use a portable drive (a memory stick or even a memory card) with a partition formatted so that you can read it on both devices. Windows and Linux partitions are formatted in different ways. While it is likely that Linux can read a Microsoft formatted partition, Microsoft Windows can never read a Linux formatted partition.
I won't mention manufacturer names here, but one well known brand (that uses descriptions like extreme) is the market leader, and does have greater reliability than cheaper cards from other manufacturers.


==Where to install all packages?==
''Setting up a Pi is simpler'' '''if you buy a micro-SD card that is''':
* either pre-installed with [https://github.com/raspberrypi/documentation/blob/master/installation/noobs.md NOOBS (Novel Out of Box Software)],
* or pre-installed with the Raspberry Pi operating system.


For simplicity on this page CHOSEN PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.
NOOBS makes it easy to install (by default) Raspberry Pi operating system, as if you insert such a micro-SD card into a new Raspberry Pi computer, when you power up the Pi, the operating system will be installed during that first boot. If you have a Raspberry Pi model with an Ethernet connection, and you connect your Pi to your hub/router before you first switch it on, then at that first boot, NOOBS will offer you a choice of several operating systems, with Raspberry Pi as first choice.


The phrase “CHOSEN PATH” is used, because it is most likely you want to create the sub-folder called “/CumulusMX” (note where capital letters must be used) in a part of the Linux file structure that already exists.
Various suppliers offer cards of 16 to 64 GB with NOOBS pre-installed ready for use in a Pi (I bought from a firm in Haverhill, Suffolk, UK).


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).
My advice is to buy your micro-SD card from a firm that specialises in selling Raspberry Pi computers and accessories. That should ensure you buy a card with the latest version of NOOBS (or Raspberry Pi Operating System) and that will make your life simpler than buying a blank micro-SD card and having to down load and add the operating system yourself.


If you want to be able to use the micro-SD card in other devices (like your PC), you may need to also buy an adapter which allows the micro-SD card to be plugged into a standard SD socket. This may be included if you buy a micro-SD card not sold specifically for the Pi, or may be available with the Pi micro-SD under a special offer for buying two items together.


===Creating the CumulusMX sub-folder===
== The Operating System ==


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


==Packages to install==
To keep this article simple, I will assume you have bought a micro-SD card either pre-installed with an operating system (OS) so you are ready to go, or you used NOOBS (as described earlier) to install your chosen OS.


<big>We shall install the Cumulus software listed on [[Software]] page</big>:
If you do need to install any operating system you choose, normally the instructions will be found from where you download the system you have selected. If you have brought a card without NOOBS, you can download/install the Raspberry Operating System Buster yourself, following either instructions on the [https://www.raspberrypi.org/downloads/ Raspberry Pi download page], those at [https://thepihut.com/blogs/raspberry-pi-tutorials/the-raspberry-pi-tutorial-beginners-guide this supplier's tutorial guide], or [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 those in Cumulus support forum]. To save you looking any of those up, the next sub-section summarises what you need to do.
# '''CumulusMX''':
#* '''CumulusMX.exe''' is written in C#, that has been developed by Mark Crossley, but still contains some code by Steve Loft
#* Download '''CumulusMX zip file’’’ from the link at [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is also written in C#, created, and developed, by Mark Crossley
#* Download '''Create Missing zip file''' from the link at [[Software#Create_Missing]]
#** This takes you to a github page with a "ReadMe" providing minimal instructions
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki
#* (it will populate missing fields in [[standard log files]] and/or missing lines in [[dayfile.txt]]).
# '''ExportToMySQL'''
#* '''ExportToMySQL.exe''' is also written in C# by Mark Crossley
#* Download '''Export To My SQL zip file''' from the link at [[Software#ExportToMySQL]]
#** This takes you to a github page with a "ReadMe" providing minimal instructions
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included within early CumulusMX zip downloads.


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


===Alternative download link for older package releases===
*Decide whether you want
**the full version of the operating system that supports a graphical user interface (choose this if you want to connect a TV or other monitor to your Raspberry Pi),
**or the ''lite'' version of the operating system that only supports SSH or terminal mode (choose this if you will operate headless - explained at end of this article)
*Download the latest version of the Raspberry Pi operating system you have selected from https://www.raspberrypi.org/downloads.
*That imager is run on any device, say your pc, and then you select '''write''' to save it onto the micro-SD card (don't forget this overwrites anything already on the card).
*This should work without a need to format the card first, (but if you do need to format it, do so using a SD card formatter downloaded from https://www.sdcard.org/downloads/formatter_4/index.html, '''not''' for example Windows format tool).
*After this image has been stored it will have created two (or three) partitions on the micro-SD card (one the boot partition is a FAT partition that can be accessed by Windows, the larger Linux partition is invisible to Windows, the optional third partition uses up any space left on a larger micro-SD card and appears as "data" under "media" in the Linux file structure).


Because the developer uses Git Hub to manage releases, the older releases remain available.
=== Is the operating system obsolete or up to date?===


====Old Cumulus MX packages====
It is important that your Raspberry Pi (or other device) has the latest operating system version installed. If the Operating System installed is an obsolete one, then each package it includes (e.g. Libre Office), and each package you add (e.g. Mono or PHP), will also be obsolete versions. In the worst case scenario, any attempt to install a package might fail giving an error message that the relevant Raspberry Pi repository is archived.
Skip this subsection if either you have installed the "pre-built disc image", or the current MX release is stable (it has been available for a while and nobody has reported any bugs).


Check if posts in the [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.
If you have a micro-SD card pre-installed with NOOBS, as described above, the first boot will install the operating system. It is the version of NOOBS that is included on the card that determines which Raspberry Pi Operating System version is set up:
*Wheezy (7) released in 2013
*Jessie (8) dating from 2015
*Stretch (9) released in 2017 (up to this called Raspbian Operating System)
*Buster (10) available from 2019 (the first to be called Raspberry Pi Operating System)
*Bullseye (11) under test in 2020


Remember, it is impossible for the developer to check all the ways in which versatile MX can be used:
Be aware that many such pre-loaded and pre-formatted cards include an obsolete version of NOOBS.
* Different weather station types (the developer only has a Davis),
*You may find your card installs the obsolete Raspbian Jessie (version 8 of Debian from 2015),
* Different computer types (development is mostly on Microsoft Windows),
*a few install the old Raspbian Stretch (Version 9 of Debian, dating from 2017),
* 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).
*a good supplier sells a card that installs latest Raspberry Operating System Buster (Version 10 of Debian, released in 2019).


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


====Old utilities====


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


This means that each version of "CreateMissing.exe" and "ExportToMySQL.exe" utilities is dependent on it being used with a release of Cumulus MX that does have correct '''''.dll''''' components in its release distribution.
How this is set up depends on your Pi model, and the operating system that is loaded on it,
*it may on first boot ask you to enter your wireless network details,
*it may list the wireless networks it finds and ask you to choose from the listed SSID,
*it might not prompt you so you need to use the configuration tool (see next sub-section),
*or you might need to click on an icon with two red crosses.


That in turn means you can't use the latest version of the utility with older MX releases, nor can you use an old utility version with latest MX release. This is why [[Software#By_Mark_Crossley|utilities downloads]] make clear which MX release is the minimum for them.
Note that there is also a Wi-Fi network country which must be set.


The older versions of these "CreateMissing.exe" and "ExportToMySQL.exe" utilities are available by going directly to the [https://github.com/cumulusmx Cumulus MX github] page, and navigating to the utility of interest. However, to use those older versions, you also need to download the corresponding older MX release, because the MX distributions contain the .dll files that the utilities require, they are not in the utilities zip. Because of this complication, novice users are advised not to attempt to use the older utilities, even if the latest version appears to have a bug. Technical users may be able to work out which .dll files are needed and can be safely added back (if they are not left over from when that past MX release was in use). An alternative is to create a new folder with the old release packages (MX and the utility of interest), a copy of the latest Cumulus.ini file, and a copy of all files from /data sub-folder; then afterwards copy back the changed files into original /data folder.
If you have had to enter wireless details into a mobile phone, you will realise what is needed:
*The ''Service Set IDentifier'' (SSID) is the name that is used for your wireless network.
**As mentioned above, you may see a list of those that have been found.
**You may have typed this into your mobile phone.
**It may be shown on a card that slips into a slot on your hub or router (you may have changed it from that initial setting).
**It can be up to 32 characters (letters, numbers, and symbols.
**Some routers come with a default SSID that is the manufacturer's name, if left unchanged it might conflict with a neighbour, so it is left to you to pick a SSID that is unique to you using up to 32 characters to personalise it.
*You also need to enter whatever Pre-Shared-Key (password) is used for your wireless network.
**You will have typed this into your mobile phone, so that can automatically connect to your network.
**You should have changed it (for security reasons) from whatever was shown as the initial password on the card that slips into a slot on your hub or router (possibly all you have done is add a prefix or suffix that means something to you).
*Most wireless networks will use Wi-Fi Protected Access (WPA) or (from 2006) Wi-Fi Protected Access II (WPA2) protocols, so '''WPA-PSK''' is correct for you.
**Note that your Pi is only able to use these protocols.
**The earlier Wired Equivalent Privacy (WEP) was officially withdrawn in 2004 as too easy to crack, so it is not supported on a new Pi.


==Upgrading a Cumulus package==


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


No further action needed for upgrade of "Create Missing" or "Export To My SQL" or "Create Records". See below for upgrade of main Cumulus MX package.
There are various other configurations you need to do on your PI.
You need to use the raspbian configuration tool '''raspi-config''',
*this can be accessed on your Pi either in a Graphical User Interface (GUI),
*or by running a command <tt>sudo raspi-config</tt> in Terminal.


If you are running an older MX release, before skipping in-between versions please check [[Updating_MX_to_new_version|here]].
==== Mandatory configurations ====


If you run MX as a service, then:
Within the Raspberian configuration utility, you will see an option to change password. You will want to do this so nobody can hack into your Raspberry Pi computer. You will need to enter the new password twice before it replaces the old one.
# Ensure you are not doing any changes to settings
# Leave MX running as you copy files from the new release distribution over the existing files
# Try to pick a time just after MX has done any standard interval store of readings or upload, so that it is least busy
# Use <code>sudo systemctl restart cumulusmx</code> to stop and then restart MX picking up the new files
# Result, downtime of MX kept to a minimum, so avoiding losing data


If you run MX interactively, do the unzip into a temporary location before you stop MX, then copy all files from temporary location over your existing files, and finally restart MX. Depending on your weather station type, it might or might not offer historic data catch-up, so you might lose some data while MX is stopped, and therefore should keep the downtime to a minimum.
The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name.
*The name can most easily be changed within the Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name.
*but it can also be edited by opening the file where it is stored using <tt>sudo nano /etc/hostname</tt>.


The alternative is to install in a new folder (or rename the old one), and copy across files not in the release from old location to new location, but in that alternative you might forget some files.
Network options can also be configured by clicking an icon on the Pi (this icon might be two red crosses if network settings are missing, two parallel arrows if the network settings are not correctly set, or the wireless symbol if your wireless network is working).


==Changing location of Cumulus MX==
==== Recommended configurations ====


If your install, or upgrade, is creating MX in a different place to where you previously ran Cumulus, then you will want to copy files across that are not in the zip extract distribution.
The default '''locale''' for a Pi is normally '''en_GB.UTF-8''', as they are designed by a company based in UK. Within the configuration option, you can add additional locales (in most cases there is a UTF-8 option which is preferred and at least one other encoding), there are also a number of special alternative locales, but I am not going to explain all the options, look it up if the default locale is not acceptable.
*Whatever locale you use, if you have already been using Cumulus (1 or MX), you need to ensure the locale matches the one used for your log files. The versions of MX released from the middle of 2020 onwards are very fussy that all dates use the same delimiter (see [[Cumulus_MX_formal_release_versions]]), so you need to check the chosen locale continues to use the same date separator as before. The locale is affected by the version of Mono you install and whether you use the locale parameter when starting MX, so I cannot cover all options.
*Anyway, the default locale is fine if you are in the UK, you use decimal points for real numbers, you use commas for list separators, and you don't have dates with month first!
*To change the locale, enter '''Localisation Options'''.


===Configuration Files to copy across from any previous Cumulus installation===
In the same option area, there are '''some more options''':
# Change Time-zone, by default UTC is used all year round. In the UK if your Cumulus MX is set to roll over at 10am in summer, you will wish to change the time-zone to UK time, because MX uses system time for many of its actions.
# Change Keyboard Layout if needed, keyboards can support different numbers of characters, and can have different currency symbols, so select whatever is relevant to you


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


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


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


Please see the table below for more advice, but the problem is that content of both files has changed as MX has been developed, so some content is no longer understood, and some new content has been added.
Sponsored by Microsoft, Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.


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


Quite often when we try to install, or update, packages on our Pi we will see messages about dependencies, and in some cases error messages saying the installation has failed or been aborted. Before we can install Mono, there are other packages required and these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian Mono download instructions for Raspberry Pi]. Here are the latest 2 options when this article was updated (if your Mono installation fails, then you selected wrong one):


If you are upgrading from an older release, please read the table for advice.
For Raspberry Operating System 9 (stretch):
<pre>sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update
</pre>


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


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


To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]
'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.


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


If you previously used an older release of Cumulus, but in this new installation will be using the latest release (latest is what is normally best, unless it has bugs), you may want to read up on all the changes between your old release and the current release, not just changes that affect the configuration file.
With all the pre-requisites correct as in previous steps, you can install mono package by simply typing <tt>sudo apt-get install -y mono-complete</tt>.


If you have used Cumulus 1 before, and decide to start with a new "Cumulus.ini" file, then you will need to work through all settings, to ensure they are set as you want. Please remember that when you use MX for first time, it uses that date it was first run as a starting date, and ignores any data found with earlier dates. Therefore you must change that start date:
It is important to note that MX requires the ''complete'' edition of mono as there is also a cut-down developer edition of Mono that can be downloaded/installed.
'''MX interface''' --> Setting menu --> '''Station Settings''' --> Click on ''General Settings'' --> Click on '''Advanced Options''' --> Edit ''Records Began Date'' following instructions below that field


==="data" directory===
The "sudo" part of this gives us rights, "apt-get" is one of the ways to search the Raspberry repository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.


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


You may also wish to read:
As the Pi does not know exactly which components are needed when multiple packages are installed with various dependencies, sometimes extra components are installed which in the end are not needed when you complete all your installations.
** [[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


Complications occur if the locale used by '''Mono''' or the locale specified when starting MX using [[#-lang parameter for changing Locale|-lang parameter]] differs from the locale for your previous device (please see [[:Category:Files with Comma Separated Values]] because some locales separate fields with commas, some separate integer and decimal parts of real numbers with commas; not to mention all sorts of issues with how dates are formatted). The main MX developer proposed that the format of files with comma separated values will be fixed from a release planned for September 2020, so all dates will use one standard format, all numbers will use decimal points, and the field separating character will be fixed.
To clear up, delete any components that are not included in dependencies by typing <tt>sudo apt autoremove</tt>.


Update May 2022, this has been put on hold, no public MX release has this restriction yet.
== Downloading and Unzipping MX Distribution ==


For simplicity, MX is installed into standard Pi user's home directory here. You might instead choose to install it on an external drive which has two significant advantages:
#there are certain files within MX that are updated very frequently, such constant rewriting can lead to a shorter life for your micro-SD card, by using an external drive for MX, MX files are less likely to be lost, and you are less likely to lose your operating system off your micro-SD card
#if you accidentally were to corrupt a critical file on your Raspberry Pi, you would need to rebuild the operating system image, and that deletes all existing files on the micro-SD card, including any related to MX, and you don't want to lose your precious data


==="Reports" directory===
Both the optional "data" directory created by NOOBS and any external drive appear within "/media/" in the file structure, but the exact path depends on your set-up and can't be predicted here.


By default MX now creates monthly and annual reports that are in the style used by NOAA in USA. If you have been using this functionality before (and it is optional) then you need to file transfer, or copy, all the files that were in the old [[Reports folder]] into the new folder of that name. Do look at that cross-reference, and read about the encoding default differences between Cumulus 1 and MX.
The procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution.
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#Download the MX distribution from the link that appears there, Mark will update it for each release he makes.


=MX can cause problems with storage=
If the latest release has bugs (it is impossible for the developer to check all the ways in which versatile MX can be used), you can Download whatever older version of MX you have decided to install from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].


MX now assumes by default that you are going to use its [[New Default Web Site Information|Default Web Site]]. That means that by default MX will re-generate temporary files in its [[Web folder|/web sub-folder]] on a frequent time-scale. That number of files writes will considerably shorten the working life-time of the "high capacity micro-SD" card that is the default storage for the Raspberry Pi. It will also considerably shorten the life of any flash memory (e.g. memory card) that you might install MX on.
#If you are downloading the distribution on your Pi, the easiest option is to download into '''~/downloads''' folder.
#* Whether this location is the default, or you are asked to select location will depend on whether your browser's default settings have been changed.
#When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
#Ensure the file unzips into your personal directory "/home/pi", although you could place it elsewhere, this is the easiest place to find (because it can also be represented by "~".


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


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


==web directory==
=== Configuration issues ===


All the files in this folder come from the download.
'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
** It is important to see that whilst most settings can be done in the former, a few are read-only and must be done in latter
**Also note that some settings are related (e.g. you need to enable real-time before any real-time actions can be selected; equally you need to enable moon image generation before you can tick the upload option; these are just the 2 most common errors)
*For general advice relating to [[Cumulus MX]], follow that link
*For [[What to do when I have a problem with MX]], follow that link
*An article that needs someone to spend a lot of time improving it is [[Cumulus MX FAQ]], but the article could be useful
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions


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


The links you need depend on which options you select in settings, you might find it easier to wait until you have run MX for a while to see what files are created that end in ".json".
'''If you have used Cumulus before''', but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
*Cumulus.ini
*strings.ini


If MX is currently running, you need to stop it, or at least alter any options that generate .json files. Then you must delete those files that end in ".json", except that you don't delete "websitedataT.json".
The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder). Be aware that the characters terminating each line may need editing (see next sub-section).


In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier):
Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].
*For '''Extra Web Files''', local file names will look like ''/home/pi/CumulusMX/web/trendsT.htm'' for the standard templates, or it might be something like '''/home/pi/cumulus_Templates/valuesRecentForDetailT.js''' if you have created your own templates.
**''Please note'' that Cumulus MX program code DOES NOT recognise "'''~/'''" as shorthand for '''/home/pi/'''.
**Your remote file names, if you have a local server as set up in the notes in the optional sections later, will look like ''/var/www/html/weather/trends.html'' or '''/var/www/html/weather/js/valuesRecentForTrends.js''', depending on your folder structure. If you pay for a commercial web server, remote file names will be as specified by them and not dependent on what device MX is on.
**Remember ''if web site is on your Pi'', MX needs full '''rw''' permissions to the HTML folder on your web site, so give permissions recursively using <tt>sudo chmod -R ugo+rw /var/www/html</tt> for Cumulus MX to successfully copy there.


<code>sudo ln -s /run/tmp/websitedata.json CHOSEN PATH/CumulusMX/web/websitedata.json</code>
=== Keeping existing data and Reports files ===


Notes:
'''If you have used Cumulus before''', you will be seeking to keep your existing log files. If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed Windows on your Raspberry Pi. Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, then ideally all your files should be edited so they simply use Line_feed to terminate all lines. This can be easily done in an editor like Notepad++ that is designed for computer files.
* The "-s" flag is what says you are creating a symbolic link
* Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file
* "CHOSEN PATH" is defined in [[#Where to install all packages?]], but basically it starts with a "/" and defines the path to get to where "CumulusMX" is a sub-folder.
* The text "websitedata.json" is just one file in the set of files linked from [[:Category:JSON Files]].


=Running MX=
The novice does not need to worry about changing end of line characters, it is advisable but not essential (as the Pi will treat the CR as a character it does not display)


There are multiple subsections here, you are unlikely to need to read them all. Look at each, and decide if it applies to you.
To get the entire content of your existing '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).


== Parameters ==
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!


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


If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).


== Running Cumulus MX ==


==Your first run of MX on Linux==
(When these notes were written, there were topics in the support forum about ways to use scripts for starting/stopping MX, but the distribution did not include any such controlling scripts. The latest MX version includes a script allowing MX to be run as a service, and perhaps someone would be kind enough to expand the first sub-section).


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


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


Information about settings is on other Wiki pages ([[MX Administrative Interface]] and [[Cumulus.ini]]).
=== Running with a terminal session left open ===


== Run interactive or as a service==
Whichever operating system you are using, to run MX requires an instruction that changes to the directory 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]].


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


It is advised that you run MX interactively to begin with, and only run it as a service when you are happy that all settings are correct, and that any uploading or other external tasks are working correctly.
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 so that terminal session continues running.


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


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


==Running MX interactively==
If you have a Raspberry Pi with a monitor attached, you will see a raspberry icon that you can click to get access to many features including shutdown options.


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


The simplest instruction to run Cumulus MX is <code>cd CHOSEN PATH/CumulusMX && sudo mono CumulusMX.exe [optional parameters]</code>.
Almost all instructions, given in this article, start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows a standard Pi user to do tasks that otherwise only work for the root user. You use it as a prefix to almost every command you type in terminal mode. There 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):
* This is two commands issued together, the first changes the working folder, the "&&" means that first command has to succeed before the second command is obeyed and actually starts the main executable
* This example has not included any optional parameters, as they are rarely needed, but the optional parameters available are as listed in table earlier.


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


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


You can start it off directly on your Pi, and then
To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.
*optionally disconnect the keyboard,
*switch off monitor or TV attached to your Pi,
*Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.


===Running MX interactively from a remote computer===
To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.


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


These won't be explained any further here, but be aware that control key sequences may not work, and you may need to type "exit" to close the session.
When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder. Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).


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


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


Open a terminal window, then navigate to the folder where you have installed the 3 Cumulus executables:
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.


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


To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, follow that link for more details.
There are various text editors available on a Pi, '''nano''' is a simple one.


Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file.


==Running MX as a Linux "systemd" service==
Use prefix of 'sudo' to give you access to any file, '''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.


There is a one-off task to define a service file, after that you can simply issue commands to stop/start/restart the service.
When in nano you select to write out to a file, it allows you to change the file name shown. If you choose to save as another file, you will be asked if the new name is correct (again type '''Y''' to continue saving).


For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement].
Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.


===The Service definition file===
The full syntax is <tt>sudo nano -B Path_file_name</tt> 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.


The MX download includes a file that can be used as a starting point for the service definition. Find this file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service''. You do have to edit this file, and then you have to copy it to a new location, before you start the MX service for the first time.
You will probably find it useful to type <tt>sudo nano /etc/nanorc</tt> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options


# Open the file at ''CHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor (see [[Preparing_your_Linux_computer_for_MX#editing_files|editing_files]]).
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 <tt>sudo nano /var/www/html/index.php</tt>. 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:
#* On a Raspberry Pi with a graphical interface, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
*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.
#* If you are accessing from another computer, using a terminal session, then "nano" is a suitable editor (explained at link just mentioned).
*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.
# Within the provided file you should find a [Service] section:
<pre>[Service]
User=root
Group=root
ExecStart=/usr/bin/mono-service -d:/home/install/CumulusMX CumulusMX.exe -service
Type=forking
ExecStopPost=/bin/rm -f /tmp/CumulusMX.exe.lock</pre>


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


:There is more in the file, but for now focus on the line including "ExecStart=/usr/bin/mono-service -d:". Don't change any of the bit I just quoted.
This is used for installing packages, you will often see it used with a parameter '''-y'''; as without that parameter you have to type '''Y''' to continue at each step of an install.


Almost certainly you will need to change "/home/install/CumulusMX" on that line. Replace that with "CHOSEN PATH/CumulusMX", i.e. the full path to the directory that the executables are being stored in.
It is important to mention here that the version of packages installed may well be obsolete, this install is finding versions from a Raspberian repository, more recent versions may be available from the providers of each package. To keep this article simple, I accept the Operating System that is installed by NOOBS, even if it is not the latest available from the Raspberian web site, I accept the versions of Mono, Apache, PHP, MariaDB, and others, that are found at the time you issue the install command. The update and upgrade command that I use in multiple places in this article is still only finding the versions available in the repository, and is included just in case the repository is being updated after any install finishes.


The final line, with all possible parameters, could read: <code>'ExecStart=/usr/bin/mono-service -d:CHOSEN PATH/CumulusMX CumulusMX.exe -service -debug -port 999 - lang el-GR</code>
If you have more skill than the level of the person at which this article is aimed at, then you should know how to install the latest version from the appropriate web sites.
* Note the space between the path (just looked at) and the executable file,
* Note the mandatory parameter "-service" that follows a space after the "CumulusMX.exe", you must leave that untouched,
* Note you can remove/keep the rest of the line after the -service i.e. the other parameters (some with their values) -lang, -port, or -debug, (as defined in table earlier), are all optional.


=== removing an unwanted file ===


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


=== Miscellaneous ===


====Technical users - additional edits====
I have created a section here, in case anyone wants to add any more instructions. Please feel free to rename it, or indeed add any clarification anywhere in this article.


Novice users, skip this subsection. ''The changes in this subsection have to be made with other changes that are not covered here'' (they depend on your weather station type, and your computer type, so are not appropriate to a Wiki page trying to generalise, and anyway your contributor is not a technical expert).
Meanwhile, look at either [https://raspberrytips.com/raspberry-pi-commands/ this web page] or [https://www.ubuntupit.com/useful-raspberry-pi-commands/ this one] for more commands.


:Look at the '''[Service]''' part of the file quoted above.
=Optional actions=


This states Cumulus should use root for both the user it runs under and for the group permissions it uses. ''If you have the technical expertise'', you might choose to run MX in a different user, if your weather station type allows MX to run in a different user. If so, replace the "root" in its two locations. (Please note some weather stations require other changes outside this file before Cumulus can make contact, one example is discussed [https://cumulus.hosiene.co.uk/viewtopic.php?t=20413 on support forum here], but there are other topics that may be relevant).
An alternative way to load Cumulus MX onto a Raspberry Pi is by using docker (a package installation), it may not be kept up to date but there is such a package at [https://github.com/magimat/rpi-cumulusmx rpi-cumulusmx] and a very old one at [https://github.com/Apollorion/CumulusMX-Docker CumulusMX-Docker].


You may also wish to add an extra line after the "Group" line <code>ExecStartPre=/bin/sleep 5</code>, this [https://cumulus.hosiene.co.uk/viewtopic.php?p=163754#p163754 is to delay the starting of MX by 5 seconds while other services start] (on a reboot of your computer) that might affect MX. (For some users, change 5 into 10, it all depends what else is being started).


:Look at the rest of the file, the '''[Unit]''' part.
Any novice can stop reading now, as preceding sections have covered all you need to do to use a Raspberry Pi (or other Unix-based device) to run MX.


For releases 3.8.4 to 3.15.0: you will see one reference to '''network-online.target''' in <code>After=network-online.target</code>.
However, some people want to do more, so various options are covered in the remainder of this article. If you are a novice, my advice is don't experiment with what is mentioned after this until you are happy that all you have done up to now works. The rest of this article does get more technical, so it might be harder to understand and harder to implement. With that warning in mind, I must add that the remaining sections cover a number of items and it is very likely that some of them could be useful to you.


For release 3.15.1 build 3170 (19 March 2022) onwards: you will see an extra line <code>Wants=network-online.target</code>
There are lots of sub-sections, so you can skip over those that do not interest you, while carefully reading the ones that could benefit you.


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


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


For that ''time-sync.target'' to work, you need to '''enable''', by creating the symbolic links needed, the appropriate services outside this edit:
*We run <tt>sudo apt update && sudo apt upgrade -y</tt> to ensure all packages are up to date before we attempt to add another package.
<pre>sudo systemctl enable --now systemd-timesyncd.service
*I remind you here that this does not update everything on your computer to the latest versions available for a Pi, that requires a different (more risky) command not taught here.
sudo systemctl enable --now systemd-time-wait-sync.service
*Instead, the instruction quoted above just updates your Pi to a consistent state; based on what is in the repository you are already using.

This action is not repeated below, but potentially applies to all options below.

==Databases built into Cumulus MX==

You do not need to know what is in those databases to use MX.

Cumulus MX includes two SQLite databases;
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#*If you do find out what the first database is used for, please update the Wiki article on it!
#The second database is the [[Weather Diary]] added by Mark Crossley, that is documented, and in the support forum there is a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.
#* The [[MX Administrative Interface|Admin Interface]] provides a page to view or edit the weather diary.

Optionally, you could install phpLiteAdmin (the significant part of that name is in the middle) to read those SQLite databases. Install it using <tt>sudo apt install phpliteadmin</tt>.



== Adding a web server and a database server ==

This is an option, and may not be useful to you, but is described here in case it is something that you want to do.

This option is not needed if your MX simply updates to an external web service (several are listed in the options in the admin interface), so you do not use the web templates supplied with MX (nor any alternative web pages created by you or a third party).

This option is not needed if you have subscribed to a commercial web server (and optionally database server).

Now you have a Raspberry Pi (or another device than can be left running all the time without consuming a lot of electricity), you ''might'' want to add a web server and database server so you can make use of the web templates that Cumulus MX provides, and its ability to update database tables.

You might want this option if you are creating your own web pages, and want to try them out without exposure to the public over the internet.

You might select this option to save the subscription costs of a commercial web server (and optionally database server).

=== Install Apache 2 (or another web server) ===

I will mention 3 possible web servers:
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <tt>sudo apt-get install nginx -y</tt>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <tt>sudo apt-get install lighttpd -y</tt>.

=== Install PHP Hypertext Pre-processor ===

*PHP is not the only script language available, but it is quite comprehensive
**being able to be used either in a fairly simple way by non-technical people
**or in an object-oriented way for those more technical to achieve success with more complex scripts.
*The simplest instruction to install it is <tt>sudo apt install php -y</tt>, which version you get depends on your Pi and its operating system.
*To check which PHP modules have been installed by the above command, type <tt>php -m</tt>.
*If you later want to use a database (and a tool like PhpMyAdmin), then your php modules loaded must include at least '''mysqli''' and '''mbstring'''.
*I will explain how to find the .ini files later, but unwanted modules can be commented out in your .ini file.

'''Alternatively''', you can install particular php modules, or a particular PHP version, by selecting components from a list. To do this type something like <tt>sudo apt install php7-fpm php7-cgi php7-cli php7-common php7.3-mbstring php7.3-mysql php7.3-curl php7.3-gd php7.3-zip -y</tt>. Only use this approach to force a particular version (but you may find that is not available), or if you are short of space, and you are only going to use a minority of the php features available in the full set of modules.


To test that php is installed, type <tt>php -v</tt> into terminal, and you will see the exact version that has been installed, a confirmation that it offers command line interface (cli), and a copyright notice.

===Creating a Home web page on your web server===

You may wish to create a index.php web page at /var/www/html which is the web server root for browsing, or of course you may wish to copy or FTP here all your existing web pages. To view a php web page, go into a browser and type in a url with the same IPv4 address as you use for the admin interface, omit the port (:8998) and instead type in your web page name (e.g. //192.168.1.'''xy'''/index.php, where you need to determine digits that replace '''xy''').

===Finding your PHP configuration file===

For sake of simplicity in this article, from now on I will assume the web server you installed is "apache2", change that segment (in the paths quoted below here), if you installed a different web server.

The ''web server'' main '''php.ini''' is found at ''/etc/php/7.n/apache2/php.ini'' (where 'n' depends on your Raspberry OS version and therefore which PHP version was installed, that was found out in last sub-section).

You may need to edit this file for example to specify where your include files are stored (if not in same folder as script with require/include). Replace "apache2" by "cli" in the path for the ''batch'' '''php.ini''' file that you may also need to edit.

To run a php script in batch, type <tt>php - f <file_name></tt>. You can redirect the output by adding a greater than symbol and the destination file (i.e. > log_file) on the same terminal line.

If you want the MX external commands to run a PHP script for you, use something like "sh" as the program to run (i.e. run shell script); and in the parameters something like
'''/home/pi/CumulusMX/MXutils/autoEOD.sh''' will run a script "autoEOD.sh" you have added to the "MXutils" folder. In that script, you put something like (assuming you have added a folder 'batch' with a subfolder 'log'):
<pre>#!/bin/sh
# This MX batch command file is initiated automatically by Cumulus MX software during last stage of processing the end of a meteorological day
echo "It stores feedback in log file CumulusMXDailyBatch (file name ends with day of month)"
sudo php -f the_path_and_filename_goes_here.php > /home/pi/CumulusMX/batch/log/DailyBatch_Day$(date +%d).log
</pre>
</pre>




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


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

MySQL database software is controlled by Oracle and not made available for inclusion in Raspberry Pi repository.

Maria is an alternative that has largely similar command syntax so is likely to work with code (like MX) designed to work with MySQL. Since the MX developer (Mark Crossley) actually uses Maria DB, we can have plenty of confidence it is suitable.

To install this database server, we type <tt>sudo apt install mariadb-server php-mysql -y</tt>.

Our database files will be stored at '''/var/lib/mysql''' by default. Our MariaDB configuration is stored at '''/etc/mysql/mariadb.conf.d/50-server.cnf''', and it is the ''datadir='' entry that controls where the database files are stored.

=== Making your database secure ===

We need to assign passwords to control access to the database by typing into terminal <tt>sudo mysql_secure_installation</tt>. That brings up a screen:
# where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
# next type '''Y''' to signify we are going to set a new password for '''root''',
# next type in a new password that you will not forget,
# next as explained on the screen we are going to say whether users must select a user name as well as a password, type '''Y''' to ''Remove anonymous users''
# next we have to decide whether we will only be logging into the database on our Pi (using Localhost) or we might be logging in remotely; type Y or N respectively, but if you choose N remember someone other than you might guess there is a root user and might guess the password you set,
# next we have another option of whether to retain or delete a test database, answer N or Y respectively, I would keep the test database for now as you can play with it and then remove it later,
# finally you type in another Y as that will '''Reload the privilege tables''' and ensure all is set up for your access to the database later.

The message, when the process successfully completes, is "Thanks for using MariDB".

=== Installing Adminer, or PhpMyAdmin ===

ExportMySQL.exe and CumulusMX.exe (see [[Cumulus_MX#Executables]] for details) both create SQL for updating tables in a MySQL database, such as the one our MariaDB software package we have installed can create.

However, there is nothing in the MX distribution that lets us back up and manipulate (e.g. delete rows with errors, or correct rogue numbers in a column) tables in this database. This option is about installing a package to do the tasks that go with operating a database.

'''PhpMyAdmin''' is one tool that can be used to manipulate your MySQL like database (that is the significance of the "My" bit in the middle of the tools's name).

You may like '''PhpMyAdmin''' as this offers:
* a graphical approach (you see a table on screen and navigate to the row or cell you want to work on)
* a SQL approach (you can try out any SQL here, before adding it to a script that you might use in a web page)
* a selection approach (you select a database, then select a table, then select an action)

#Start the install with <tt>sudo apt install phpmyadmin -y</tt>.
#The PhpMyAdmin installer will ask some questions.
#Use your tab key to select <Yes> when it asks whether you want to configure with '''dbconfig-common'''.



You may prefer to install a different tool, perhaps '''adminer''' that works using a drill down approach. A drill down approach is when you select the database, then select the table, then select the row, then select the column, then select the action. This logical step by step approach is a popular approach, but does not suit everyone.

Install this drill down package with <tt>sudo apt install adminer</tt> (I leave you to work out the commands needed after that).

===Getting web and database servers ready for use===

We need to create a user for PhpMyAdmin (or adMiner or whatever) to access our database and another for Cumulus to use to access the database tables. At the moment our database access has the single root@localhost user we created when we installed MariaDB. The initial password was set then, and we need to use it to get access to MariDB monitor where we can insert some SQL commands to create these two users.

PhpMyAdmin on first start up will ask for username (here I choose "admin") and password, thereafter it will use same log-in (by default you see log-in screen each time you restart or if it is left idle for a long time), let us create a user called 'admin' for it.

The database name (here I choose "cumulus" for the data base name), user name (here I choose "weather" for the user name), and password, must all match those set in MX using the [[MX_Administrative_Interface#MySQL_settings|MySQL_settings]] in the admin interface. You could of course use PhpMyAdmin (or AdMiner) to create additional user names, and to create the database, but I assume all is done in the following bit of SQL. Remember, the Windows operating system is not case sensitive, but all Linux based operating systems are case sensitive (so whatever pattern of capitals and lowercase you choose must be used every time. Also all names must start with a letter, can contain only letters or digits (no punctuation), and must not be a reserved word ("password" is a reserved word, so you cannot use that for a password, nor for a column name).

Obviously, these names might not be what you use, but you can amend commands below accordingly. For each line with SQL, it must end with a semicolon (;) as shown. After you press "Enter" key you will get a response saying "OK" if you have remembered the semi-colon. You can actually use "\G" or "\g" instead of a semi-colon, but here we will keep it simple and stick to semi-colon.

The SQL lines have a prompt of a greater than symbol (>) while the command lines have a prompt showing current path. Note that "identified by" is followed by a password enclosed in single quotes.

<pre>sudo mysql --user=root --password=InitialPassword
create user admin@localhost identified by 'PhpMyAdminPassword';
create user weather@localhost identified by 'MXPassword';
grant all privileges on *.* to admin@localhost;
grant all privileges on *.* to weather@localhost;
FLUSH PRIVILEGES;
create database cumulus;
exit;</pre>

As I type this, Cumulus MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore in this situation it will crash out (with message press Enter to close).

=== Commands to ensure PhpMyAdmin will work ===

The following sequence of commands will
* add the mysqli module to our php install,
*will restart apache,
*will create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser,
*will give the standard user (pi) ownership of the database files and the web pages:

<pre>sudo phpenmod mysqli
sudo service apache2 restart
sudo ln -s /usr/share/phpmyadmin /var/www/html/phpmyadmin
sudo chown -R pi:www-data /var/www/html/</pre>

===Viewing web pages on our new web server===

You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi IPv4 address e.g. a URL like '''http://192.168.1.xyz/phpmyadmin''' where ''xyz'' is 2 or 3 digits you look up as mentioned before where FTP was described. If your Pi has both Ethernet and wireless connection, there will be two different values of ''xyz'' for you to choose one from. On first run of PhpMyAdmin, as already mentioned, you will see a '''PHP MyAdmin log-on page''' where you type username and password we have just set up.

===Populating your database tables on your Pi===

Cumulus MX has functionality to update database tables at one of 3 intervals:
#real-time
#standard interval
#end of day

The database tables can use the column names in the schemas pre-defined by Cumulus MX or in a custom schema (where you specify the column names). The settings are all in [[MX_Administrative_Interface#MySQL_settings]], so read that section to find out more.

You might have started using MX before you set up your database. There is a option in that part of the admin interface to create database tables (as required) for each of the 3 updating intervals. For example, the default name for the table updated at the standard interval is "monthly", but you could give it a name of "standard" or whatever you like.

The MX release distribution includes another executable. Type <tt>cd CumulusMX && sudo mono ExportMySQL.exe monthly</tt> to run the executable. The first parameter is "monthly" even if the table has a different name.
#if the table name is defined in the admin interface, and the table already exists in the database with the correct columns defined, then the executable will use that table.
#There is an optional second parameter that specifies the log file name to read.
#*if the second parameter is not specified, this executable will look at every log file (in "data" folder and with file name that starts with month, then has "log.txt"),
# for each line in the log file the executable will try to insert a row in the database table
#*the SQL syntax used is "insert ignore", so if the row for that log file line already exists in the table, it will skip onto next line of log file.

Similar instructions apply for the end of day table, although as there is only one daily summary log file, there is no optional second parameter, just type <tt>cd CumulusMX && sudo mono ExportMySQL.exe dayfile</tt>.

There is no way to use this executable for insert of past rows into the real-time table.

If you have been running Cumulus on another device previously and already have database tables, the next section explains how you can create SQL to export your old database and use that SQL to populate the new table.

===Transferring database tables to your Pi===

If you have been using Cumulus before (and already have a database) then you can use PhpMyAdmin on your old device to '''export''' out all the '''Cumulus tables as SQL''' in a zip file, FTP that zip file across to your Pi, then use PhpMyAdmin on your Pi to '''import''' that zip file.

Providing you selected the right options for what SQL you created in your export, the import will contain SQL to create the tables and to insert all the rows into each Cumulus table on your Pi. Please note that there is a limit of around 1000 rows that can be imported in one action, so for your bigger tables, you will only create the table once, but you will do several '''Replace''' row actions (export from old device, then import to Pi) each transferring just one thousand rows, until the whole table is on the Pi. You may prefer to use "ExportMySQL.exe" as described in previous section to recreate your bigger tables from the Cumulus log files.

You might want to also '''export/import the tables in the PhpMyAdmin database''' (as they contain your preferences for each of your tables) in a separate zip, although these might need some extra transformations, as they are specific to a particular version of the database server (and the old database server version may not match the MariaDB version on your Pi). Some PhpMyAdmin tables do change for different versions of the tool, so that too may make export/import of its tables more complicated.

=== Restarting Web Server ===

After all these installs, we need to restart Apache (so it loads the PHP and MariaDB), by typing <tt>sudo service apache2 restart</tt> or (if we just want the Apache configuration reloaded) by typing <tt>sudo systemctl reload apache2</tt>. Similar commands apply for other web servers.

We will need to restart Apache (or whichever web server we installed) any time we change our php.ini files, database passwords, and anything else that is checked when the web server starts.

== Operating your Raspberry Pi in headless mode ==

The terminology "headless" means using another device to send commands to a Pi via a wired or wireless network, instead of connecting a keyboard and monitor (or TV) directly to the Pi so you make all selections directly on it.

For a novice, the easiest way to set up your Pi (as described above) requires (at least temporary) a keyboard and a monitor (can be a TV) to be connected to it. You might also want to connect a mouse. Depending on the Raspberry Pi you bought, and whether you bought a keyboard (or can borrow one from any PC you have), the ease of making these connections will vary. Once your Pi is set up, and you have started MX running, you can disconnect these peripherals, and leave your Pi running.

The options described in the rest of this article cover all aspects of using a PC to do actions on your Pi, including how to change some settings on your Pi without ever connecting a keyboard and monitor to the Pi. For a novice, there are lots of opportunities to make errors in the following options, so remember the cricketer who said "If at first you do not succeed, try and try again, if you continue to fail, give up".

=== Remote access ===

There are various different ways that another device can access the Pi over networks. The most popular lets a Terminal mode on your other device connect to your Raspberry Pi using Secure Shell Home, and the commands you type in on your other device are just the same ones you would type directly into the Raspberry Pi terminal mode. The responses you get are also the same. What is likely to be different is
*any control sequences,
*any copy and paste operations,
*and any other actions that are specific to the terminal mode on the other device.


You can use the browser on your PC to connect to the web server created by the MX engine to run the admin interface (all that needs is that the Pi and the PC are both connected to your hub or router, so they are on the same local network):
* to change settings
*or to look at the web pages provided in that interface.

Your PC can be used (as well as your Pi) to look at any web pages updated by MX (all that needs is your device to be able to connect to whatever web server runs your web pages).

====Ways of using PC to do what can be done on a Pi====

On your Pi, there are various applications that you can run with graphical interfaces, these let you achieve what you want by on screen selections, without having to learn what Linux commands to type in. You might wish to use these when you are operating your Pi in a headless state (without keyboard or monitor), so you want to see these graphical interfaces on your PC. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.


An alternative way to work on your Pi is its its terminal mode. This lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, and can therefore allow you to achieve tasks where a graphical interface fails because of the ownership of the part of the file structure where your action is taking place. The commands you type into a terminal screen on a Pi can also be typed into a terminal screen on your PC, and you will see the same responses. For this to work, you need to switch Secure Shell Home (SSH) on as that is what controls access over a network. This article explains most aspects of SSH in the next few sub-sections.


==== What is Secure Shell Home?====

Secure Shell Home (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network. If you have two devices (your Pi and another computer), SSH will allow the two devices to exchange commands and responses between a terminal and a computer over the wireless or Ethernet (or mixture) network that connects them.

You may be too young to remember when communication with a computer was often done (remotely) using a Teletype (or similar device) acting in terminal mode. Just 4 decades ago this would have been a familiar experience for anyone working with computers, now it may seem strange for you.

It is possible you have remote connection from home to a computer at your work (although that probably uses a different protocol as the network is likely to be better secured as it passes over the internet).

SSH is switched off by default on a standard Raspberry Pi set up.

You can if you have a keyboard and screen attached to your Pi, go into the configuration screen it offers and switch SSH on. The easiest way is using the '''Raspi-config''' tool, either from the main menu (raspberry Pi icon inside a square) or in terminal mode with '''sudo raspi-config''' (choose option 5 = ''Interfacing Options'', look for SSH). This will enable you to later access your Pi from your PC and might be useful later on. While you are in the configuration tool choose option 1 = ''Change User Password'', and set the password you will use for your SSH session; the default password is '''raspberry''', but you don't want to let hackers into your Pi, so you will choose something hard to guess.

The next sub-section describes how you can switch SSH on during the first boot, by creating a file on the micro-SD card before you insert it into your Pi, the file is removed as part of the boot process, so this only works once.

====Pre-configuring the Pi for headless operation====

If you want to set up your Pi headless (without monitor, keyboard, mouse), then you must ensure SSH (which is off by default) is switched on as your Pi boots up. Otherwise you have no access to do any setting up, and you cannot even close down the Pi tidily! The only way to achieve this, is by adding a file '''SSH''' to the boot partition before the micro-SD card is put into the Pi. If you don't do this you cannot get headless operation, and you will need to move a monitor or TV, mouse, and keyboard, across to the Pi.

The file, you add to the boot partition (there is a second partition that may be invisible), must be named "SSH" with those three letters in capitals, but with no file extension. You can create the file with whatever text editor you have available.
*On a Windows PC, if you right click (while viewing the boot directory on the card) there is an option called '''New''' and if you select ''a text file'' it will create an empty file with the extension '''.txt'''. (In windows there is an option to hide extensions which is on by default, so you may need to deselect this option ['''New''' menu -> ''Options''] to see this extension). On Windows you can open the file using Notepad to verify it is empty, if you gave accidentally created a file of another type like word processing it will be full of characters some of which do not display. Anyway, you must remove any extension from the file name so it is really just '''SSH'''.

Type into the file <tt>touch ssh</tt>, but nothing else, no empty lines, no end of line characters.

When the card is inserted into your Pi, on boot this file will be removed and the SSH option will be enabled. The default password is '''raspberry''', once you have successfully got SSH working. You should then use '''sudo raspi-config''' (choose option 1 = ''Change User Password'', and set the new password you will use for your SSH session next time).


====How to use SSH?====

If you have a Windows PC, this will allow you to open a '''Command''' prompt, '''Power Shell''', or '''Terminal''' window (the selection you have available depends on certain settings).

If you have a Linux or Mac device, open '''Terminal'''.

Next, (assuming your Pi is running, and that your other device is on the same local network), type <tt>ssh pi@raspberrypi</tt> to get access to default user in your Pi.

(As an alternative for Windows operating system, you can install PuTTY, this has the advantage that you can enter the connection settings into it, and configure various other options, and these are remembered, so might make it easier to use. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).

When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. The action that result from any key combinations depend on your terminal application, not just whatever you are running on your Pi. Your mouse can't affect cursor location, but the mouse might be needed to select text, the left click might copy what is selected, and the right click might paste (what is in your PC's clipboard) at current cursor position.

You can use SSH access from your PC:
* when you need to edit a file on your Pi,
*or do a file transfer between Pi and PC or vice versa.

=== Running MX from your PC ===

If you choose to use the simple <tt>sudo mono CumulusMX.exe</tt> command in a terminal (or command window or Powershell) session on your PC, remember MX will detect if that session is ended and will shut down MX. This means if you want to keep MX running you need to keep your session on your PC running and you loose the advantage of saving electricity by running MX on a PI because your PC remains on.

As I type this a new release 3.8.0 is to allow MX to run as a service, and a future release is planned to change the associated script, so anything I write here might become obsolete, and the next sub-section gives you some links to the support forum about alternatives to the new feature. Hopefully, someone will edit this article, when instructions have settled down and won't change on next release. Basically, the ability to run MX as a service, means that MX actually runs independent of the session that starts or stops the service; and therefore implies you can shut down your PC without stopping MX.

Hopefully someone will add notes to this article about the running as service option. I have not tried it, so I cannot add such notes.

=== Older information about using a PC and a PI ===

In the Cumulus Support forum, there are articles about a [https://cumulus.hosiene.co.uk/viewtopic.php?p=139779#p139779 stop/start routine], a [https://cumulus.hosiene.co.uk/viewtopic.php?p=141514#p141514 backup routine], and [https://cumulus.hosiene.co.uk/viewtopic.php?p=146028#p146028 how to run MX as a service]. I will let you hunt for and read the relevant topics, as you may find details in more than one place. This article currently avoids describing these to try to keep content simple. Here is just a list of some alternatives to having to leave your terminal session running:
# Use '''start/stop routine''' (see earlier link), this effectively starts a separate session for MX to run in and leaves the standard terminal session free.
# Run MX as an '''init service''' (see the earlier post in the service link above), be aware that this is a new feature in the new release of MX 3.8.0, again this starts MX outside your terminal session
# Use '''Screen''' software to start up a separate session that you can log off from without MX stopping (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146203#p146203 how to run using screen]}
# Run MX as a '''systemd service''' (see the more recent posts in the service link above), be aware that at time of typing this is planned to be incorporated in a future release but the MX developer has no knowledge in this area


===Headless Wireless Network set up===

If you don't connect a keyboard and monitor to your Raspberry Pi, you can't set up the wireless network configuration on your Pi using one of the provided configuration tools as described in the earlier wireless network sub-section.

You can use the SSH approach described immediately above to access the '''Raspi-config''' tool and in that do the necessary configuration.

There is one further, complicated, way to set up the wireless configuration so that the wireless network will work when you first boot up your Raspberry Pi. If you have brought the Zero model, that does not allow Ethernet connection, you might decide to follow this complex approach that involves creating a text file in the boot partition of your micro-SD card, and store it in the boot directory on your micro-SD card with a file name '''wpa_supplicant.conf''' before you insert that card in your Pi and do its first boot.


====Technical Notes only relevant to Raspberry Pi====
A note of caution here, it is easy to make mistakes, and you may find this does not work. It is presented here just to cover all options, to use this does require some technical skill, a novice will be better off avoiding this.


This Wiki page has tried to avoid being too specific to particular hardware, but to avoid misunderstanding the last subsection, a little does need to be said to justify the claim that only technical users, who understand all the other changes needed, should make changes mentioned there.
Ensuring you are using a text editor that won't add any unwanted control characters, add the following text using UTF-8 encoding:
<pre>ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB


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


The issue is your Cumulus MX on restarting will skip the catch-up of historic data (should your weather station settings make that available), because the dummy clock makes MX think the computer was not off for long. Subsequent measurements will then get logged against the wrong time until the correct time is found on the internet (NTP). At that moment, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day. In my experience it can be anything from 2 minutes to 10 minutes after switch on before my RPi does a time sync over the internet.
*Obviously, if you are not in United Kingdom, you will replace '''GB''' by the country code that applies to you.
*Within the first set of quotes, replace '''YourNetwork''' by whatever ''Service Set IDentifier'' (SSID) is used for your wireless network.
**You may have typed this into your mobile phone.
**It may be shown on a card that slips into a slot on your hub or router, but you may have changed it from that initial setting.
**Whatever it is, and it can be up to 32 characters (letters, numbers, and symbols), type it within the double quotes.
**Some routers come with a default SSID that is the manufacturer's name, if left unchanged it might conflict with a neighbour, so it is left to you to pick a SSID that is unique to you using up to 32 characters to personalise it.
*Within the next set of quotes, which relate to the key (or password) that protects access to your network, replace '''YourNetworkPassword''' by whatever Pre-Shared-Key (password) is used for your wireless network.
**You will have typed this into your mobile phone, so that can automatically connect to your network.
**In this case, you should have changed it (for security reasons) from whatever was shown as the initial password on the card that slips into a slot on your hub or router (possibly all you have done is add a prefix or suffix that means something to you).
*Most wireless networks will use Wi-Fi Protected Access (WPA) or (from 2006) Wi-Fi Protected Access II (WPA2) protocols, so '''WPA-PSK''' is correct for you.
**Note that your Pi is only able to use these protocols.
**The earlier Wired Equivalent Privacy (WEP) was officially withdrawn in 2004 as too easy to crack, so it is not supported on a new Pi.


You might expect <code>sudo systemctl disable fake-hwclock.service</code> (or remove the service, and modify the scripts that call it) could ensure the computer (if online) has to get a time found on the internet (NTP). Nothing is as simple as it might seem!
Should you wish to set up your Pi with several network definitions, please see [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).


===Downloading MX distribution on PC===
===Commands to do actions on a service===


You will need to start (or restart) MX after you have defined (or redefined) the service as instructed above. The specific commands to use with MX service are at [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]], here I simply repeat the basic commands that can be used with any service (status, enable, disable, start, stop, and restart).
If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!


Don't forget you may need to type <code>sudo systemctl daemon-reload</code> to tell "systemd" that it needs to reload all service definitions whenever either one has changed, or a new one has been added.
Click '''QuickConnect''' and you should see the local files in the left frame and your Pi home files in the right frame. The easiest way is to find the folder called '''CumulusMX''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.


In all these commands, '''just replace [service_name] with ''cumulusmx''''' (or enter the name of another service).
If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).
* <code>sudo systemctl status [service_name]</code>
** (displays whether named service has started, whether it has failed, whether it has stopped, also whether enabled, extra information will be added should status change)
** type the single character "q" to quit updating status display and return to prompt
* <code>sudo systemctl enable [service_name]</code>
** (typed just once, and service named will automatically start when your Linux computer is booted)
** the confirmation message says a link has been created
* <code>sudo systemctl disable [service_name]</code>
** (used when you don't want an automatic restart of the named service)
* <code>sudo systemctl start [service_name]</code>
** (will start the named service)
* <code>sudo systemctl stop [service_name]</code>
** (will stop the named service)
** Closing MX with "cumulusmx" as the named service this way does a proper shutdown
* <code>sudo systemctl restart [service_name]</code>
** (issues a stop, then start, command to named service)
** You can upgrade MX by installing new files over the existing ones, while MX is left running, and then use this command to pick up new release with minimum downtime.

Latest revision as of 08:38, 20 September 2023

Using MX on UNIX-derived Operating Systems

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

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

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

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


Why install MX on Linux?

Contributions to the Cumulus Support Forum suggest that:

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

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

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

If you are running MX on on any computer running the Microsoft Windows Operating System, then you should be reading the MX on Windows OS page instead. In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs. It appears this is not because Microsoft computers are so more readily available and therefore known about; but because people often find “installing”, and using, MX is more difficult when using the more complex Microsoft Windows operating system, and people tend not to understand basic issues such as avoiding "Program Files".


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

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

Device Coverage

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

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

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

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

Further Information

There are various related pages to get more information:

  • If you encounter a problem when running MX, please see What to do when I have a problem with MX
  • If MX gives you a message saying "you are not running the latest version", please see Guide to upgrading MX
  • If you are puzzled by the terminology, please see Category:Terminology for links to pages that explain terminology used by Cumulus (these pages were written for the legacy Cumulus 1 and may need updating for MX)
  • If you need to know more about files in the installation, please see Category:Cumulus Files for links to all Wiki pages describing the sub-folders and files used by MX
  • Go to Category:Cumulus MX for links to all pages in this Cumulus Wiki that relate specifically to MX
  • Admin interface provides information on configuration and web pages for viewing your weather data locally
  • The Cumulus MX FAQ page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
  • If you were using the original (now legacy) Cumulus software, please read Migrating_from_Cumulus_1_to_MX, although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, and was written for an old MX release, it will help you understand configuration differences.
  • If you want to use a script language, you might want to read PHP Hypertext Pre-processor and JavaScript page
  • If you will be using the standard web pages (from release 3.10.1) see this page
  • If you want to write your own customised templates, read Customised_templates.
  • If you want to explore alternative web pages from third-parties, start on User Contributions page.


Preparing your computer for installing the Cumulus MX suite

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

That page covers:


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

Technical aside

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

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

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

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

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

Cumulus packages

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

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


Handling zip files

Each release is presented as a zip. It does not matter which device (if you have two or more computers), or which browser (it can be default browser for your device or the browser you like best) you use for the download. When your browser saves the zip it might be into a folder called “downloads” on your computer, or you may be able to save into another folder that you prefer (perhaps on a different partition). Your browser might even remember the folder you used before for files of type zip.

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

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

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

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

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

If you have chosen to do the download on a different device to that on which you will install, you can unzip on either device. To transfer either the downloaded .zip file, or the extracted file structure, between devices, you can use a file transfer package, or use a portable drive (a memory stick or even a memory card) with a partition formatted so that you can read it on both devices. Windows and Linux partitions are formatted in different ways. While it is likely that Linux can read a Microsoft formatted partition, Microsoft Windows can never read a Linux formatted partition.

Where to install all packages?

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

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

It is important to minimise the length of the path name, because this path name has to be passed between various different software languages (and longer paths risk truncation).


Creating the CumulusMX sub-folder

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

Packages to install

We shall install the Cumulus software listed on Software page:

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

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

Alternative download link for older package releases

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

Old Cumulus MX packages

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

Check if posts in the Cumulus Support Forum tell you that the current release of MX has one or more bug(s) that affects one or more aspect(s) of MX that you intend to use.

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

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

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

Old utilities

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

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

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

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

Upgrading a Cumulus package

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

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

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

If you run MX as a service, then:

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

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

The alternative is to install in a new folder (or rename the old one), and copy across files not in the release from old location to new location, but in that alternative you might forget some files.

Changing location of Cumulus MX

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

Configuration Files to copy across from any previous Cumulus installation

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

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

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

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

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

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

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


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

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

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

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

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

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

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

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

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

"data" directory

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

You may also wish to read:

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

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

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


"Reports" directory

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

MX can cause problems with storage

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

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

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

web directory

All the files in this folder come from the download.

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

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

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

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

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

Notes:

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

Running MX

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

Parameters

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

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


Your first run of MX on Linux

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

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

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

Run interactive or as a service

MX can be run in two different ways.

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

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

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

Running MX interactively

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

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

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

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

Interactive advice

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

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

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

Running MX interactively from a remote computer

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

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

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

Running another executable with a terminal session left open

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

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

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


Running MX as a Linux "systemd" service

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

For more information, see original release announcement.

The Service definition file

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

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

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

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

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


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

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


Technical users - additional edits

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

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

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

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

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

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

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

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

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

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

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


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

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

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

Technical Notes only relevant to Raspberry Pi

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

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

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

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

Commands to do actions on a service

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

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

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

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