MX on Linux

From Cumulus Wiki
Jump to navigationJump to search

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.

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 MX releases

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 build, without the bug, from CumulusMX/releases.

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

Upgrading a Cumulus package

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

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" sub-folder

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" sub-folder

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

MX can severely damage 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) or external drive (with a spining disc and moving head) that you might install MX on.

The expected life of any storage device, and the extent to which its life is shortened depends on the actual device. The external devices that have the longest life (and therefore can cope most easily with multiple read/write actions) are solid state discs (SSD). 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 sub-folder

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 second actually starts the main executable
  • Optional parameters are not normally needed, but available 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". 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

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. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
  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 /tmp/CumulusMX.exe.lock

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. Note the mandatory parameter "-service", you must leave that untouched, but you can add -lang, -port, or -debug, as in table earlier after the -service as per example below.

Do change "/home/install/CumulusMX CumulusMX.exe". Replace that with "CHOSEN PATH/CumulusMX.exe".

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


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

  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 "sytemd" 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

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.

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 this, you have to decide what is needed in your context.

As an example, 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. A standard raspberry pi computer does not have a real-time clock, so when you switch it on, the clock just continues from whatever the time was when it was switched off. If the computer has online access, then it can look up the correct time online and adjust its clock. We don't want MX to start until after the time has been synced, and we want the local file-system to be ready for MX to read/update/store files. The example extra line ensures (Requires) these events have happened before MX can start.


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 either a real-time clock chip, or a time found on the internet (NTP), i.e. this will ensure that Cumulus obtains the correct time from the computer to control all its actions
        • If you are using a weather station type that does not time-stamp the readings it supplies to a Raspberry Pi, adding that target reference is important
        • A standard RPi does not include a real time clock chip (it can be added via connections available), therefore when the RPi boots it initially uses a dummy clock, and this sets the time to when the RPi was last running.
        • That means without this target being included, a newly booted-up RPi will tell Cumulus MX the time is just after when the computer was shut down, that might be very different to the true current time. It means your Cumulus MX on restarting will skip the catch-up of historic data (should your weather station settings make that available). Subsequent measurements will then get logged against the wrong time.
        • When the Raspberry Pi does do a time-sync, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day.

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

Commands to start, stop, or restart (stop and start in one command) MX as a service

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

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

  • sudo systemctl start [service_name]
  • sudo systemctl stop [service_name]
  • sudo systemctl restart [service_name]

If you want MX to automatically start when your Linux computer is booted, just type sudo systemctl enable [service_name] once, and it will be activated on each reboot. Change the "enable" into "disable" if you don't want an automatic restart.