MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

MX on Linux (view source)

Revision as of 14:57, 27 August 2021

3,519 bytes added ,  14:57, 27 August 2021
m
→‎Report and data files to copy across from any previous Cumulus location
(28 intermediate revisions by the same user not shown)
Line 101: Line 101:
===sudo===
===sudo===


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


The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.
For example, the Raspberry Pi Operating System has a single default user "Pi", with their home folder that can be referenced as "~".


If we are working away from the folder(s) owned by the default user, we can consider whether we want to change the ownership of these parts of the file system (how to do this for a MX installation is explained later) so that we can access the files with our default user without using "sudo" for file/folder commands.
In the '''apt''' context here, those limited rights allow use of actions that just read (such as '''search''', ''show'').


In some limited cases, it might make sense to just change "read" rights,so that the default user can read a file/folder, but other actions are not possible without using "sudo" prefix. This limits our ability to accidentally delete files that other processes need.
However, for any action involving writing (such as '''install''', ''full-upgrade'', '''update''', ''autoremove''), the package manager needs additional rights, and we prefix the "apt" with '''sudo'''.
 
: Elsewhere on this page you might notice [[#Running any MX executable with a terminal session left open|'''cd''']] can move round the file structure (without a "sudo"), but "sudo" is used with [[# Installing/Configuring the MX service and the -service parameter|'''cp''']] as that writes a file.
 
Novice readers should exercise caution, because using "sudo", changing folder/file ownership, adding write rights, and even using "-R" or "-y" flags, can all make it very easy to inadvertently do the wrong action, even perhaps delete vital folders/files. 
 
: '''For technical readers only''', "sudo" is further explained later [[#su_and_sudo]]). Briefly,  "sudo" gives super-user (root) rights when executing the instruction that follows for actions on files that are either not in the current user's ownership, or for which the current user lacks necessary (read, write, execute) permissions.


===apt===
===apt===
Line 113: Line 119:
The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   
The second part of our installation commands is “apt” meaning “Advance Package Tool”. In simple terms, it runs the “package manager” used in Linux.   


If you are looking online for a tutorial on how to install packages, you might see “apt-get” or "apt-cache" used in examples they quote. It should be safe to replace these older package managers with "apt". I have included a little technical explanation at the end of this page if this really worries you.
If you are looking online for a tutorial on how to install packages, you might see “apt-get” or "apt-cache" used in examples they quote. It should be safe to replace these older package managers with "apt". I have included [[#Package Manager – a brief technical aside|a little technical explanation]] at the end of this page if this really worries you.


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


For the record only, here is full list of what can follow “apt”:  
Here is full list of what can follow “apt”, as we will use some of the alternatives later:  


{| class="wikitable" border="1"
{| class="wikitable" border="1"
Line 133: Line 139:
|-
|-
! scope="row"|upgrade
! scope="row"|upgrade
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions
| Once your "source list" is up to date, the instruction "upgrade" can be included after "apt" to download any newer versions now available in repositories, and to replace those packages that are already installed on your computer with those newer versions.  (You cannot upgrade the actual kernel within the operating system with this instruction, so there is no necessity to reboot your Linux computer).
|-
! scope="row"|full-upgrade
| Once your "source list" is up to date, the instruction "full-upgrade" can be included after "apt". The advantage of "full-upgrade" over the simple "upgrade" is that it picks up dependencies, and so results in more components being upgraded. (Again, this does not affect kernel and does not require a computer reboot).
|-
|-
! scope="row"|autoremove
! scope="row"|autoremove
Line 170: Line 179:


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


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


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


=== USB HID ===  
=== USB HID ===  
Line 190: Line 206:


MX uses this library for weather stations  (like Fine Offset and USB connected Oregon Scientific models) that appear as a HID via a USB connection. To check if your weather station appears as a HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.
MX uses this library for weather stations  (like Fine Offset and USB connected Oregon Scientific models) that appear as a HID via a USB connection. To check if your weather station appears as a HID, download this [https://cumulus.hosiene.co.uk/download/file.php?id=11414 USB HID test package] and run it.


This HidSharp library calls a package ''libudev shared library'' file called ''libudev.so.1''. Most recent Linux distributions will already include the libudev shared library. On my Raspberry Pi, [[#install|typing]] <code>apt search libudev</code> showed ''libudev.so.1'' was already installed.  If it is missing, then [[#install]] it.
This HidSharp library calls a package ''libudev shared library'' file called ''libudev.so.1''. Most recent Linux distributions will already include the libudev shared library. On my Raspberry Pi, [[#install|typing]] <code>apt search libudev</code> showed ''libudev.so.1'' was already installed.  If it is missing, then [[#install]] it.
Line 242: Line 257:
: <code>sudo apt install -y mono-complete</code>.  
: <code>sudo apt install -y mono-complete</code>.  


The “sudo”, “apt”, “install”, and “-y” have already been explained.
* The “sudo”, “apt”, “install”, and “-y” have [[#The various components to commands for installation|already been explained]].
* The "mono-complete" is the package we want.


The "mono-complete" is the package we want.
:Please note that if you just specify “mono”, you will get ‘’’mono-devel’’’ (the developer edition) that does not include all the components required by each of the Cumulus executables.


:Please note that if you just specify “mono”, you will get ‘’’mono-devel’’’ (the developer edition) that does not include all the components required by each of the Cumulus executables.
Please note that a particular MX build might specify it needs a particular version of Mono.  Hence, although normally you can upgrade any (CumulusMX.exe, ExportToMySQL.exe, CreateMissing.exe, proposed CreateRecords) cumulus package without upgrading Mono, sometimes you will need to install Mono again.


Please note that a particular MX build might specify it needs a particular version of Mono. Hence, although normally you can upgrade a cumulus package without upgrading Mono, sometimes you will need to install Mono again.
The latest release of Mono can always be downloaded from [https://www.mono-project.com/download/stable/#download-lin] for a variety of Linux distributions:
# follow step 1 there,  
# but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’


The latest release of Mono can always be downloaded from [https://www.mono-project.com/download/stable/#download-lin], follow step 1 there, but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’
The complete mono package includes a component (mono-xsp4) that creates a simple web server to run ASP.NET 4.0 applications. MX does not need this, so type <code>sudo update-rc.d mono-xsp4 disable</code>.


=Cumulus packages=
=Cumulus packages=


Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.  If you are using the [[Software#Cumulus_MX|pre-built disc image]], then (unless the MX release version included in your image is an old one) you should skip the instructions for "CumulusMX".
Note use of plural in section name above, the following sub-sections will install various packages produced by Developer Mark Crossley.  If you are using the [[Software#Cumulus_MX|pre-built disc image]], then (unless the MX release version included in your image is an old one) you should skip the instructions for installing "CumulusMX" itself.


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


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


==Where to install all packages?==
==Where to install all packages?==
Line 283: Line 300:
*# The developer suggests you use ‘’’/opt’’’ for EXISTING PATH (which should be available on any Linux computer).   
*# The developer suggests you use ‘’’/opt’’’ for EXISTING PATH (which should be available on any Linux computer).   
*#* By default, the code Mark provides for installing Cumulus as a service, will run that service as a root user, and the root user has full permissions in /opt (and everywhere else)
*#* By default, the code Mark provides for installing Cumulus as a service, will run that service as a root user, and the root user has full permissions in /opt (and everywhere else)
*#* If you do choose a EXISTING PATH outside your home folder, you might want to change the ownership of the "CumulusMX" sub-folder, to the default user (Pi), if so, type <code>sudo chown -R pi: EXISTING PATH/CumulusMX</code>.  The advantages of that command is you no longer need "sudo" to access the files (however, if you are running MX as a service, you also need to edit the user in the script provided to create the service, so MX does not create files with root ownership - this will be covered later)
*#* (Novices: Skip this step) If you do choose a EXISTING 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: EXISTING PATH/CumulusMX</code>, and reduce the need to use "sudo" on many actions. 


==Packages to install==
==Packages to install==


<big>We shall install the Cumulus software listed on [[Software]] page</big>:
<big>We shall install the Cumulus software listed on [[Software]] page</big>:
# '''CumulusMX’’’:
# '''CumulusMX''':
#* '''CumulusMX.exe’’’ is written in C#
#* '''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 [[Software#Latest_build_distribution_download]]
#* Download '''CumulusMX zip file’’’ from the link at[[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''Create Missing''']]:
# [[Software#Create_Missing|'''Create Missing''']]:
#* '''CreateMissing.exe''' is another C# package
#* '''CreateMissing.exe''' is also written in C#, created, and developed, by Mark Crossley
#*  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]]), 
#* Download '''Create Missing zip file''' from the link at [[Software#Create_Missing]]
#* Simple Instructions for using this executable are on the github page where they are found, you can find the link for that at [[Software#Create_Missing]] in this Wiki.
#** 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'''
#*  '''ExportToMySQL.exe''' is also written in C#
#*  '''ExportToMySQL.exe''' is also written in C# by Mark Crossley
#* Download '''ExportToMySQL.exe''' package from [[Software#ExportToMySQL]]
#* Download '''Export To My SQL zip file''' from the link at [[Software#ExportToMySQL]]
#* '''ExportToMySQL.exe''' is not (at the time this was written) documented in this Wiki although [[MX_Administrative_Interface#MySQL_settings]] does describe a similar utility (written by Steve Loft) that was actually included in early MX release downloads.
#** 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, there is another utility, '''CreateRecord''', initialised in the Github areas managed by the developer where Cumulus is worked on.  This will, if my understanding is correct, read [[dayfile.txt]] and use that to update the various [[:Category:Ini Files|extreme record files]].  However, at the time of writing this, it is nothing more than a concept that needs to be coded, and (as far as I know) there has been no progress on that utility for at least 4 months.
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 (any code on the developer's computer has not yet been included) 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]].


===Alternative download link for older MX releases===
===Alternative download link for older MX releases===
Line 325: Line 345:
All the (optional) files in the [[Reports folder]] can be copied across from a previous installation. If your previous installation was not on Linux, see [[#Line terminators in .txt files]]
All the (optional) files in the [[Reports folder]] can be copied across from a previous installation. If your previous installation was not on Linux, see [[#Line terminators in .txt files]]


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


 
Whilst you should copy ALL the files in the [[data folder]], from any old installation into the new installation, there are several extra considerations:
If your previous Cumulus installation was version 1.9.4, or earlier, then you need to do a lot of reading:
* '''Your new MX installation will ignore any entries prior to the MX Start Date'''  in [[Monthly log files]], such as [[Standard log files]], and [[Extra Sensor Files]]:
* [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
**  See [[Cumulus.ini#Data_Logging|'''StartDate=xxxxx''']] parameter, edit using ''Station Settings → Common Options → Advanced Options → Records Began date''
* [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
* Be aware your new installation has to use the same "locale" as the old installation, or MX will struggle as the locale affects how new lines are stored, and how MX expects old lines to have been stored.
* [[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
* Microsoft Windows uses different line terminators, see [[#Line terminators in .txt files]], although MX should cope, any third party routines reading your data files will probably not accept a line terminator change.
* If your previous Cumulus installation was of the legacy software, version 1.9.4, or earlier, then you need to do a lot of reading:
** [[Amending dayfile]] tells you about how MX is far more fussy about the content in [[dayfile.txt]]
** [[:Category:Ini Files|.ini files]] explains how time-stamps are formatted differently in the extreme tracking files
** [[Migrating from Cumulus 1 to MX]] gives some advice about differences in settings, but be aware that the way MX handles settings varies by release, and information on the linked page may be out of date


==Configuration Files to copy across from any previous Cumulus installation==
==Configuration Files to copy across from any previous Cumulus installation==
Line 339: Line 363:
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file
*[[Cumulus.ini]] (note initial capital, then lower case) – main configuration file


If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.
Just copy the existing files from old to new installation, if
# 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 means you do not have a recent release)
# Your old installation was on a Linux computer (not a computer running Microsoft Windows Operating System)


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


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


'''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.
{| class="wikitable"
|-
! scope="col" style="width:450px; color:blue" | Cumulus.ini !! scope="col" style="width:450px; color:navy" | 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 [[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).


You create a “strings.ini” file by selecting some of the parameters from the [[samplestrings.ini]] file that is included in each MX release, and modifying the value for the listed attributes as you type them (under the same group titles - these are enclosed in [ ] as before).  
The sections that appear in '''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 [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 to make any change.


The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX.  So be cautious if you try to use a "strings.ini" file originally created by the legacy software, check whether the parameters you used before are still available in the latest "samplestrings.ini".
To remove any parameters no longer used in this file, see [[Cumulus.ini#How_to_Remove_Redundant_parameters_from_file|remove redundant parameters]]


The content of "samplestrings.ini" is changing as MX is developed. Therefore, your existing “strings.ini” might need to be modified. There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it. Instead, you need to manually check each parameter you have in your “strings.ini” file to see if that parameter is in “samplestring.ini” included in the release you have installed. You may also find new parameters in “samplestring.ini” that you wish to add to your “strings.ini” file to tailor new functionality to your preferences.
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
 
| The content of "samplestring.ini" is changing as MX is developed:
===Cumulus.ini===
* 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.  
If your old release was 3.8.0 or later, then copy the [[Cumulus.ini]] file used in that old installation into your new one. The file is growing with lots of new parameters, and the tables on the page I have just linked indicated when parameters were introduced, and where those settings may be changed to make it simple for you to ensure all settings are right for your new release.
* 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 your old release was older that 3.8.0, then you will see [[:Category:Configuration Files|the Configuration Files page]] shows different links for documentation on older "cumulus.ini" files.  Because of those differences, many people prefer to rename their existing “Cumulus.ini” file when upgrading from such an old release, or making an install on a new device. To create a new file, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.  However, you do need to be aware that such older releases included a lot of "read-only" parameters that had to be set manually in the file, you may find some of those parameters are still needed by you, so you will want to edit the new file, with MX stopped, and copy any of those old "read-only" parameters that might not yet be settings you configure within the MX interface (although the number of these is diminishing with each new release).
|}


If you previously used an older release of Cumulus, but in this new installation will be using the latest release (latest is what is normally best, unless it has bugs), you may want to read up on all the changes between your old release and the current release, not just changes that affect the configuration file.
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.
Line 407: Line 447:
# as a service and  
# as a service and  
# interactively with terminal window left open.
# interactively with terminal window left open.
As a side-note, some weather station types require MX to be run with '''root''' rights, this is why ''sudo'' is included in each example command, but if you have technical knowledge and know your weather station can be run with default user, you can omit the ''sudo'' provided your user has ownership of all folders and files used by MX.


== Optional parameters to add to the instruction to run the MX engine ==
== Optional parameters to add to the instruction to run the MX engine ==


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


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


=== Parameter for changing Port ===
=== -port parameter for changing Port ===


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


=== Parameter for changing Locale ===
=== -lang parameter for changing Locale ===
 
Individual computers may have different default for their locale.  The forum reported an issue with OS X with its default US locale even if that is not your locale.
 
As MX starts its output (to diagnostic log and to any interactive terminal window) says which locale is being used, '''Current culture: English (United States)'''.  That default locale will relate to the one your computer had when mono is installed, as it is mono that tells MX all the locale settings. If you notice MX starting with wrong locale, issue the correct instruction to close MX.


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


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


If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.  
If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.  
Line 432: Line 476:
Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.
Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.


=== Parameter for running as service ===
=== Installing/Configuring the MX service and the -service parameter===


The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>
The parameter syntax is <code>sudo mono CumulusMX.exe -service</code>
Line 438: Line 482:
You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.
You don't use this parameter in a terminal or interactive instruction for running MX. Instead it appears within a file that we use to set up for running MX as a service.
   
   
For the latest release, (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 this later release announcement]:
For recent releases, (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146473#p146473 original release announcement]):
#There is a task to do just once to configure the service
#There is a task to do just once to configure the service
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
#Find the '''EXISTING PATH/CumulusMX/MXutils/linux/''' sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
Line 452: Line 496:


There are some edits needed to that section:
There are some edits needed to that section:
# Replace '''User=root''' if you want the service to run as a different user
# Technical users might want to edit the '''User=root''' line so that the service will run as a different user, novice users are best to leave this alone
# Edit the line that begins with '''ExecStart='''
# Everyone must edit the line that begins with '''ExecStart='''
#* The mandatory change is to replace '''/home/install''' by what you have selected for EXISTING PATH
#* The mandatory change is to replace '''/home/install''' by what you have selected for EXISTING PATH
#* An optional change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections above
#* An optional change is to add additional parameters after the '''-service''' (select from '''-debug''', -locale, -port) as described in sub-sections above
#save file with a new name '''cumulusmx_mine.service''' (using a new name stops it being overwritten when we upgrade MX
# Next save file with a new name '''cumulusmx_edited.service''' (using a new name stops it being overwritten when we upgrade MX
#now copy file to where it is needed to run the service:
# 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>
:<code>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx_mine.service /etc/systemd/system/cumulusmx.service</code>
# Finally, optionally create a symbolic link to that file using <code>sudo systemctl enable cumulusmx</code> if you want the service to start after a reboot
 
Here is how the file might look after the changes:
<pre>[Unit]
Description=CumulusMX service
Documentation=https://cumuluswiki.org/a/Main_Page
After=network-online.target
 
[Service]
User=pi
Group=pi
ExecStart=/usr/bin/mono-service -d:/opt/CumulusMX CumulusMX.exe -service -debug
Type=forking
ExecStopPost=/bin/rm /tmp/CumulusMX.exe.lock


[Install]
====Setting up as a service in release 3.8.0 ====
WantedBy=multi-user.target</pre>


== Setting up as a service in release 3.8.0 ==
The previous section covered how to set up a service in all recent releases, but if you are still using the [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 3.8.0 release] then different instructions were supplied:
 
Skip this sub-section for latest release. 
 
For historic reasons, note the original instructions in the 3.8.0 [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 release announcement]:
# Ensure you are in the folder containing CumulusMX.exe
# Ensure you are in the folder containing CumulusMX.exe
# Type <code> mono-service -l:/var/run/cmx.pid CumulusMX.exe -service</code>
# Type <code> mono-service -l:/var/run/cmx.pid CumulusMX.exe -service</code>
# (to verify) note this does not allow you to add -port, -debug, -locale parameters
# (to verify) note this does not allow you to add -port, -debug, -locale parameters


=== Parameter for adding debugging ===
=== -debug parameter for adding debugging ===
 
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 data logging from the start-up of Cumulus MX by adding a parameter: 
:<code>sudo mono CumulusMX.exe -debug</code>


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


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


=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===
=== Parameters only applicable to Version 3.0.0 Beta builds of MX ===
Line 496: Line 524:
The following two parameters cannot be used with MX since it came out of 3.0.0 beta.
The following two parameters cannot be used with MX since it came out of 3.0.0 beta.


==== web sockets ====
==== -wsport parameter for web sockets ====


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


That parameter [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887&p=138815&hilit=sockets#p138815 is now deprecated as Web Sockets in all builds since 3045] use the same port for web sockets as for the HTTP port of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see -port parameter described earlier.
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]].
 
==== Debugging of data flow between station and MX====
 
Use '''sudo mono CumulusMX.exe -Logging=1''' (for the station to MX transfers to have increased debugging logging).  


Note use of this parameter is now deprecated.
==== -logging parameter for debugging of data flow between station and MX====


Although this is not mentioned in any release announcements, it appears that on all recent MX releases this effect is incorporated into the '''-debug''' parameter described earlier. Perhaps someone could confirm whether this is true.
Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CumulusMX.exe -Logging=1</code> (for the station to MX transfers to have increased debugging logging).  


Note use of this parameter is now deprecated, as it has been incorporated into '''-debug''', see above.


==Running as a service==
==Running as a service==
Sfws
5,838

edits

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

Navigation menu