5,838
edits
MX on Linux: Difference between revisions
m
Correcting multiple typos !
m (Correcting multiple typos !) |
|||
|
'''This page focuses on aspects of MX that are specific to the Linux operating systems.’’’
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.
=Using MX on UNIX-derived Operating Systems=
Linux is available in a multitude of different kernels, on a multitude of devices, but this Wiki page will largely ignore any technical variations (some included at end of page) and focus on giving some background content to support the basics.
The Raspberry Pi Operating System is based on Debian, one of the Linux kernels. Where appropriate, this page gives instructions specific to a [[Raspberry Pi computer page|Raspberry Pi computer]].
If you use a different kernel, or feel that this page inadequately covers what you want to know, can you add sub-sections to this page to ensure it covers the Linux device you use?
*If you encounter a problem when running MX, see [[What to do when I have a problem with MX]]
*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
*If you want to use a script language, you might want to read [[PHP|PHP Hypertext Pre-processor and JavaScript]] page
The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.
You can change the rights in a folder, or for a file, to make this prefix unnecessary outside root access requiring contexts like installation.
===apt===
|To check all components in the packages you have installed and remove those components that are not needed by the dependencies of the packages you use.
As an example, when you install mono-complete, there might be components that are never used, and “autoremove” can be used to tidy up when you finish all your installations
|-
|remove
The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.
After the “install” part mentioned above, we can add “-y” to signify that we want the install to continue.
=== Name ===
If you read all the previous section, it explained Linux has a ‘’’source list’’’ of ‘’’repositories’’’ from which it can load software packages.
# Our first task will be to install the appropriate mono repository, if that is not already in our source list
# Our second task will install a package called ‘’’mono-complete’’’ from the repository we just installed, (this is needed to run software written in the C# languages)
==Changing the Source List==
Note use of plural in section name above, the following sub-sections will install MX and the other packages already mentioned, all by Developer Mark Crossley.
Our next task is to install the Cumulus software listed on [[Software]] page:
# '''CumulusMX’’’, this is written in C# and we download it from [[Software#Latest_build_distribution_download]]
# [[Software#Create_Missing|'''CreateMissing.exe''']], another C# package (it will populate missing fields or missing lines in log files), Simple Instructions for using this executable is on the github page where they are found, again linked from '''Software''' page in this Wiki.
#* Using '''CreateMissing.exe''' is fully documented at [[Calculate_Missing_Values#CreateMissing.exe]] in this Wiki.
# Finally, install ‘’’Export (old data) To a Maria (or other MySQL) database server’’’ package downloaded from [[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.
==Where to install all packages?==
*For simplicity on this page EXISTING PATH is used to represent any location in the Linux file structure where you decide to install Cumulus:
**Some people install it into ‘’’/home/pi/’’’, the default folder for the default user (Pi), because then the default user has full permissions automatically
**Mark suggests you install into ‘’’/opt/’’’ which is where other additional software is often installed
* All the Cumulus packages, should be put into a sub-folder called “CumulusMX” (note where capital letters must be used).
** You can create that folder as you unzip a MX release, or you can type <code>sudo mkdir EXISTING PATH/CumulusMX</code> first (note that EXISTING PATH is explained above and always starts with a slash “/”).
** It is best to change permissions for the "CumulusMX" sub-folder, <code>chmod ugo+rwx CumulusMX</code> will give full rights to the folder, so that "sudo" is not needed to run an executable there, and you can read/update any file in the folder regardless of which user you have logged in.
*Many with a Raspberry Pi add an external drive to reduce wear on the internal micro-SD card, and so if they have to reload the kernel (sometimes called “operating system”), they don’t lose their Cumulus packages and data.
**This is more complicated in that you might have to create linux partitions on this disc, then mount these partitions, and this page is not the place to get too technical
==Alternative download link for older MX releases==
In such a case, download any earlier build, without the bug, from [https://github.com/cumulusmx/CumulusMX/releases 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 [https://github.com/cumulusmx Cumulus MX github] page, and navigate to the utility of interest, to download an older version of these utilities.
==Handling zip files==
Each release is presented as a zip.
The download and unzip procedure is exactly same on your Linux computer, as it would be on a Windows PC. So if you have two devices available, you can download on either device, and if it is not the computer you want to install on, you can use a file transfer package to move the files between devices, or use a drive (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
When your browser saves the zip it might be into a folder called “downloads” on your computer, or you
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.
==Where to install MX==
As mentioned earlier, you can choose where you install your three Cumulus downloads. It is important to minimise the length of the path name, because this has to be passed between various different software languages (and longer paths risk truncation). Here I use “EXISTING PATH” (
It was also mentioned before that you can create the folder to hold the packages in advance using <code>sudo mkdir EXISTING PATH/CumulusMX</code>, and you can change its permissions using <code>chmod ugo+rwx CumulusMX</code>.
==Upgrading a Cumulus package==
Upgrading to a new MX release is explained [[Updating_MX_to_new_version|here]], but basically follow instructions above, and install over your existing files. The alternative is to install in a new folder (or rename the old one), and copy across files not in the release.
==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===
'''This is an optional file'''.
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.
The sections that appear in '''samplestrings.ini''', and the parameters that appear within a section, changed drastically between Cumulus 1.9.4 and MX. They may also be change drastically be one MX release and the next. 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.
===Cumulus.ini===
The documentation for the latest release can be found at [[Cumulus.ini]], note that this does not explain the changes from 3.9.7 to 3.10.1, but it does include advice on (while MX is running) it can automatically update the file. This automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.
==Folders to copy across from previous Cumulus installations==
'''If you have used Cumulus before''', you will be seeking to keep your existing ([[:Category:MX txt Files|.txt]] and extremes [[:Category:Ini Files|.ini]]) files. This means you must transfer the whole [[Data folder|/data]] sub-folder from your old installation to your new installation. If you use decimal commas, you might want to read what it says on [[:Category:Ini Files|this page]].
If your previous Cumulus installation was 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
If you are using the optional “NOAA report” functionality, you must also transfer the whole [[Reports folder|Reports]] sub-folder.
===Line terminators in these files===
If you are moving from Microsoft Windows to Linux, you need to be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed).
The kernel in your Linux computer might be able to detect that it is getting Microsoft files, and discard the extra end of line character.
However, if you are reading that file in a script, it might not detect the end of line encoding. So if that script expects “LF” to terminate each line, when the script is reading the final field of each line, the script will find that final field has an unwanted “CR” in it and not recognise it as a numerical value (or time-stamp). Equally, if the script expects “CR” as line terminator, then the first field of the each line (except the first line) starts with a “LF” and the script will not recognise it as a date (or section name).
In each case, any checking for numerical input might fail, and any attempt to check/extract characters from these fields might fail because their position relative to start/end is changed.
If you run your Linux computer in a headless mode, accessing its files by a remote terminal session, be aware that the line terminator used by the remote computer may be applied to files affected by whatever command you do remotely.
===Changing line terminators===
Many editors designed for programmers (they might be described as providing a programming development environment) can change the line ending of every line (either while file is being edited or when file is saved).
‘’’Geany’’’ is a programming development editor provided on some Linux systems including Raspberry Pi, that can do this ('''Document''' menu, -->> '''Select Line Endings''').
Notepad++ is another editor available for multiple operating systems ('''Edit''' menu -->> '''EOL conversion''').
Both have capabilities to make such changes on either the single file that has focus, or all loaded files.
=Running MX on Linux=
== Optional parameters to add to the instruction to run the MX engine ==
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section does not cover all optional parameters and needs a contributor to update it!
</div>
== Beta builds of MX ==
=== web sockets ===
Beta builds in MX version 3.0.0 had an optional parameter <code>sudo mono CumulusMX.exe -wsport nnnn</code> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''Web Sockets'''.
You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
That parameter is now deprecated as Web Sockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]], see Port parameter below.
=== 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).
Although this is not mentioned in any release announcements, it appears that use of this parameter is now deprecated as it appears that on all recent MX releases this effect is incorporated into the '''-debug''' parameter. Perhaps someone could confirm whether this is true.
=== Parameter for changing Port ===
<pre>sudo mono CumulusMX.exe -port 9999</pre>
You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable
=== Parameter for adding debugging ===
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:
:<code>sudo mono CumulusMX.exe -debug</code>
You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
Since this parameter is applied when you start MX, it applies all the time MX continues to run. Obviously this log file continues to grow, the longer MX is left running, and if debugging is switched on the file will grow in size must faster. Consequently, the default is not to add the extra debugging information and the settings can be used to switch it off again if you do have it switched on.
sudo mono CumulusMX.exe -lang en-GB
</pre>
You can omit the "sudo" if you have done the recommended "chmod" described earlier on the folder containing the executable.
Other local 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'''.
Use <code>'''ps -ef | grep -i cumulus | grep -v grep'''</code> to see if Cumulus is running or not.
= Operating a web site with uploads from MX engine =
== The standard web pages ==
=== From release 3.10.1 ===
The web pages are a one-off upload from '''CumulusMX/webfiles'''. The data to be shown on these web pages are uploaded from [[:Category:JSON_Files|.json]] files in the [[web_folder]].
Please read [[New_Default_Web_Site_Information|this page]] for more information about styling options and other details.
=== Until release 3.9.7 ===
The styling and library files were a one-off upload from '''CumulusMX/webfiles'''. These release use [[Cumulus_template_file|template files]], these are [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by MX to add the variable data]], and this will create web pages that are uploaded to your web site.
Please read [[Customised_templates]] for further information about the various pages provided, and how you can customise them to suit you.
=== Comparison with legacy Cumulus 1 web pages ===
* Note that the MX web files are not the same as the ones for Cumulus 1,
** so if moving from Cumulus 1 to MX, delete all your Cumulus 1 files from the "web" and "webfiles" sub-folders, and all files from your web server; then upload files from the new "webfiles" folder.
* The standard gauges are now the SteelSeries gauges. The default gauges page does not display a graph when you hover over a gauge (as happened when you added the stand-alone Steel Series gauges to Cumulus 1).
* The trends web page in Cumulus 1 relied on that software generating graphs as images.
** In MX, the software generates files with time and value pairs, these are stored in json format, the trends page then uses a library package (Highstocks) to draw graphs from those data pairs.
== Alternative ways to obtain web pages ==
You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].
== Using your own web pages ==
* Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*# MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*# MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.
You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.
=That is
If you have read up to
The remaining sections are more technical and so you can skip them.
| |||