MX on Linux: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

MX on Linux (view source)

Revision as of 09:06, 23 April 2021

250 bytes added ,  23 April 2021
m
no edit summary
m (change sequence)
mNo edit summary
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <ttcode>sudo apt-get update && sudo apt-get upgrade</ttcode>.
 
= Installing Mono =
== Installing Mono instruction ==
 
With all the pre-requisites correct as in previous steps, you can install mono package by simply typing <ttcode>sudo apt-get install -y mono-complete</ttcode>.
*The "sudo" part of this gives us super-user rights when executing the instruction that follows
*The "apt-get" is one of the ways to search the Raspberry repository for applications, it is more powerful than just "apt"
*The "mono-complete" is the package we want.
 
With latest installs of rPi, you can also use <ttcode>sudo apt install mono-complete -y</ttcode>
 
It is important to note that MX requires the ''complete'' edition of mono. (There is also a cut-down developer edition of Mono that can be downloaded/installed, and that is the default installation).
==Tidying Mono Installation==
 
Installing mono-complete has probably added some components not needed for your particular Linux distribution. To remove unneeded components type <ttcode>sudo autoremove</ttcode>.
 
Now you have what is needed to run any executable related to Cumulus, not just '''CumulusMX.exe'''.
As the Pi does not know exactly which components are needed when multiple packages are installed with various dependencies, sometimes extra components are installed which in the end are not needed when you complete all your installations.
 
To clear up, delete any components that are not included in dependencies by typing <ttcode>sudo apt autoremove</ttcode>.
 
=Cumulus MX =
 
The download and unzip procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <ttcode>sudo mkdir EXISTING PATH/CumulusMX</ttcode> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution into home directory ('''~''').
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
Follow above instructions, again.
 
'''Either''' install new release on top of old release, '''or''' install in new place (follow all instructions as if new installation for adding existing log files) remembering that <ttcode>sudo mono CumulusMX.exe</ttcode> instruction has to be issued in new place.
 
== MX Back-up issues ==
**Your remote file names, if you have a local server as set up in the notes in the optional sections later, will look like ''/var/www/html/weather/trends.html'' or '''/var/www/html/weather/js/valuesRecentForTrends.js''', depending on your folder structure.
**If you pay for a commercial web server, remote file names will be as specified by them and not dependent on what device MX is on.
**Remember ''if web site is on your Pi'', MX needs full '''rw''' permissions to the HTML folder on your web site, so give permissions recursively using <ttcode>sudo chmod -R ugo+rw /var/www/html</ttcode> for Cumulus MX to successfully copy there.
 
== Keeping existing data and Reports files ==
*The quickest way in WinSCP is to use its command line options.
*The following apply to all clients using GUI.
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <ttcode>hostname -I</ttcode>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <ttcode>hostname</ttcode>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, (and I have not said how you can change this on a RPi!)
=== Optional parameters to add to the instruction to run the MX engine ===
 
Beta builds in MX version 3.0.0 had an optional parameter <ttcode>-wsport nnnn</ttcode> that determined which port (represented by a 4 digit number ''nnnn'') was used for '''WebSockets'''. That parameter is now deprecated as WebSockets in all builds since 3045 uses the same port as the rest of the [[MX_Administrative_Interface#The_API_interface|Admin Interface]]. The remaining parameters that are still available are described in subsequent sub-sections.
 
==== Parameter for changing Port ====
#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
#* At time of typing this, the sub-folder only contains one file, the one we need to edit
# As described later there is a choice of editors, but you can use <ttcode>sudo nano cumulusmx.service</ttcode> to edit the service configuration file
# Look for '''ExecStart=/usr/bin/mono-service -d:'''
#* Replace the path that follows the above text with the path to your CumulusMX.exe, add the '''-service''' and optionally add any other parameter (e.g. '''-debug''', -locale, -port) as described in sub-sections above.
#save file
#now copy file
:<ttcode>sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/</ttcode>
 
If you upgrade to a new release, the file in EXISTING PATH will be overwritten, but the critical file in "/etc/sytemd/system" will not be affected.
===Running as a service===
 
If you want MX to automatically start when your Linux computer is booted, just type <ttcode>sudo systemctl enable cumulusmx</ttcode> once, and it will be activated on each reboot.
 
To manually start MX as a service, (such as after any MX upgrade to a new release, or when you want to first run it), simply type <ttcode>sudo systemctl start cumulusmx</ttcode>
 
 
Use <ttcode>systemctl status cumulusmx.service</ttcode> in a terminal session to see status of Cumulus service
 
 
Whichever operating system you are using, to run MX requires an instruction that changes to the directory (EXISTING PATH) where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].
 
The simplest instruction to run Cumulus MX is <ttcode>cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe</ttcode>. Just in case it is not obvious .... if you start MX using this command in a terminal window on your Pi, you must leave that session running, then MX will continue to run.
 
You can start it off directly on your Pi, and then
*Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.
 
Use <ttcode>'''ps -ef | grep -i cumulus | grep -v grep'''</ttcode> to see if Cumulus is running or not.
 
 
You need to use the raspbian configuration tool '''raspi-config''',
*this can be accessed on your Pi either in a Graphical User Interface (GUI) where fewer options are available,
*or by running a command <ttcode>sudo raspi-config</ttcode> in Terminal where more options are available.
 
==== Mandatory configurations ====
Anyway, we need to replace the host name to personalise it to you, and make it harder for a hacker to know what device is represented by that network name.
*The name can most easily be changed within either Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name.
*but it can also be edited by opening the file where it is stored using <ttcode>sudo nano /etc/hostname</ttcode>.
 
Some network options can sometimes (depends on permissions) be configured by clicking an icon on the Pi (this icon might be two red crosses if network settings are missing, two parallel arrows if the network settings are not correctly set, or the wireless symbol if your wireless network is working).
== su and sudo ==
 
There is a command <ttcode>su</ttcode> that allows a terminal session to become a super user session with root privileges. If you use that command, without a '''sudo''' command in front, you need to type in the password (we changed earlier) when prompted. if you type <ttcode>sudo su</ttcode>, then you get root privileges without being asked to quote password. All subsequent lines in this terminal session will have a prompt that reminds you that you have root access and do not need to prefix subsequent commands with "sudo".
 
Normally, all terminal sessions will use the default "pi" user, and for individual commands, you will use a "sudo" prefix each time that command needs administrative rights, as this allows a standard Pi user to do tasks that otherwise only work for the root user.
If you are using the RPi OS GUI, it provides a file manager that displays folders and files, and if you have a mouse you can click on an object to see what actions are available. The file manager has "Home" and "Root" as bookmarks by default, you can bookmark others. Typically, any new partitions created can also be accessed from bookmarks. Depending on options you select, there may be icons on the GUI desktop to link to particular folders and clicking on these offers various options including opening them in file manager.
 
In a terminal environment, to see what files and folders are in the current directory, type <ttcode>dir</ttcode> for just names or <ttcode>ls</ttcode> for details.
 
== external storage ==
#if your drive has partitions, then you will see further entries like '''/dev/sda1''' and ''/dev/sda2''.
#type '''df''' to see whether your drive is currently mounted (being used by computer system)
#if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) <ttcode>umount /dev/sda</ttcode>, obviously replace the "a" by the appropriate letter seen in the earlier command
#if the drive does not have a partition, create one using <ttcode>fdisk /dev/sda</ttcode>, again changing the "a" into whatever letter was seen in response to the first "fdisk" command
#*"fdisk" is a utility, it will wait for further instructions, follow each with pressing "Enter"
#*type '''n''' as instruction to create a new partition
#*type '''w''' to create the partition you have now specified for Linux.
#Now we have a partition table and a partition on our drive, we can repeat '''fdisk -l''' to see the entry now added, it might be '''/dev/sda1''', where again the "a" might be a different letter
#To format this partition for Linux, we specify "ext4" as the way to format it using <ttcode>mkfs.ext4 /dev/sda1</ttcode>, again replacing the "a" as required.
#we need to create a folder within
#*"/media" for Linux in general
#*"/media/pi" for Raspberry PI OS
# As we will learn later, the relevant command (in RPi OS) is '''mkdir /media/pi/my_short_name''', where "my_short_name" is selected by you
#To mount our partition, we type <ttcode>mount /dev/sda1 /media/pi/my_short_name</ttcode>, where "sda1" is replaced by "sdb1" or whatever we saw in '''fdisk -l''', and "pi/my_short_name" is replaced by whatever we used in our make directory command.
#To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing <ttcode>nano /etx/fstab</ttcode>
#*In the editor, use the down arrow on your keyboard to move to last line, and then type '''/dev/sda1''' (change the "a" as necessary), then press "tab", then type '''/media/pi/my_short_name''' (change "pi/my_short_name" to whatever we used in our make directory command), then press "tab", then type '''ext4''' (again matching the format type we selected earlier), then press "tab", then type '''defaults''', then press "tab", then type '''1''', then press "tab", then finally type '''2'''
#*save the file (as described later in nano sub-section), hold down control key and press '''o'' letter key. Press "enter" again to confirm same file name.
== folder commands ==
 
To make a new folder in the current directory, type <ttcode>sudo mkdir folder_name</ttcode>.
 
To remove a directory type in a particular path, type <ttcode>sudo rmdir /path/directory</ttcode>. Normally, you need to remove all contents before you can remove the directory. If you are sure it is safe to remove directory and contents in one go, type tt>sudo rmdir -r /path/directory</ttcode>, but remember the contents are gone for ever, so be absolutely sure you have specified the right folder!
 
To copy folders/files from one directory to another use <ttcode>cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive</ttcode>
 
To create a logical pointer to a folder or file elsewhere, within a folder that does not have that folder/file, <ttcode>ln -s /path/elsewhere path/pointer_location</ttcode>. An example might be '''ln -s /usr/share/phpliteadmin/diary.db ~/CumulusMX/data/diary.db''' which would let MX see and update a database maintained by phpLiteAdmin.
 
=== chmod ===
 
When you are attempting any of the actions listed in this article that involve reading, creating, editing, exeduting, or moving, files; you might see an error message generally because of a lack of write (or execute) permissions on an existing file or folder. Whilst <ttcode>rm filename</ttcode> will remove a file even if it is write protected, for nano you need to change the file permissions with <ttcode>sudo chmod -R ugo+rw ~/CumulusMX</ttcode> for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).
 
 
====nano====
 
The full syntax is <ttcode>sudo nano -B Path_file_name</ttcode> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.
 
After typing the nano command you need to specify a filename (it might include a path, see earlier sub-section for use of '''/''' and '''~''') and there are examples later in this article, but if you decide to ''host a web site on your Pi'' then you might want to edit its home page with (.html or .php) name like <ttcode>sudo nano /var/www/html/index.php</ttcode>.
 
After you have made an alteration to the current contents of the file, various options are shown at the bottom. Here are two key ones:
*Another is '''^X''' which means if you press the control key down and type X you get the exit dialogue. If you have not made any edits, or have already saved the file, this just exits the editor. If you have not used control and O to save the file, it asks whether you want to save the edited file (type '''Y'''), typing just the Y key lets save continue (any other key stroke exits without saving), then it shows the current file name, if you press '''Enter''' then that file will be overwritten.
 
You might find it useful to type <ttcode>sudo nano /etc/nanorc</ttcode> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.
 
====Geany====
== removing an unwanted file ==
 
You can remove a file with various commands, including <ttcode>sudo rm filename</ttcode>.
 
== install ==
== Standard action before adding any extra packages ==
 
*We run <ttcode>sudo apt update && sudo apt upgrade -y</ttcode> to ensure all packages are up to date before we attempt to add another package.
*I remind you here that this does not update everything on your computer to the latest versions available for a Pi, that requires a different (more risky) command not taught here.
*Instead, the instruction quoted above just updates your Pi to a consistent state; based on what is in the repository you are already using.
You can install phpLiteAdmin (the significant part of that name is in the middle) to read (you can display the whole table very easily) and edit (via a friendly GUI) either, or both, of those SQLite databases.
 
Install it using <ttcode>sudo apt install phpliteadmin</ttcode>. You will need to follow the instructions in '''/usr/share/phpliteadmin/phpliteadmin.php''' to change the password, and to define the path to the database you want to read, as both databases have the wrong extension to be found automatically. You may need to change file permissions, and you may decide to use the symbolic link example given earlier so MX accesses the diary at a location that suits ppLiteAdmin.
 
I find the admin interface is not always reliable for updating the weather diary, MX uses a very simple way to access hardware;
 
I will mention 3 possible web servers:
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <ttcode>sudo apt install apache2 -y</ttcode>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <ttcode>sudo apt-get install libapache2-mod-fcgid</ttcode>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <ttcode>sudo apt-get install nginx -y</ttcode>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <ttcode>sudo apt-get install lighttpd -y</ttcode>.
 
=== Install PHP Hypertext Pre-processor ===
**being able to be used either in a fairly simple way by non-technical people
**or in an object-oriented way for those more technical to achieve success with more complex scripts.
*The simplest instruction to install it is <ttcode>sudo apt install php -y</ttcode>, which version you get depends on your Pi and its operating system.
*To check which PHP modules have been installed by the above command, type <ttcode>php -m</ttcode>.
*If you later want to use a database (and a tool like PhpMyAdmin), then your php modules loaded must include at least '''mysqli''' and '''mbstring'''.
*I will explain how to find the .ini files later, but unwanted modules can be commented out in your .ini file.
 
'''Alternatively''', you can install particular php modules, or a particular PHP version, by selecting components from a list. To do this type something like <ttcode>sudo apt install php7-fpm php7-cgi php7-cli php7-common php7.3-mbstring php7.3-mysql php7.3-curl php7.3-gd php7.3-zip -y</ttcode>. Only use this approach to force a particular version (but you may find that is not available), or if you are short of space, and you are only going to use a minority of the php features available in the full set of modules.
 
 
To test that php is installed, type <ttcode>php -v</ttcode> into terminal, and you will see the exact version that has been installed, a confirmation that it offers command line interface (cli), and a copyright notice.
 
===Creating a Home web page on your web server===
You may need to edit this file for example to specify where your include files are stored (if not in same folder as script with require/include). Replace "apache2" by "cli" in the path for the ''batch'' '''php.ini''' file that you may also need to edit.
 
To run a php script in batch, type <ttcode>php - f <file_name></ttcode>. You can redirect the output by adding a greater than symbol and the destination file (i.e. > log_file) on the same terminal line.
 
If you want the MX external commands to run a PHP script for you, use something like "sh" as the program to run (i.e. run shell script); and in the parameters something like
Maria is an alternative that has largely similar command syntax so is likely to work with code (like MX) designed to work with MySQL. Since the MX developer (Mark Crossley) actually uses Maria DB, we can have plenty of confidence it is suitable.
 
To install this database server, we type <ttcode>sudo apt install mariadb-server php-mysql -y</ttcode>.
 
Our database files will be stored at '''/var/lib/mysql''' by default. Our MariaDB configuration is stored at '''/etc/mysql/mariadb.conf.d/50-server.cnf''', and it is the ''datadir='' entry that controls where the database files are stored.
=== Making your database secure ===
 
We need to assign passwords to control access to the database by typing into terminal <ttcode>sudo mysql_secure_installation</ttcode>. That brings up a screen:
# where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
# next type '''Y''' to signify we are going to set a new password for '''root''',
* a selection approach (you select a database, then select a table, then select an action)
 
#Start the install with <ttcode>sudo apt install phpmyadmin -y</ttcode>.
#The PhpMyAdmin installer will ask some questions.
#Use your tab key to select <Yes> when it asks whether you want to configure with '''dbconfig-common'''.
You may prefer to install a different tool, perhaps '''adminer''' that works using a drill down approach. A drill down approach is when you select the database, then select the table, then select the row, then select the column, then select the action. This logical step by step approach is a popular approach, but does not suit everyone.
 
Install this drill down package with <ttcode>sudo apt install adminer</ttcode> (I leave you to work out the commands needed after that).
 
===Getting web and database servers ready for use===
You might have started using MX before you set up your database. There is a option in that part of the admin interface to create database tables (as required) for each of the 3 updating intervals. For example, the default name for the table updated at the standard interval is "monthly", but you could give it a name of "standard" or whatever you like.
 
The MX release distribution includes another executable. Type <ttcode>cd CumulusMX && sudo mono ExportMySQL.exe monthly</ttcode> to run the executable. The first parameter is "monthly" even if the table has a different name.
#if the table name is defined in the admin interface, and the table already exists in the database with the correct columns defined, then the executable will use that table.
#There is an optional second parameter that specifies the log file name to read.
#*the SQL syntax used is "insert ignore", so if the row for that log file line already exists in the table, it will skip onto next line of log file.
 
Similar instructions apply for the end of day table, although as there is only one daily summary log file, there is no optional second parameter, just type <ttcode>cd CumulusMX && sudo mono ExportMySQL.exe dayfile</ttcode>.
 
There is no way to use this executable for insert of past rows into the real-time table.
=== Restarting Web Server ===
 
After all these installs, we need to restart Apache (so it loads the PHP and MariaDB), by typing <ttcode>sudo service apache2 restart</ttcode> or (if we just want the Apache configuration reloaded) by typing <ttcode>sudo systemctl reload apache2</ttcode>. Similar commands apply for other web servers.
 
We will need to restart Apache (or whichever web server we installed) any time we change our php.ini files, database passwords, and anything else that is checked when the web server starts.
*On a Windows PC, if you right click (while viewing the boot directory on the card) there is an option called '''New''' and if you select ''a text file'' it will create an empty file with the extension '''.txt'''. (In windows there is an option to hide extensions which is on by default, so you may need to deselect this option ['''New''' menu -> ''Options''] to see this extension). On Windows you can open the file using Notepad to verify it is empty, if you gave accidentally created a file of another type like word processing it will be full of characters some of which do not display. Anyway, you must remove any extension from the file name so it is really just '''SSH'''.
 
Type into the file <ttcode>touch ssh</ttcode>, but nothing else, no empty lines, no end of line characters.
 
When the card is inserted into your Pi, on boot this file will be removed and the SSH option will be enabled. The default password is '''raspberry''', once you have successfully got SSH working. You should then use '''sudo raspi-config''' (choose option 1 = ''Change User Password'', and set the new password you will use for your SSH session next time).
If you have a Linux or Mac device, open '''Terminal'''.
 
Next, (assuming your Pi is running, and that your other device is on the same local network), type <ttcode>ssh pi@raspberrypi</ttcode> to get access to default user in your Pi.
 
(As an alternative for Windows operating system, you can install PuTTY, this has the advantage that you can enter the connection settings into it, and configure various other options, and these are remembered, so might make it easier to use. As mentioned earlier, PuTTY and winSCP work well togther because they share settings. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <ttcode>https://www.putty.org/</ttcode>).
 
When you are using a terminal, it is a sequential device, each line is either a string of characters that you type in (these might include a backspace character) or something sent back in response. The action that result from any key combinations depend on your terminal application, not just whatever you are running on your Pi. Your mouse can't affect cursor location, but the mouse might be needed to select text, the left click might copy what is selected, and the right click might paste (what is in your PC's clipboard) at current cursor position.
== Running MX from your PC ==
 
If you choose to use the simple <ttcode>sudo mono CumulusMX.exe</ttcode> command in a terminal (or command window or Powershell) session on your PC, remember MX will detect if that session is ended and will shut down MX. This means if you want to keep MX running you need to keep your session on your PC running and you loose the advantage of saving electricity by running MX on a PI because your PC remains on.
 
As I type this a new release 3.8.0 is to allow MX to run as a service, and a future release is planned to change the associated script, so anything I write here might become obsolete, and the next sub-section gives you some links to the support forum about alternatives to the new feature. Hopefully, someone will edit this article, when instructions have settled down and won't change on next release. Basically, the ability to run MX as a service, means that MX actually runs independent of the session that starts or stops the service; and therefore implies you can shut down your PC without stopping MX.
Sfws
5,838

edits

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

Navigation menu