MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

MX on Linux (view source)

Revision as of 12:57, 15 March 2022

3,614 bytes added ,  15 March 2022
m
Updated for MX release 3.15.1 - only affects section 9.4 re editing service file
m (→‎web sub-folder: correct link)
m (Updated for MX release 3.15.1 - only affects section 9.4 re editing service file)
==Where to install all packages?==
 
For simplicity on this page EXISTINGCHOSEN PATH (the contents of this will start with a slash “/”, but not end with a slash) is used to represent any location in the Linux file structure where you decide to install all the Cumulus packages.
 
The phrase “EXISTING“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 <code>sudo mkdir EXISTINGCHOSEN PATH/CumulusMX</code> first (note that EXISTINGCHOSEN PATH is explained above and always starts with a slash “/”).
* By using the phrase EXISTINGCHOSEN 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 EXISTINGCHOSEN 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 EXISTINGCHOSEN 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 EXISTINGCHOSEN 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: EXISTINGCHOSEN PATH/CumulusMX</code>, and reduce the need to use "sudo" on many actions.
 
==Packages to install==
In a terminal session, issue commands in the following format for each file (this example relates to Raspberry Pi and uses "/var/tmp" which was defined in the extra line added to fstab earlier):
 
<code>sudo ln -s /var/tmp/availabledata.json EXISTINGCHOSEN PATH/CumulusMX/web/availabledata.json</code>
 
Notes:
* The "-s" flag is what says you are creating a symbolic link
* Full paths are given both for the file that MX is to be redirected to, and after it the path where it expects to create the file
* "EXISTINGCHOSEN 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 "availabledata.json" is just one file in the set of files linked from [[:Category:JSON Files]].
 
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 <code>cd EXISTINGCHOSEN PATH/CumulusMX && sudo mono CumulusMX.exe</code>.
* This is two commands issued together, the first changes the working folder, the second actually starts the main executable
 
Open a terminal window, then navigate to the folder where you have installed the 3 Cumulus executables:
 
<code>cd EXISTINGCHOSEN PATH/CumulusMX</code>
 
Next decide which executable you want to run, for [[Software#Create_Missing|Create Missing utility]], that link takes you to a section of this Wiki where there are links to more information about the utility, to run it type:
To run [[Software#Export_To_MySQL|Export To My SQL]], you change the name of the executable above and add the necessary parameters, as explained in links from that link.
 
If you have followed advice at [[#Where to install all packages?]], the user you are using will own the "EXISTINGCHOSEN PATH/CumulusMX" folder and you may be able to omit the "sudo".
 
Just in case it is not obvious .... if you start any executable using this command in a terminal window on your Pi, you must leave that session running, or that executable will stop running.
*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 as a Linux "systemd" service==
 
Running interactively allows MX to display error messages to you, and to confirm when it is running normally. If you run MX as a service you do not get any direct feedback, and cannot see if there has been a problem or failure.
 
Cumulus MX constantly develops, information here may not keep up with changes made by developer.
 
If you are using a MX release before Patch release 3.8.4 - b3094 (14 September 2020), this "systemd" functionality was not available, and you should skip all the following sub-sections.
 
 
===Defining "cumulusmx" service for "systemd"===
 
The MX release distribution you downloaded and unzipped earlier includes a file that can be used as a starting point for the service definition. Find this file at ''EXISTINGCHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service''.
 
For more information, see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement].
 
Please note the content of this file changes in some MX releases, the text here may not get updates each time there is such a change. The change at release 3.15.1 is described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=162184#p162184 this forum post]. The text throughout this section has been updated to reflect that change.
====All users - mandatory edit of service file====
 
Please note the text shown here reflects content as at release 3.15.1. If you are using an earlier, or later, release then the supplied text might be different, but the mandatory edit described here is still needed.
# Open the file at ''EXISTING PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".▼
 
▲# Open the file at ''EXISTINGCHOSEN PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".
# Within the provided file you should find a [Service] section:
<pre>[Service]
ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock</pre>
 
 
There are some edits needed to that section:
# ''Everyone must edit'' the line that begins with '''ExecStart=''':
# There is a mandatory edit of path name, and an option to add parameters to the MX execute instruction.
#* The '''mandatory''' change is to replace '''/home/install''' by what you have selected for EXISTINGCHOSEN PATH
#* An '''optional''' change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections later, the example below assumes you want to add "-debug"
# The new line will then read something like '''ExecStart=/usr/bin/mono-service -d:EXISTINGCHOSEN PATH/CumulusMX CumulusMX.exe -service -debug'''
 
If you are a technical user, you may want to read the next few sub-sections, before you save this file and finish the edit.
 
If you are a novice user, then you are advised to skip the technical sub-sections that follow, and proceed directly to numbered steps below that save the file and make it usable by "systemd".
 
NoviceIf users can skip the next sub-section, but if theyyou are using a standard Raspberry Pi with some types of weather station, there is a technical change mentioned therefor editing the "[Unit]" section of the file while you are editing it, that can be implemented to ensure that Cumulus MX does a historic data catch up if that is possible.▼
 
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX)
# Exit out of the editor you are using
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot
 
▲Novice users can skip the next sub-section, but if they are using a standard Raspberry Pi with some types of weather station, there is a technical change mentioned there that can be implemented to ensure that Cumulus MX does a historic data catch up if that is possible.
 
====Technical users - optional edits of service file====▼
 
Novice users should read the guidance in previous sub-section.
▲====Technical users - optional edits====
 
 
# Open the file at ''EXISTING PATH/CumulusMX/MXutils/linux/cumulusmx.service'' using an editor. On a Raspberry Pi, use the file manager to navigate to this file, right click the file named, and select "Geany's Programmers Editor".▼
Three sub-sections follow, the first two cover edits to different sections of the file, everyone must read the third sub-section as that describes how to end edit, and what to do next.
# Within the provided file you should find a '''[Unit]''' section:▼
 
#* Recent releases of MX have a line saying <code>After=network-online.target</code>, this was not included for all past releases
 
#** This line instructs "systemd" to ensure that the network service is started after the "cumulusmx" service i.e. it requests there is a connection by LAN or Wireless to the internet.▼
If you already have the file open in an editor because of doing the edits in previous sub-section you are ready to skip to next sub-section.
#* Technical users may wish to insert this new line before the above existing line: <code>Requires= time-sync.target local-fs.target</code>▼
 
#**# The '''local-fs.target''' specifies that the ''cumulusmx'' service requires the file service to have started, i.e. checks your computer can read files before it attempts to start the ''cumulusmx'' service▼
▲#Otherwise Openopen the file at ''EXISTINGCHOSEN 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".
#**# The '''time-sync.target''' specifies that the ''cumulusmx'' service requires the computer to have synced with either a real-time clock chip, or the time found on the internet, i.e. this will ensure that Cumulus obtains the correct time from the computer to control all its actions▼
 
#**#* If you are using a weather station type that does not time-stamp the reading it supplies to a Raspberry Pi, adding that target reference is important▼
 
#**#* A standard RPi does not include a real time clock chip (it can be added via connections available), therefore when the RPi boots it initially uses a dummy clock, and this sets the time to when the RPi was last running.▼
=====Technical users - optional pair of edits to "[Service]" section=====
#**#* That means without this target being included, your Cumulus MX on restarting will think the time has hardly changed, and skip the catch-up of historic data (should your weather station settings make that available). It also means that, at least means some, measurements have been logged against the wrong time.▼
#**#* When the Raspberry Pi does do a time-sync, the time will suddenly jump, this is serious if this means the "rollover" time has been skipped over, as it implies the "dayfile.txt" will miss a line, and many measurements will be logged to wrong day.▼
 
Novice readers are advised to let Cumulus MX use the root user, following the suggestion below to change user/group entries may cause all sorts of problems and needs a good level of technical understanding to follow through all implications.
# Within the provided file you should find a [Service] section (see the contents in previous sub-section)
# Technical users might want to edit the '''User=root''' line so that the service will run as a different user, just change the name that appears after the "=" sign.
# Having changed the user name you may also need to edit the '''Group=root''' line to ensure the group name is valid for whatever new user you selected.
 
 
=====Technical users - optional edit to "[Unit]" section=====
 
The content of the "[Unit]" section of the service description file described here has evolved as MX develops. The main change is in references to '''network-online.target''':
* It did not appear at all in Patch release 3.8.4 - b3094 (14 September 2020)
* It appeared as <code>After=network-online.target</code> at some later release.
* From release 3.15.1 build 3170 (19 March 2022) it appears twice
<pre>Wants=network-online.target
After=network-online.target</pre>
 
▲# Within the provided file you should find a '''[Unit]''' section:
#* As mentioned above, the content of this section depends upon which MX release you are using.
#* All release distributions that contain the file should have the following three lines:
#*# <code>[Unit]</code>
#*# <code>Description=CumulusMX service</code>
#*# <code>Documentation=https://cumuluswiki.org/a/Main_Page</code>
#* What follows after that depends on which release distribution you have installed
▲#** ThisYou may see a line instructssaying <code>After=network-online.target</code>, that means that if the network online detection service has been started, and the network service is not running, then "systemd" toshould ensure that the network service is started after the "cumulusmx" service i.e. it requests there isstarting a connection by LAN or Wireless to the internet after starting MX.
#** You may see a line saying <code>Wants=network-online.target</code>, that tells "systemd" that the "cumulusmx" service wants the network online detection service to be started. Note that the terminology ''wants'' means MX can still start even if the network service is not running, or if the attempt to start the network service fails
# Technical users should use the editor to create a blank line after <code>Documentation=https://cumuluswiki.org/a/Main_Page</code>
▲#* TechnicalType usersinto maythat wish to insert this newblank line before the above existing linefollowing: <code>Requires= time-sync.target local-fs.target</code>
#* 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 either a real-time clock chip, or thea 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 reading it supplies to a Raspberry Pi, adding that target reference is important
▲#**#* A standard RPi does not include a real time clock chip (it can be added via connections available), therefore when the RPi boots it initially uses a dummy clock, and this sets the time to when the RPi was last running.
▲#**#* That means without this target being included, youra newly booted-up RPi will tell Cumulus MX onthe restartingtime willis just after thinkwhen the timecomputer haswas hardlyshut changeddown, andthat 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). ItSome also meansmeasurements that, at least means some, measurementswill havethen beenget 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.
 
 
=====Technical users - Saving the file and making it available to "systemd"=====
 
# Open the "File" menu, and select "Save as" and enter a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX)
# Exit out of the editor you are using
# Now type <code>sudo systemctl daemon-reload</code>, this tells "sytemd" that it needs to reload all service definitions because either one has changed, or a new one has been added
# Finally, '''optionally''', create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to automatically start after a reboot
 
 
== Optional parameters to add to the instruction to run the MX engine ==
==== -wsport parameter for web sockets ====
 
Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono EXISTINGCHOSEN PATH/CumulusMX/CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.
 
Note use of this parameter is now deprecated, as it has been incorporated into '''-port''' parameter described earlier. The reason is that [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]].
Sfws
5,838

edits

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

Navigation menu