Cumulus Wiki

MX on Linux: Difference between revisions

MX on Linux (view source)

Revision as of 21:06, 29 September 2020

6,842 bytes added ,  21:06, 29 September 2020
m
no edit summary
mNo edit summary
Line 1: Line 1:
=Using MX on UNIX-derived Operating Systems=
=Using MX on UNIX-derived Operating Systems=


MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.  Although the article focusses on one computer type, the Rspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to other Unix-derived devices.
MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.  Although the article focusses on one computer type, the Raspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to another Unix-derived devices.


==Introduction==
==Introduction==


This article focuses on a device called the Raspberry Pi.  It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux). In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi. The Apple Mac runs its own version of Unix, so is not covered here, but hopefully this article will still be of some use by telling you what steps are needed even if the key sequences are different.
This article focuses on a computer called the Raspberry Pi.   
 
It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).  
 
In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi.  
 
The Apple Mac runs its own version of Unix, and while standard Unix uses Line_Feed to terminate lines in files, the Mac uses Carriage_Return.  Hopefully someone will write an article about the Mac in this Wiki, but in meantime this is closest you can get.


The article will give you some guidance on:
The article will give you some guidance on:
*Choosing a Pi model to buy
*Choosing a Pi model to buy
*Setting up a Raspberry Pi,
*Setting up a Raspberry Pi,
** either connecting it to a keyboard, mouse, and monitor (could be TV), and internet (wired Ethernet or wireless)
** or running it headless, where all instructions are typed into another device and the Pi has no keyboard, mouse, or monitor, but is connected to internet (wired Ethernet or wireless)
*Installing OS (the NOOBS described here can install various OS, you choose which one you want)
*Installing OS (the NOOBS described here can install various OS, you choose which one you want)
*Installing Mono (needed on any Linux based OS, but can even run on Windows!)
*Installing Mono (needed on any Linux based OS, but can even run on Windows!)
*Installing Apache, PHP, MariaDB, PhpMyAdmin, and copying your database from another device (obviously this installation can be done on any device, but the approach here is on a Pi)
*Installing MX
*Running MX (these notes apply to any Linux OS, but some hints need consideration even in Windows)
*Running MX (these notes apply to any Linux OS, but some hints need consideration even in Windows)
{{TOCright}}
{{TOCright}}
It also covers some optional extras!


== A very quick introduction to Linux ==
== A very quick introduction to Linux ==
Line 23: Line 29:


If you have a Raspberry Pi with a monitor attached, you will see a raspberry icon that you can click to get access to many features including shutdown options.
If you have a Raspberry Pi with a monitor attached, you will see a raspberry icon that you can click to get access to many features including shutdown options.
* To shutdown a Pi, type <tt>sudo halt</tt>, and then optionally turn the power off when the shut down has completed.
* To reboot your Pi, type <tt>sudo reboot</tt>, and then you will see that your Pi shuts down and then boots up again. Although the notes below rarely mention this instruction, it is usually advisable to reboot after installing new packages, or changing the configuration, to ensure everything works correctly, so you will probably use it quite often during set up.


=== sudo ===
=== sudo ===


Almost all instructions here start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows you to do tasks that only work in the root user.  You use it as a prefix to almost every command you type in terminal mode.  There are 3 system commands that will only work with this prefix (or by using the shutdown options in the main menu - raspberry icon in square):
Almost all instructions here start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows you to do tasks that only work in the root user.  You use it as a prefix to almost every command you type in terminal mode.  There are 3 system commands that will only work with this prefix:


*'''sudo halt''' = stops any cpu functions, but leaves Pi running; used when you have reached the end of commands you want to do for now
*'''sudo halt''' = stops any cpu functions, but leaves Pi running; used when you have reached the end of commands you want to do for now
Line 41: Line 44:
To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.
To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.


To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.  To give a folder and all its sub-folders and files full permissions (think carefully whether you really want to do this) type something like <tt> sudo chmod -R ugo+rw /var/www/html</tt>. See next sub-section for explanation.
To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.   


=== chmod ===
=== chmod ===


When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder.  Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).
When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder.  Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).
*'''chmod''' command to modify permissions
*'''chmod''' command to modify permissions
* the '''-R''' indicates recursive action (i.e. including not just the named folder, but all files within it and all sub-folders, and all files within sub-folders)
*letters indicating whose permission is being modified
*letters indicating whose permission is being modified
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''u''' = Owning user (sometimes the owner is the user root, sometimes the owner is the user Pi, for our web pages later we change ownership)
** '''g''' = Group (by default there are no groups, but a group can be defined if you want to define multiple users, with different passwords, but same rights of access)
** '''g''' = Group (by default the owning user is also a group, but a group can be defined if you want to give multiple users (with different passwords) the same rights of access)
** '''o''' = Other users (Public, needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
** '''o''' = Other users (write permission here is needed if for example you are using FTP to move a file from a PC to your Pi, or vice versa)
* sign for add or remove permissions
* sign for add or remove permissions
* '''+''' = add permission
* '''+''' = add permission
Line 63: Line 69:
=== nano ===
=== nano ===


There are various text editors available on a Pi, '''nano''' is a simple one. Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file. The sudo gives you access to any file, it does not change the actual file access, so you might find you can read a file, but not save it after you have done your edit.  If you change the file name shown, then it can save as another file, but you will be asked if the new name is correct (again type '''Y''' to continue saving).  Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.
There are various text editors available on a Pi, '''nano''' is a simple one.  
 
Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file.  
 
Use prefix of 'sudo' to give you access to any file, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.   
 
When in nano you select to write out to a file, it allows you to change the file name shown. If you choose to save as another file, you will be asked if the new name is correct (again type '''Y''' to continue saving).   
 
Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.


The full syntax is <tt>sudo nano -B Path_file_name</tt> 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.
The full syntax is <tt>sudo nano -B Path_file_name</tt> 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.
Line 224: Line 238:
=== Wireless Network ===
=== Wireless Network ===


Depending on your Pi model, it may on first boot ask you to enter your wireless network details, it may list the wireless networks it finds and ask you to choose, or you might need to use the configuration tool, or you might need to click on an icon with two red crosses.
How this is set up depends on your Pi model, and the operating system that is loaded on it,
*it may on first boot ask you to enter your wireless network details,  
*it may list the wireless networks it finds and ask you to choose from the listed SSID,  
*it might not prompt you so you need to use the configuration tool (see next sub-section),  
*or you might need to click on an icon with two red crosses.
 
Note that there is also a Wi-Fi network country which must be set.
 
If you have had to enter wireless details into a mobile phone, you will realise what is needed:
*The ''Service Set IDentifier'' (SSID) is the name that is used for your wireless network.
**As mentioned above, you may see a list of those that have been found. 
**You may have typed this into your mobile phone.
**It may be shown on a card that slips into a slot on your hub or router (you may have changed it from that initial setting).
**It can be up to 32 characters (letters, numbers, and symbols.
**Some routers come with a default SSID that is the manufacturer's name, if left unchanged it might conflict with a neighbour, so it is left to you to pick a SSID that is unique to you using up to 32 characters to personalise it.
*You also need to enter whatever Pre-Shared-Key (password) is used for your wireless network.
**You will have typed this into your mobile phone, so that can automatically connect to your network.
**You should have changed it (for security reasons) from whatever was shown as the initial password on the card that slips into a slot on your hub or router (possibly all you have done is add a prefix or suffix that means something to you).
*Most wireless networks will use Wi-Fi Protected Access (WPA) or (from 2006) Wi-Fi Protected Access II (WPA2) protocols, so '''WPA-PSK''' is correct for you.
**Note that your Pi is only able to use these protocols.
**The earlier Wired Equivalent Privacy (WEP) was officially withdrawn in 2004 as too easy to crack, so it is not supported on a new Pi.




=== Other configuration ===
=== Other configuration ===


There are various other configurations you need to do on your PI. Unlike SSH, these can't be done by storing files on the micro-SD card. You need to use the raspbian configuration tool '''raspi-config''', and this can be accessed on your Pi either in a Graphical User Interface (GUI), or by running a command in Terminal. The same command can be run from a remote device if you successfully have SSH running. 
There are various other configurations you need to do on your PI.
 
You need to use the raspbian configuration tool '''raspi-config''',
Whether on your Pi, or from a remote computer terminal session, the command to use is <tt>sudo raspi-config</tt>.
*this can be accessed on your Pi either in a Graphical User Interface (GUI),  
*or by running a command <tt>sudo raspi-config</tt> in Terminal.


==== Mandatory configurations ====
==== Mandatory configurations ====


When you use SSH for the first time to connect to your Pi, you will see a warning that SSH is enabled but the password has not been changed, which is a security risk.  So it is mandatory to change the network password for your Pi from the default '''raspberry''' to something that you can remember but makes life hard for anybody trying to hack into your system with malicious intent.
Within the Raspberian configuration utility, you will see an option to change password. You will want to do this so nobody can hack into your Raspberry Pi computer.  You will need to enter the new password twice before it replaces the old one.


Within the Raspberian configuration utility, you will see an option to change password. You will need to enter the new password twice before it replaces the old one.
The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name.
*The name can most easily be changed within the 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 <tt>sudo nano /etc/hostname</tt>.


The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name. The name can most easily be changed within the Raspberian configuration utility, but it can also be edited by opening the file where it is stored using <tt>sudo nano /etc/hostname</tt>.  Once we rename this hostname, if we are working headless, we will see an error message: '''sudo: unable to resolve host raspberrypi''', appearing when we leave the configuration utility.  These can be safely ignored (it's just because you renamed the Pi) and will disappear after next reboot of your Pi. 
Network options can also 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).  
 
Within the Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name. Network options can also 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).  Hopefully, for you the WiFi network and password have already been set by the '''wpa-supplicant.con'''f file added to micro-SD card earlier.


==== Recommended configurations ====
==== Recommended configurations ====
Line 248: Line 283:
*Whatever locale you use, if you have already been using Cumulus (1 or MX), you need to ensure the locale matches the one used for your log files. The versions of MX released from the middle of 2020 onwards are very fussy that all dates use the same delimiter (see [[Cumulus_MX_formal_release_versions]]), so you need to check the chosen locale continues to use the same date separator as before. The locale is affected by the version of Mono you install and whether you use the locale parameter when starting MX, so I cannot cover all options.  
*Whatever locale you use, if you have already been using Cumulus (1 or MX), you need to ensure the locale matches the one used for your log files. The versions of MX released from the middle of 2020 onwards are very fussy that all dates use the same delimiter (see [[Cumulus_MX_formal_release_versions]]), so you need to check the chosen locale continues to use the same date separator as before. The locale is affected by the version of Mono you install and whether you use the locale parameter when starting MX, so I cannot cover all options.  
*Anyway, the default locale is fine if you are in the UK, you use decimal points for real numbers, you use commas for list separators, and you don't have dates with month first!
*Anyway, the default locale is fine if you are in the UK, you use decimal points for real numbers, you use commas for list separators, and you don't have dates with month first!
*To change the locale, enter '''Localisation Options'''. Note that there is also a Wi-Fi network country which must be set, but as that has already been set by the '''wpa-supplicant.con'''f file added to micro-SD card earlier, it is listed here in the recommended section.
*To change the locale, enter '''Localisation Options'''.  


In the same option area, there are '''some more options''':
In the same option area, there are '''some more options''':
# Change Time-zone, by default UTC is used all year round. In the UK if your Cumulus is set to roll over at 10am in summer, you will wish to change the time-zone to UK time.
# Change Time-zone, by default UTC is used all year round. In the UK if your Cumulus MX is set to roll over at 10am in summer, you will wish to change the time-zone to UK time, because MX uses system time for many of its actions.
# Change Keyboard Layout if needed, keyboards can support different numbers of characters, and can have different currency symbols, so select whatever is relevant to you
# Change Keyboard Layout if needed, keyboards can support different numbers of characters, and can have different currency symbols, so select whatever is relevant to you


Line 288: Line 323:
=== Installing Mono ===
=== Installing Mono ===


With all the pre-requisites correct as in previous steps, you can install mono by simply typing <tt>sudo apt-get install -y mono-complete</tt>. It is important to note that MX requires the ''complete'' edition of mono as there is also a cut-down developer edition of Mono that can be downloaded/installed. "sudo" as already described gives us rights, "apt-get" is one of the ways to search the Raspberry respository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.
With all the pre-requisites correct as in previous steps, you can install mono by simply typing <tt>sudo apt-get install -y mono-complete</tt>.  


=== Completing Package Installation ===
It is important to note that MX requires the ''complete'' edition of mono as there is also a cut-down developer edition of Mono that can be downloaded/installed.


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 <tt>sudo apt autoremove</tt>.
"sudo" as already described gives us rights, "apt-get" is one of the ways to search the Raspberry respository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.


== Installing (or updating) MX ==
=== Completing Package Installation ===
 
In [[Cumulus.ini]] there are various settings that will need to be initialised if you start using MX, or updated if you have used Cumulus (1 or MX) before. Read the linked article for more information, but one item is to identify how to connect to our weather station.  On a zero model with only one USB socket connecting to a weather station that uses USB, the default '''ComPort''' will be right. On a model 3 with 4 USB sockets, the first USB device to be connected takes the default (ending in zero), the next device will replace that zero with one, and so on; so providing you plug in your weather station without any other device plugged into USB (plug in keyboard, mouse, external storage or USB stick afterwards) again the default will work.


If you have moved from running MX on Windows to running on your Pi, then you potentially have lots of items to update. If you are using <tt>sudo nano Cumulus.ini</tt>, then you will see control sequences for replace, next page, prior page, and all these these will come in handy.
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.  


=== MX Distribution ===
To clear up, delete any components that are not included in dependencies by typing <tt>sudo apt autoremove</tt>.


Download whatever version of MX you have decided to install (sometimes the latest version has bugs that might cause a problem for your station or the functionality you use) from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases]
== Downloading and Unzipping MX Distribution ==


====Download on Raspberry Pi====
The procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, so you already have folder ready for MX.
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#For the latest release, Open the Cumulus Wiki at the [[Software]] article.
#Download the MX distribution from the link that appears there, Mark will update it for each release he makes.


If you are download on your Pi, and that is the easiest option, you may download into '''~/downloads''' folder or you may choose location (depending on whether you have changed settings in Chrome). It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, and subsequently extract from that same level in zip, alternatively the extract can create the folder for you. Whichever approach you choose, simply open (if the distribution zip is visible right click gives you open option) the download distribution file, next you will need to click '''extract''' and choose where the files go.
If the latest release has bugs, you can Download whatever version of MX you have decided to install from [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].


====Download on PC====
#If you are download on your Pi, the easiest option is to download into '''~/downloads''' folder.
#* Whether this location is the default, or you are asked to select location will depend on whether your browser's default settings have been changed.
#When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
#Ensure the file unzips into your personal directory "/home/pi", although you could place it elsewhere, this is the easiest place to find (because it can also be represented by "~".


If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
* 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 likely to be a single figure like 0 or 1, and the xy is two 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 <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* 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 <tt>hostname</tt>) 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!


Click '''QuickConnect''' and you should see the local files in the left frame and your Pi files in the right frame. The easiest way is to find the folder called '''CumulusMX''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.


=== Configuration issues ===
=== Configuration issues ===


If you have used Cumulus before, but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*Cumulus.ini
*Strings.ini
 
The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder).
 
If you have not used Cumulus before, there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.  
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.  
Line 337: Line 364:
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions


Remember as mentioned earlier, the configuration file may need editing to update port names, any command locations, and to update file locations.  Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, that wading through all options in the interface).  
 
 
'''If you have used Cumulus before''', but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
*Cumulus.ini
*Strings.ini
 
 
The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder). Be aware that the characters terminating each line may need editing (see next sub-section).
 
 
Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations.  Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).  
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].   
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].   
*For '''Extra Web Files''', local file names will look like ''/home/pi/CumulusMX/web/trendsT.htm'' or '''/home/pi/cumulus_Templates/valuesRecentForDetailT.js'''.  
*For '''Extra Web Files''', local file names will look like ''/home/pi/CumulusMX/web/trendsT.htm'' for the standard templates, or it might be something like '''/home/pi/cumulus_Templates/valuesRecentForDetailT.js''' if you have created your own templates.  
**''Please note'' that Cumulus MX does not recognise "'''~/'''" as shorthand for '''/home/pi/'''.  
**''Please note'' that Cumulus MX program code DOES NOT recognise "'''~/'''" as shorthand for '''/home/pi/'''.  
**Your remote file names, if you have a local server as set up in the notes here, will look like ''/var/www/html/weather/trends.html'' or '''/var/www/html/weather/js/valuesRecentForTrends.js''', depending on your folder structure.  
**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, MX needs full '''rw''' permissions to the HTML folder on your web site, if web site is on your Pi, then give permissions recursively using <tt>sudo chmod -R ugo+rw /var/www/html</tt> for Cumulus MX to successfully copy there.
**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 <tt>sudo chmod -R ugo+rw /var/www/html</tt> for Cumulus MX to successfully copy there.


=== data and Reports files ===
=== Keeping existing data and Reports files ===


The entire content of your existing  '''data''' and '''Reports''' folder should also be copied  across to your Pi or transferred across using FileZilla or a similar tool. The same settings as for the distribution can be used, but you will have a different starting point in your left frame.
'''If you have used Cumulus before''', you will be seeking to keep your existing log files. If you have been using the Windows Operating System each line in each file will be terminated by two control characters (Carriage_return and Line_feed). That is fine if you have installed Windows on your Raspberry Pi.  Assuming you have installed the Raspberry Pi Operating System or another Linus distribution, then ideally all your files should be edited so they simply use Line_feed to terminate all lines. This can be easily done in an editor like Notepad++ that is designed for computer files.
 
The novice does not need to worry about changing end of line characters, it is advisable but not essential (as the Pi will treat the CR as a character it does not display)
 
To get the entire content of your existing  '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).  
 
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* 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 <tt>hostname -I</tt>). 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 <tt>hostname</tt>) 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!
 
Click '''QuickConnect''' and you should see the local files in the left frame and your Pi home files in the right frame. The easiest way is to find the folder called '''data''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.
 
If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).


== Running Cumulus ==
== Running Cumulus ==


The simplest command to start Cumulus is <tt>sudo mono CumulusMx.exe</tt>, but you may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]]. Just in case it is not obvious .... if you start MX using this command either in terminal on your Pi, or in a Command or Terminal window (or even in puTTY) on another device, the you must leave that session running for MX to continue to run. That is fine if you are happy to start it off directly on your Pi, and then switch off monitor or TV attached to your Pi, but leave Pi on so that terminal session continues. This is simple, you can use SSH access from my PC when you need to edit a file, or do a file transfer between Pi and PC or vice versa. Obviously my PC lets you view the admin interface to change settings or look at the web page provided in that interface. (I can also see my own web pages run on the web server on the Pi).
The simplest command to start Cumulus is <tt>sudo mono CumulusMx.exe</tt>, but you may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].  


That is simple if your Pi is in your home, and you can go back to the Pi when you need to stop MX (perhaps to update it to a new release). But maybe you are running Pi headless, or it is in a remote location, in that case instead of starting and stopping MX in a terminal session, you will want to issue commands that connect to a separate session for starting MX so you can disconnect from that session without causing MX to close. As I type this a new release is allowing 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 paragraph gives you some links to the support forum.  Hopefully, someone will edit this article, when instructions have settled down and won't change on next release.
Just in case it is not obvious .... if you start MX using this command either in terminal on your Pi, you must leave that session running for MX to continue to run.  


In the Cumulus Support forum, there are articles about a [https://cumulus.hosiene.co.uk/viewtopic.php?p=139779#p139779 stop/start routine], a [https://cumulus.hosiene.co.uk/viewtopic.php?p=141514#p141514 backup routine], and [https://cumulus.hosiene.co.uk/viewtopic.php?p=146028#p146028 how to run MX as a service]. I will let you hunt for and read the relevant topics, as you may find details in more than one place. This article currently avoids describing these to try to keep content simple.  Here is just a list of some alternatives to having to leave your terminal session running:
You can start it off directly on your Pi, and then
# Use '''start/stop routine''' (see earlier link), this effectively starts a separate session for MX to run in and leaves the standard terminal session free.
*optionally disconnect the keyboard,  
# Run MX as an '''init service''' (see the earlier post in the service link above), be aware that this is a new feature in the new release of MX 3.8.0, again this starts MX outside your terminal session
*switch off monitor or TV attached to your Pi,  
# Use '''Screen''' software to start up a separate session that you can log off from without MX stopping (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146203#p146203 how to run using screen]}
*Just ensure you leave Pi on so that terminal session continues running.  
#  Run MX as a '''systemd service''' (see the more recent posts in the service link above), be aware that at time of typing this is planned to be incorporated in a future release but the MX developer has no knowledge in this area


=Optional actions=
=Optional actions=


The above has covered all you need to do to use a Raspberry Pi (or other Unix-based device) to run MX.
Any novice can stop reading now, as preceding sections have covered all you need to do to use a Raspberry Pi (or other Unix-based device) to run MX.
 
However, some people want to do more, so various options are covered in the remainder of this article. If you are a novice, my advice is don't experiment with what is mentioned after this until you are happy that all you have done up to now works.  The rest of this article does get more technical, so it might be harder to understand and harder to implement. With that warning in mind, I must add that the remaining sections cover a number of items and it is very likely that some of them could be useful to you.


However, some people want to do more, so various options are covered in the remainder of this article.
There are lots of sub-sections, so you can skip over those that do not interest you, while carefully reading the ones that could benefit you.




== Before adding any extra packages ==
== Standard action before adding any extra packages ==


*We run <tt>sudo apt update && sudo apt upgrade -y</tt> to ensure all packages are up to date before we attempt to add another package.  
*We run <tt>sudo apt update && sudo apt upgrade -y</tt> 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.   
*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.
*Instead, the instruction quoted above just updates your Pi to a consistent state; based on what is in the repository you are already using.
This action is not repeated below, but potentially applies to all options below.


==Databases built into Cumulus MX==
==Databases built into Cumulus MX==
You do not need to know what is in those databases to use MX.


Cumulus MX includes two SQLite databases;
Cumulus MX includes two SQLite databases;
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#*If you do find out what the first database is used for, please update the Wiki article on it!
#The second database is the [[Weather Diary]] added by Mark Crossley,  that is documented, and in the support forum there is a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.  
#The second database is the [[Weather Diary]] added by Mark Crossley,  that is documented, and in the support forum there is a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.  
#* The [[MX Administrative Interface|Admin Interface]] provides a page to view or edit the weather diary.


You do not need to know what is in those databases to use MX. The [[MX Administrative Interface|Admin Interface]] provides a page to view or edit the weather diary.
Optionally, you could install phpLiteAdmin (the significant part of that name is in the middle) to read those SQLite databases. Install it using <tt>sudo apt install phpliteadmin</tt>.


Optionally, you could install phpLiteAdmin (the significant part of that name is in the middle) to read those SQLite databases. Install it using <tt>sudo apt install phpliteadmin</tt>.


If you do find out what the first database is used for, please update the Wiki article on it!


== Adding a web server and a database server ==
== Adding a web server and a database server ==


Now you have a Raspberry Pi (or another device than can be left running all the time without consuming a lot of electricity), you might want to add a web server and database server so you can make use of the web templates that Cumulus MX provides, and its ability to update database tables. This is an option, and may not be useful to you, but is described here in case it is something that you want to do.
This is an option, and may not be useful to you, but is described here in case it is something that you want to do.
 
This option is not needed if your MX simply updates to an external web service (several are listed in the options in the admin interface), so you do not use the web templates supplied with MX (nor any alternative web pages created by you or a third party).
 
This option is not needed if you have subscribed to a commercial web server (and optionally database server).
 
Now you have a Raspberry Pi (or another device than can be left running all the time without consuming a lot of electricity), you ''might'' want to add a web server and database server so you can make use of the web templates that Cumulus MX provides, and its ability to update database tables.  
 
You might want this option if you are creating your own web pages, and want to try them out without exposure to the public over the internet.
 
You might select this option to save the subscription costs of a commercial web server (and optionally database server).


=== Install Apache 2 (or another web server) ===
=== Install Apache 2 (or another web server) ===


I will mention 3 possible web servers:
I will mention 3 possible web servers:
#If you choose '''Apache''' it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.   
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.   
#*You might want to use Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#If you choose '''nginx''', install that web server with <tt>sudo apt-get install nginx -y</tt>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <tt>sudo apt-get install nginx -y</tt>.
#If you choose '''lighttpd''', install it with <tt>sudo apt-get install lighttpd -y</tt>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <tt>sudo apt-get install lighttpd -y</tt>.


=== Install PHP Hypertext Pre-processor ===
=== Install PHP Hypertext Pre-processor ===


*PHP is not the only script language available, but it is quite comprehensive being able to be used either in a fairly simple way or in an object-oriented way for those trying to achieve more complex scripts.   
*PHP is not the only script language available, but it is quite comprehensive  
**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 <tt>sudo apt install php -y</tt>, which version you get depends on your Pi and its operating system.  
*The simplest instruction to install it is <tt>sudo apt install php -y</tt>, 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 <tt>php -m</tt>.  
*To check which PHP modules have been installed by the above command, type <tt>php -m</tt>.  
Line 459: Line 531:
=== Installing Adminer, or PhpMyAdmin ===
=== Installing Adminer, or PhpMyAdmin ===


ExportMySQL.exe and CumulusMX.exe (see [[Cumulus_MX#Executables]] for details) both create SQL for updating tables in a MySQL database, such as the one our MariaDB software package we have installed can create; so maybe we want to install a package that lets us back up and manipulate tables in this database.  
ExportMySQL.exe and CumulusMX.exe (see [[Cumulus_MX#Executables]] for details) both create SQL for updating tables in a MySQL database, such as the one our MariaDB software package we have installed can create.


PHPMyAdmin is not the only tool that can be used to manipulate your MySQL like database (that is the significance of the "My" bit in the middle of the tools's name), and you may prefer to load a different tool, perhaps '''adminer''' that works using a drill down approach.
However, there is nothing in the MX distribution that lets us back up and manipulate (e.g. delete rows with errors, or correct rogue numbers in a column) tables in this database. This option is about installing a package to do the tasks that go with operating a database.


However, let me assume that you are happy to use '''PHPMyAdmin''' and I will describe how to install that. Start the install with <tt>sudo apt install phpmyadmin -y</tt>.  (Alternatively install a drill down package with <tt>sudo apt install adminer</tt> and I leave you to work out the commands needed after that).
'''PhpMyAdmin''' is one tool that can be used to manipulate your MySQL like database (that is the significance of the "My" bit in the middle of the tools's name).


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 like '''PhpMyAdmin''' as this offers:
* a graphical approach (you see a table on screen and navigate to the row or cell you want to work on)
* a SQL approach (you can try out any SQL here, before adding it to a script that you might use in a web page)
* a selection approach (you select a database, then select a table, then select an action)
 
#Start the install with <tt>sudo apt install phpmyadmin -y</tt>. 
#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 <tt>sudo apt install adminer</tt> (I leave you to work out the commands needed after that).


===Getting web and database servers ready for use===
===Getting web and database servers ready for use===


We need to create a user for PhpMyAdmin (or adMiner or whatever) to access our database and another for Cumulus to use to access the database tables. At the moment our database access has the single root@localhost user we created when we installed MariaDB.  The initial password was set then, and we need to use it to get access to MariDB monitor where we can insert some SQL commands to create these two users. PhpMyAdmin on first start up will ask for username and password, thereafter it will use same log-in, let us create a user called 'admin' for it. The user name and password for the data base is set in MX using the [[MX_Administrative_Interface#MySQL_settings|MySQL_settings]] in the admin interface, let us create a user called 'weather'. Obviously, these names might not be what you use, but you can amend commands below accordingly. For each line with SQL, it must end with a semicolon (;) as shown.  The SQL lines have a prompt of a greater than symbol (>) while the command lines have a prompt showing current path. Note that "identified by" is followed by a password enclosed in single quotes.
We need to create a user for PhpMyAdmin (or adMiner or whatever) to access our database and another for Cumulus to use to access the database tables. At the moment our database access has the single root@localhost user we created when we installed MariaDB.  The initial password was set then, and we need to use it to get access to MariDB monitor where we can insert some SQL commands to create these two users.  
 
PhpMyAdmin on first start up will ask for username and password, thereafter it will use same log-in (by default you see log-in screen each time you restart or if it is left idle for a long time), let us create a user called 'admin' for it.  
 
The user name and password for the data base is set in MX using the [[MX_Administrative_Interface#MySQL_settings|MySQL_settings]] in the admin interface, for it let us create a user called 'weather'.  
 
Obviously, these names might not be what you use, but you can amend commands below accordingly. For each line with SQL, it must end with a semicolon (;) as shown.  The SQL lines have a prompt of a greater than symbol (>) while the command lines have a prompt showing current path. Note that "identified by" is followed by a password enclosed in single quotes.


<pre>sudo mysqli --user=root --password=InitialPassword
<pre>sudo mysqli --user=root --password=InitialPassword
Line 478: Line 569:
FLUSH PRIVILEGES;
FLUSH PRIVILEGES;
exit;</pre>
exit;</pre>
As I type this, MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore it will crash out (with message press Enter to close).


Next, we need to add the mysqli module to our php install, to restart apache, to create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser, and we need to give the standard user (pi) ownership of the database files and the web pages:
As I type this, Cumulus MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore in this situation it will crash out (with message press Enter to close).
 
 
=== Commands to ensure PhpMyAdmin will work ===
 
The following sequence of commands will
* add the mysqli module to our php install,  
*will restart apache,  
*will create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser,  
*will give the standard user (pi) ownership of the database files and the web pages:


<pre>sudo phpenmod mysqli
<pre>sudo phpenmod mysqli
Line 487: Line 586:
sudo  chown -R pi:www-data /var/www/html/</pre>
sudo  chown -R pi:www-data /var/www/html/</pre>


===Viewing web pages on our new web server===


You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi URL e.g. '''http://192.168.1.xy/phpmyadmin''' where ''x'' and ''y'' are digits you look up as mentioned before where FTP of MX distribution was described.  If your Pi has both Ethernet and wireless connection, there will be two different values of ''y'' for you to choose one from.  On first run of PhpMyAdmin, as already mentioned, you will see a PHP MyAdmin log on page where you type username and password we have just set up.
You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi IPv4 address e.g. a URL like  '''http://192.168.1.xyz/phpmyadmin''' where ''xyz'' is 2 or 3 digits you look up as mentioned before where FTP was described.  If your Pi has both Ethernet and wireless connection, there will be two different values of ''xyz'' for you to choose one from.  On first run of PhpMyAdmin, as already mentioned, you will see a '''PHP MyAdmin log-on page''' where you type username and password we have just set up.


===Transferring database tables to your Pi===   
===Transferring database tables to your Pi===   


If you have been using Cumulus before (and have a database) then you can use PhpMyAdmin on your old device to '''export''' out all the '''Cumulus tables as SQL''' in a zip file, FTP that zip file across to your Pi, use PhpMyAdmin to '''import''' that zip file.   
If you have been using Cumulus before (and already have a database) then you can use PhpMyAdmin on your old device to '''export''' out all the '''Cumulus tables as SQL''' in a zip file, FTP that zip file across to your Pi, then use PhpMyAdmin on your Pi to '''import''' that zip file.   


Providing you selected the right options for what SQL you created in your export, the import will contain SQL to create the tables and to insert all the rows into each Cumulus table on your Pi. Please note that there is a limit of around 1000 rows that can be imported in one action, so for your bigger tables, you will only create the table once, but you will do several '''Replace''' row actions (export from old device, then import to Pi) each transferring just one thousand rows, until the whole table is on the Pi.
Providing you selected the right options for what SQL you created in your export, the import will contain SQL to create the tables and to insert all the rows into each Cumulus table on your Pi. Please note that there is a limit of around 1000 rows that can be imported in one action, so for your bigger tables, you will only create the table once, but you will do several '''Replace''' row actions (export from old device, then import to Pi) each transferring just one thousand rows, until the whole table is on the Pi.


You might want to also '''export/import the PhpMyAdmin tables''' with your preferences in a separate zip, although these might need some extra transformations, as they are specific to a particular version of the database server (and the old device version may not match the MariaDB version on your Pi). Some PhpMyAdmin tables do change for different versions of the tool, so that too may make export/import of its tables more complicated.
You might want to also '''export/import the tables in the PhpMyAdmin database''' with your preferences in a separate zip, although these might need some extra transformations, as they are specific to a particular version of the database server (and the old device version may not match the MariaDB version on your Pi). Some PhpMyAdmin tables do change for different versions of the tool, so that too may make export/import of its tables more complicated.


=== Restarting Web Server ===
=== Restarting Web Server ===


After all these installs, we need to restart Apache (so it loads the PHP and MariaDB), by typing <tt>sudo service apache2 restart</tt> or  if we just want the Apache configuration reloaded by typing <tt>sudo systemctl reload apache2</tt>.  Similar commands apply for other web servers.
After all these installs, we need to restart Apache (so it loads the PHP and MariaDB), by typing <tt>sudo service apache2 restart</tt> or  (if we just want the Apache configuration reloaded) by typing <tt>sudo systemctl reload apache2</tt>.  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.
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.
Line 509: Line 609:


For a novice, the easiest way to set up your Pi (as described above) requires (at least temporary) a keyboard and a monitor (can be a TV) to be connected to it. You might also want to connect a mouse. Depending on the Raspberry Pi you bought, and whether you bought a keyboard (or can borrow one from any PC you have), the ease of making these connections will vary. Once your Pi is set up, and you have started MX running, you can disconnect these peripherals, and leave your Pi running.
For a novice, the easiest way to set up your Pi (as described above) requires (at least temporary) a keyboard and a monitor (can be a TV) to be connected to it. You might also want to connect a mouse. Depending on the Raspberry Pi you bought, and whether you bought a keyboard (or can borrow one from any PC you have), the ease of making these connections will vary. Once your Pi is set up, and you have started MX running, you can disconnect these peripherals, and leave your Pi running.
The options described in the rest of this article cover all aspects of using a PC to do actions on your Pi, including how to change some settings on your Pi without ever connecting a keyboard and monitor to the Pi. For a novice, there are lots of opportunities to make errors in the following options, so remember the cricketer who said "If at first you do not succeed, try and try again, if you continue to fail, give up".


=== Remote access ===
=== Remote access ===
Line 517: Line 619:
*and any other actions that are specific to the terminal mode on the other device.
*and any other actions that are specific to the terminal mode on the other device.


====Alternative to SSH====


While SSH gives you access to command lines, and lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, there might be some times when you are operating your Pi in a headless state (without keyboard or monitor) yet you want to explore its graphical user interface. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.
You can use the browser on your PC to connect to the web server created by the MX engine to run the admin interface (all that needs is that the Pi and the PC are both connected to your hub or router, so they are on the same local network):
* to change settings
*or to look at the web pages provided in that interface.
 
Your PC can be used (as well as your Pi) to look at any web pages updated by MX (all that needs is your device to be able to connect to whatever web server runs your web pages).
 
====Ways of using PC to do what can be done on a Pi====
 
On your Pi, there are various applications that you can run with graphical interfaces, these let you achieve what you want by on screen selections, without having to learn what Linux commands to type in. You might wish to use these when you are operating your Pi in a headless state (without keyboard or monitor), so you want to see these graphical interfaces on your PC. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.
 
 
An alternative way to work on your Pi is its its terminal mode. This lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, and can therefore allow you to achieve tasks where a graphical interface fails because of the ownership of the part of the file structure where your action is taking place. The commands you type into a terminal screen on a Pi can also be typed into a terminal screen on your PC, and you will see the same responses. For this to work, you need to switch Secure Shell Home (SSH) on as that is what controls access over a network. This article explains most aspects of SSH in the next few sub-sections.


You might find such an alternative is easier for you, as graphical interfaces let you achieve what you want by on screen selections, without having to learn what Linux commands to type in.


==== What is Secure Shell Home?====
==== What is Secure Shell Home?====


Secure Shell Home (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network. If you have two devices (your Pi and another computer), SSH will allow the two devices to exchange commands and responses between a terminal and a computer.  You may be too young to remember when communication with a computer was often done remotely using a Teletype or similar device acting in terminal mode, just 4 decades ago this would have been a familiar experience to anyone working with computers, now it may seem strange for you. It is possible you have remote connection from home to a computer at your work (although that probably uses a different protocol as the network is likely to be more secured).
Secure Shell Home (SSH) is a cryptographic network protocol for operating network services securely over an unsecured network. If you have two devices (your Pi and another computer), SSH will allow the two devices to exchange commands and responses between a terminal and a computer over the wireless or Ethernet (or mixture) network that connects them.   
 
You may be too young to remember when communication with a computer was often done (remotely) using a Teletype (or similar device) acting in terminal mode. Just 4 decades ago this would have been a familiar experience for anyone working with computers, now it may seem strange for you.  
 
It is possible you have remote connection from home to a computer at your work (although that probably uses a different protocol as the network is likely to be better secured as it passes over the internet).


SSH is switched off by default on a standard Raspberry Pi set up. You can if you have a keyboard and screen attached to your Pi, go into the configuration screen it offers and switch SSH on.
SSH is switched off by default on a standard Raspberry Pi set up.  
The easiest way is using the '''Raspi-config''' tool, either from the main menu (raspberry Pi icon inside a square) or in terminal mode with '''sudo raspi-config''' (choose option 5 = ''Interfacing Options'', look for SSH).  This will enable you to later access your Pi from your PC and might be useful later on. While you are in the configuration tool choose option 1 = ''Change User Password'', and set the password you will use for your SSH session; the default password  is '''raspberry''', but you don't want to let hackers into your Pi, so you will choose something hard to guess.  
 
You can if you have a keyboard and screen attached to your Pi, go into the configuration screen it offers and switch SSH on. The easiest way is using the '''Raspi-config''' tool, either from the main menu (raspberry Pi icon inside a square) or in terminal mode with '''sudo raspi-config''' (choose option 5 = ''Interfacing Options'', look for SSH).  This will enable you to later access your Pi from your PC and might be useful later on. While you are in the configuration tool choose option 1 = ''Change User Password'', and set the password you will use for your SSH session; the default password  is '''raspberry''', but you don't want to let hackers into your Pi, so you will choose something hard to guess.  


The next sub-section describes how you can switch SSH on during the first boot, by creating a file on the micro-SD card before you insert it into your Pi, the file is removed as part of the boot process, so this only works once.
The next sub-section describes how you can switch SSH on during the first boot, by creating a file on the micro-SD card before you insert it into your Pi, the file is removed as part of the boot process, so this only works once.
Line 546: Line 662:
====How to use SSH?====
====How to use SSH?====


If you have a Windows PC, this will allow you to open a '''Command''' prompt, '''Power Shell''', or '''Terminal''' window (the selection you have available depends on certain settings). If you have a Linux or Mac device, open '''Terminal'''. Next, assuming your Pi is running, on whatever other device you have on the same local network, type <tt>ssh pi@raspberrypi</tt> to get access to default user in your Pi. 
If you have a Windows PC, this will allow you to open a '''Command''' prompt, '''Power Shell''', or '''Terminal''' window (the selection you have available depends on certain settings).  


(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 options, so you might find it easier to use. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).
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 <tt>ssh pi@raspberrypi</tt> 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. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).


When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. 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.
When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. 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.
You can use SSH access from your PC:
* when you need to edit a file on your Pi,
*or do a file transfer between Pi and PC or vice versa.
=== Running MX from your PC ===
If you choose to use the simple <tt>sudo mono CumulusMX.exe</tt> 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. 
Hopefully someone will add notes to this article about the running as service option. I have not tried it, so I cannot add such notes.
=== Older information about using a PC and a PI ===
In the Cumulus Support forum, there are articles about a [https://cumulus.hosiene.co.uk/viewtopic.php?p=139779#p139779 stop/start routine], a [https://cumulus.hosiene.co.uk/viewtopic.php?p=141514#p141514 backup routine], and [https://cumulus.hosiene.co.uk/viewtopic.php?p=146028#p146028 how to run MX as a service]. I will let you hunt for and read the relevant topics, as you may find details in more than one place. This article currently avoids describing these to try to keep content simple.  Here is just a list of some alternatives to having to leave your terminal session running:
# Use '''start/stop routine''' (see earlier link), this effectively starts a separate session for MX to run in and leaves the standard terminal session free.
# Run MX as an '''init service''' (see the earlier post in the service link above), be aware that this is a new feature in the new release of MX 3.8.0, again this starts MX outside your terminal session
# Use '''Screen''' software to start up a separate session that you can log off from without MX stopping (see [https://cumulus.hosiene.co.uk/viewtopic.php?p=146203#p146203 how to run using screen]}
#  Run MX as a '''systemd service''' (see the more recent posts in the service link above), be aware that at time of typing this is planned to be incorporated in a future release but the MX developer has no knowledge in this area




Line 588: Line 728:


Should you wish to set up your Pi with several network definitions, please see [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).
Should you wish to set up your Pi with several network definitions, please see [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).
===Downloading MX distribution on PC===
If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* 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 <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* 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 <tt>hostname</tt>) 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!
Click '''QuickConnect''' and you should see the local files in the left frame and your Pi home files in the right frame. The easiest way is to find the folder called '''CumulusMX''' in the distribution on the left and drag it to the correct position in the right hand frame. Then all you need to do is watch the progress until it successfully finishes.
If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).
Sfws
5,838

edits

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