Cumulus Wiki

MX on Linux: Difference between revisions

Page Discussion

MX on Linux (view source)

Revision as of 12:00, 23 January 2025

2,615 bytes added ,  23 January
m
→‎Parameters
mNo edit summary
 
(9 intermediate revisions by 3 users not shown)
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.
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 severelycause damageproblems with storage=
 
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) or external drive (with a spinning 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.
* "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=
|-
! 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 monodotnet ./CumulusMX.exedll -port 9999</code> and the interface will run at port 9999 instead.
|-
! scope="row" | -service
|-
! 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>sudodotnet mono./ CumulusMX.exedll -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
|}
 
 
 
==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 [[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.
 
Information about settings is on other Wiki pages ([[MX Administrative Interface]] and [[Cumulus.ini]]).
 
# 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]]).
#* 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).
# Within the provided file you should find a [Service] section:
ExecStart=/usr/bin/mono-service -d:/home/install/CumulusMX CumulusMX.exe -service
Type=forking
ExecStopPost=/bin/rm -f /tmp/CumulusMX.exe.lock</pre>
There is more in the file, but for now focus on the line including "ExecStart=/usr/bin/mono-service -d:".▼
 
*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.
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.
 
▲: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.
Do change "/home/install/CumulusMX CumulusMX.exe". Replace that with "CHOSEN PATH/CumulusMX.exe".
 
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: <code>'ExecStart=/usr/bin/mono-service -d:CHOSEN PATH/CumulusMX CumulusMX.exe -service -debug -port 999 - lang el-GR</code>
* 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:
# 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 "sytemdsystemd" 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
 
====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).
Novice users, skip this subsection.
 
: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 Younote maysome alsoweather wishstations torequire addother anchanges extraoutside linethis afterfile thebefore "Group"Cumulus linecan <code>ExecStartPre=/bin/sleepmake 5</code>contact, thisone example is todiscussed delay[https://cumulus.hosiene.co.uk/viewtopic.php?t=20413 theon startingsupport offorum MXhere], bybut 5there seconds whileare other servicestopics startthat (onmay abe reboot of your computerrelevant) that might affect MX. (For some users, change 5 into 10, it all depends what else is being started).
 
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).
Note that this delay on reboot in the [Service] part of the file is not enough of a delay to cope with the Raspberry Pi being switched off and later switched on, so this is why an edit is also needed in the [Unit] part of the file to fully cope with dependency on other services, so that will be described next. Look at the rest of the file, the '''[Unit]''' part.
 
: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 <code>After=network-online.target</code>.
For release 3.15.1 build 3170 (19 March 2022) onwards: you will see an extra line <code>Wants=network-online.target</code>
 
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.
 
AsIf anyour examplecomputer 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>. AUsing standard"Requires" raspberryensures pithese computerrequesting does notevents have ahappened real-timebefore clock,MX socan whenstart, youif switchthey it onfail, theMX clockwill justnot continuesbe fromstarted, whateverthis theexample timehas wasnot whenspecified ita wastime switchedthat off,MX asshould MXwait usesfor the timeother takenservices fromto your computer, all MX actions will use this "stale" timestart!
 
For that ''time-sync.target'' to work, you need to '''enable''', by creating the symbolic links needed, the appropriate services outside this edit:
If the computer has online access, then it can look up the correct time online and adjust its clock. The extra line in the example should be added if we don't want MX to start 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. 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!
<pre>sudo systemctl enable --now systemd-timesyncd.service
sudo systemctl enable --now systemd-time-wait-sync.service
</pre>
 
 
#* 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 eithersome a real-time clocksource chip(see notes below), orwhich acould timebe founduseful onif theyour internetweather (NTP),station i.e.type thisdoes willnot ensuretime-stamp thatreadings Cumulusstored obtainsin the correctconsole, timeand fromyou the computerwant to controlensure allMX itsreads actionscorrect time from your computer
#*#* 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.''
 
====Technical Notes only relevant to Raspberry Pi====
===Commands to start, stop, or restart (stop and start in one command) MX as a service===
 
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.
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 [[Raspberry_Pi_Image#systemctl_commands|systemctl_commands]], here I simply repeat the basic commands that can be used with any service (start, stop, and restart).▼
 
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.
In all these commands, '''just replace [service_name] with ''cumulusmx''''' (or enter the name of another service).▼
 
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.
* sudo systemctl start [service_name]▼
* sudo systemctl stop [service_name]▼
* sudo systemctl restart [service_name]▼
 
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!
If you want MX to automatically start when your Linux computer is booted, just type <code>sudo systemctl enable [service_name]</code> once, and it will be activated on each reboot. Change the "enable" into "disable" if you don't want an automatic restart.
 
===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 full set ofspecific commands to use with thisMX 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).
 
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.
 
▲In all these commands, '''just replace [service_name] with ''cumulusmx''''' (or enter the name of another service).
* <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.
NeilThomas
445

edits

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