MX on Linux

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 a multitude of devices running Linux.

This document is 'Work In Progress' so content may not be complete or accurate!

It might be sensible if Apple Mac specific information goes onto a new page. 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. Until someone has created a separate page about the Mac in this Wiki, this is closest you can get.

This article focuses on Linux operating system

The Running Cumulus MX on Microsoft Windows page covers those aspects of MX that are specific to Personal Computers running Microsoft's operating system. In the Cumulus support forum, there are many posts from people who are struggling with using Windows PCs, and it seems a lot of them find "installing" and using MX difficult with Microsoft Windows.

This page focuses on aspects of MX that are specific to the Linux operating systems.

The notes here will generally apply to any version of Linux, although the configuration editor described is only on the RPi.

Although it is intended that this page should cover all Linux-based devices, the content here is based on experience of those who have contributed to this page. To be more comprehensive, it needs contributions from users of other devices to be prepared to edit this page.

Perhaps, you my reader, can add sub-sections to this page adding any alternative guidance for other Linux running devices.

How to read this page

This page is deliberately arranged so the key information about installing MONO and MX comes first, and you may not need to read beyond that.

A tiny Linux computer

To install MX on a Linux computer, you obviously need a computer. After this page has covered MX, scroll down, and a long section (should you wish to read it) tells you everything about a tiny,but powerful, computer that is called the Raspberry Pi (RPi), running the Raspberry Pi Operating System, but most of the guidance here will apply to other devices.

Other information on this page

After that comes a section on Linux commands, if you carry on reading.

This page ends with text about what else you can do with your Linux computer. This is not about using word-processors, but about optionally running your own web server and database server.

Checking all packages are up to date

Periodically, and before you add new software, it is worth getting your RPi to check its respositories to see if everything already installed is using latest release.

Note these commands do not update the kernal. You do NOT need to reboot your Linux computer for any package these commands change. (Only a kernal update needs a reboot, and a Kernal update is so complicated it is not described here).

Either type:

sudo apt-get update
sudo apt-get upgrade

or to insert in single line type instead sudo apt-get update && sudo apt-get upgrade.

Installing Mono

Sponsored by Microsoft, Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.

Preparing for Mono installation

Quite often when we try to install, or update, packages on our Pi we will see messages about dependencies, and in some cases error messages saying the installation has failed or been aborted. This is why you are advised to do both apt-get update and apt-get upgrade first.

Before we can install many packages, we need to install certificates and tell our RPi where to download from.

For Mono, these vary depending upon the Raspberry operating system version we have installed, see Mono download instructions for Raspberry Pi. Here are the latest 2 options when this article was updated (if your Mono installation fails, then you selected wrong one):

For Raspberry Operating System 9 (stretch):

sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-raspbianstretch main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update

For Raspberry Operating System 10 (buster):

sudo apt install apt-transport-https dirmngr gnupg ca-certificates
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
echo "deb https://download.mono-project.com/repo/debian stable-raspbianbuster main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
sudo apt update

Installing Mono instruction

With all the pre-requisites correct as in previous steps, you can install mono package by simply typing sudo apt-get install -y mono-complete.

• 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 "install" is the action we want to do
• The -y flag means the installation will happen without us needing to confirm we want it to install the packages identified.
• The "mono-complete" is the package we want.

With latest installs of rPi, you can also use sudo apt install mono-complete -y

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 sudo autoremove.

Now you have what is needed to run any executable related to Cumulus, not just CumulusMX.exe.

Completing Package Installation

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 sudo apt autoremove.

Cumulus MX

Now you have your Linux computer set up, it is ready for MX, so this section is the important one.

Where to install MX?

For simplicity, MX can be installed into standard Pi user's home directory (~/CumulusMX) here, as that simplifies permissions, you don't need super user privileges to write in the home directory. However, instead of using "~/", the following notes will use EXISTING PATH, so the notes are equally valid should you install elsewhere.

The image that Mark Crossley provides has MX pre-installed into /opt/CumulusMX.

You might choose to install it on an external drive which has two significant advantages:

1. there are certain files within MX that are updated very frequently, such constant rewriting can lead to a shorter life for your micro-SD card,
   • by using an external drive for MX, MX files are less likely to be lost, and you keep MX and your operating system on separate drives, so are less likely to wear out your micro-SD card
2. if you accidentally were to corrupt a critical file on your Raspberry Pi, you would need to rebuild the operating system image, and that deletes all existing files on the micro-SD card, including any related to MX, and you don't want to lose your precious Cumulus data

Both the optional "data" directory created by NOOBS, and any external drive that has been mounted, normally appear within "/media/pi" in the file structure so EXISTING PATH might be "/media/pi/mount_name", but the exact path depends on your set-up, and might not be as predicted here.

Downloading and Unzipping MX Distribution

The download and unzip procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:

1. It is recommended, you type sudo mkdir EXISTING PATH/CumulusMX first, so you already have folder ready for MX, but the file can be created by unzipping the distribution into home directory (~).
2. Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
3. To find the link to latest release distribution zip in the Cumulus Wiki, open the Software article in the Current_Release section.
4. Download the MX distribution from the link that appears there, Mark will update it for each release he makes.

If the latest release has bugs (it is impossible for the developer to check all the ways in which versatile MX can be used), you can Download whatever older version of MX you have decided to install from CumulusMX/releases.

1. If you are downloading the distribution 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.
2. When download completes, use the mouse to click on the download file name, this should ask if you want to extract (unzip) it.
3. Ensure the file unzips into your personal home directory "/home/pi", although you could place it elsewhere, this is the easiest place to find (because it can also be represented by "~").

Upgrading to a new release

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 sudo mono CumulusMX.exe instruction has to be issued in new place.

MX Back-up issues

You should ensure that you backup the critical files (Cumulus.ini, strings.ini, all files in data folder, any files in Report folder) on a regular basis to another computer (or to your web site) and not rely on any back-ups that MX does.

Configuration issues

To learn more about configuration, please see MX Administrative Interface and Cumulus.ini articles.

In the earlier MX releases, some settings can be changed in the admin graphical interface (these are labelled read-write), but some (labelled read-only) must be configured by stopping Cumulus and editing the configuration file.

More recent releases simplify the process, all settings can be configured using the interface. So if this is your first use of Cumulus MX (even if you used the legacy Cumulus before), then on first starting the software, you can configure all the settings. Now stop and restart MX to ensure all those settings are picked up.

General Issues when configuring

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 may save you from days of issues:

• The settings available will vary depending on which release of MX you are installing/running
  • You need to work through all the settings web pages in the interface, to ensure that you have made all the settings needed for your set up.
  • Please note that some settings are related (e.g. you need to enable real-time before any real-time actions can be selected; equally you need to enable moon image generation before you can tick the moon upload option; these are just the 2 most common errors)
• For general advice relating to various MX issues, study all the links in that category
• For What to do when I have a problem with MX, follow that link
• An article that needs someone to spend a lot of time improving it is Cumulus MX FAQ, but the article could be useful

• If you were using the original (now leagcy) Cumulus software, please read Migrating_from_Cumulus_1_to_MX, although that is mostly directed at those using MX on the same Windows PC as they used for Cumulus 1, it will help you understand configuration differences.
• If you previously ran MX on a Microsoft Windows PC, and now intend to run MX on your RPi, be aware that the characters terminating each line in any files copied across may need editing (see next sub-section).

Configuration Issues when moving from Windows to Linux

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 to make changes is easiest because it (in many cases) limits the selections to those that are valid.

However, editing the Cumulus.ini file directly might be easier if you 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).

Here are the main points (based on MX being installed in home folder):

• 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 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 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 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 sudo chmod -R ugo+rw /var/www/html for Cumulus MX to successfully copy there.

Keeping existing data and Reports files

If you have used Cumulus before, you will be seeking to keep your existing log files.

To get the entire content of your existing data and Reports folder onto your Pi:

• you could copy them onto the micro-SD card, or a memory stick, (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).

Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, and your files were created by Microsoft Windows, then ideally all your files should be edited so they simply use Line_feed (LF) to terminate all lines. This can be easily done on your RPi by opening each file in an editor like Geany (part of the programming collection in the full RPi OS installation that is designed for computer files. Geany can be set to always save every file with LF' only on every line regards of what was used on any individual line when file was read; plus it can have multiple files open.

If you are editing on another operating system, Notepad++ is an easy to use editor that is designed for computer files. It has some capabilities to do changes to all open 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 a Windows OS on your Raspberry Pi.

If you are a novice and your files contain both CR and LF, the Linux will only use the LF as end of line character, and will treat the CR as an indication the file is not in Linux format. This might give problems if you try to use one of the basic text editors provided with RPi OS, but MX will cope.

using file transfer

On a Microsoft Windows PC, WinSCP is a popular choice for file transfer (FTP and SFTP). It can be done using command lines in a (Powershell, Command, or Terminal) window. Alternatively, it uses a Graphical User Interface, that can support multiple tabs, and background. For full features see here. As it is designed just for Windows, it can appear in right click menus. Another benefit is that it shares some settings with Putty SSH client, if you will use that to link to your RPi.

A common FTP client, available on most devices is FileZilla Client.

First of all you need to configure your FTP client, unless you have done that previously and saved the configuration:

• The quickest way in FileZilla is to fill out the "quick connect boxes".
• 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 hostname -I). 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 hostname) 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!)

Click the button to Connect 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 MX

This section explores the optional parameters, and then covers 2 ways to run MX:

1. as a service and
2. directly with terminal window left open.

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

Beta builds in MX version 3.0.0 had an optional parameter -wsport nnnn 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 Admin Interface. The remaining parameters that are still available are described in subsequent sub-sections.

Parameter for changing Port

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

sudo mono CumulusMX.exe -port 9999

Parameter for adding debugging

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

If there is a problem, then there is a great benefit in actually increasing the level of detail in these logs; and that is done either within the settings (options section of station settings) in admin interface while MX is running, or by adding 1 or 2 parameters when you start MX. Obviously this log file continues to grow, the longer MX is left running, and if debugging is switched on the file will grow in size must faster. Consequently, the default is not to add the extra debugging information and the settings can be used to switch it off again if you do have it switched on. Whether you start it with a parameter or enable it within settings, stopping MX will end the extra debugging, and on restart it will default back to no debugging unless turned on again with parameter or setting.

You can also add CumulusMX.exe -debug (to have full debugging of actions by MX turned on as MX starts), and/or CumulusMX.exe -Logging=1 (for the station to MX transfers to have increased debugging logging).

sudo mono CumulusMX.exe -debug -Logging=1

Since this parameter is applied when you start MX, it applies while MX continues to run. Obviously, it must be applied every time you start MX if you want this increased level of logging to continue every time you restart MX.

The comments in the MX source suggests -debug turns on both debug and data logging (see Station_Settings#Options in admin interface settings), but I believe that is wrong as per example above, there are 2 separate parameters.

Parameter for changing Locale

On Linux and (in particular) OS X, Cumulus MX may not be given the correct locale to use, and you may get the default US locale even if that is not your locale. It will output the local it is using when it starts; if it is not correct, close it down and start it again, this time specifying your locale on the command line, using the -lang parameter . For example, in the UK, on a non-Windows device type:

sudo mono CumulusMX.exe -lang en-GB

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

If you are not sure what value you need to supply for the -lang parameter, there is a list here - http://msdn.microsoft.com/en-gb/library/ee825488%28v=cs.20%29.aspx. You need to supply the code in the first column ("Language Culture Name") in that list.

Note that this does not affect the language used by Cumulus MX (although it may in the future), it affects the decimal separator and the list separator.

Note that you may need to supply your administrator password after typing the 'sudo ...' command line. The system will prompt you for this if it is needed.

Parameter for running as service

Use of this is explained next. The parameter syntax is sudo mono CumulusMX.exe -service

Setting up as a service

If you have installed MX release 3.8.0 or later, you can set up MX to run as a service.

1. There is a task to do just once to configure the service
2. 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
3. As described later there is a choice of editors, but you can use sudo nano cumulusmx.service to edit the service configuration file
4. 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.
5. save file
6. now copy file

sudo cp EXISTING_PATH/CumulusMX/MXutils/linux/cumulusmx.service /etc/systemd/system/

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 sudo systemctl enable cumulusmx 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 sudo systemctl start cumulusmx

Use systemctl status cumulusmx.service in a terminal session to see status of Cumulus service

Running with a terminal session left open

This is alternative to the running as service as described above.

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 Optional_parameters.

The simplest instruction to run Cumulus MX is cd EXISTING PATH/CumulusMX && sudo mono CumulusMX.exe. 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

• optionally disconnect the keyboard,
• switch off monitor or TV attached to your Pi,
• Just ensure you leave Pi on (with that window minimised) so that terminal session continues running.

Use ps -ef | grep -i cumulus | grep -v grep to see if Cumulus is running or not.

The Raspberry Pi micro-computer

The Raspberry Pi computer (RPi) is a small board of electronics. The board can be bought separately to the micro-SD card that it will boot from. There is a choice of operating system (OS) that can be processed by the board. The available OS choices include Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).

On this Wiki page, the focus is on the last OS, Raspberry Pi Operating System, because that is easiest to install, and includes extra features specially designed to make using a RPi easier.

If you want to install a different OS, you may use a micro-SD card that includes Novel Out of Box Software (NOOBS), as that (when your RPi has a wired Ethernet connection to internet) can download and install a variety of OS.

If your micro-SD card does not have a pre-installed OS, and it don't have NOOBS, then please use a search engine to find an operating system thatsuits you, and instructions on how to install it on a micro-SD card.

The article will give you some guidance on:

• Choosing a Pi model to buy
• Setting up a Raspberry Pi,
• 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 MX
• Running MX (these notes apply to any Linux OS, but some hints need consideration even in Windows)

It also covers some included functionality and some optional extras for you RPi.

There are relatively few posts in the Cumuus Support forum from people struggling with setting up the Raspberry Pi, and several posts reporting success with using MX on this small computer.

Linux is better than Windows

It is recognised that some people might be experienced Windows PC users, and perhaps scared of learning Linux; this page may persuade people that actually a Raspberry Pi (RPi) computer can be used instead of their Windows PC for all their tasks. Here are a few facts:

• The Raspberry Pi is a simple computer that is far easier to learn than a complicated machine like a Personal Computer (PC) running Windows.
• There are various operating systems (OS) that you can use on a RPi
  • It can run a small version of the Windows operating system, the same as the one that is pre-installed on certain modern white goods.
  • This page focusses on the simpler Raspberry Pi operating system (based on debian Linux) as it works on a RPi.
    • You don't need to learn much Linux, but this article does cover some commands.
• A RPi is small in size so does not intrude into your home
• A RPi uses much less power than a PC, and so can be left running, while a PC wastes a lot of electricity if left running.
  • The Raspberry Pi is a computer that is better for the environment during manufacture, its single board has just a small number of components, unlike a PC manufactured with lot of components.
• A Windows computer is frequently interrupted by Microsoft software updates, most of which require a reboot. Linux computers don't do automatic updates, software can be upgraded, or replaced, by manual instruction without (except for kernal updates) a reboot.
• A RPi can do word processing, spreadsheets, database tasks, drawing tasks, display images, play sounds and videos, let you use email, play games etc.
• It is simplest to connect keyboard and monitor to the Raspberry Pi so all actions are done directly on it.
  • Another option discussed is using a PC to control a "headless" Raspberry Pi (i.e. one without keyboard and without monitor).
• A RPi is the ideal device to run Cumulus MX, and (if you want) the same RPi can run a database server and/or web server (on which you can run the example web pages provided, or create your own variants)
  • Downloading the MX release distribution, and unzipping the files, is effectively the same on any device.
  • On Linux you need to (simply) manually install one extra component (Mono-complete) to run the executables included in MX, (the equivalent component (.NET) is automatically pre-installed on Windows).
  • Running MX is same on any device (precise command syntax to start it varies, but what MX does when running is largely independent of device)

Image alternative

If you have a spare Raspberry Pi, and a spare micro-SD card, that are not being used, there is an alternative to following the detailed guidance later on this page.

Instead, all you need to do is download one image file onto the micro-SD card before you insert it into your RPi and let it boot. The single download file is available at Software page Current_Release section.

This image includes the "lite" edition of RPi OS, it also includes a mono-complete package, and includes a modified MX distribution, all on that single download.

Choose it if:

• you are never going to use a keyboard nor TV (or other monitor) with your Raspberry Pi,
• and you don't want to use any other software on your RPi.

Read about using it on Raspberry_Pi_Image page:

• If you are new to MX, after booting from image, you will need to use the admin interface to define station type, your choice of units, and some other settings, before MX can start recording data from the connected weather station.
• If you are migrating from another computer, after booting from image, you need to add (using an external memory stick or file transfer from your other device to the RPi), the following:
  • (mandatory) Cumulus.ini,
  • (optional) strings.ini,
  • (mandatory) all files from old data sub-folder,
  • and any (optional) files from old Reports sub-folder.

Setting up RPi manually

You can find, online, instructions (and videos) about setting up a Pi, these describe all the necessary steps that are described below from buying a suitable micro-SD card, through installing the operating system, and adding additional software. If you use a search engine, then you can find a variety of different sets of instructions, including some that are very simple but basic; and others that are a little more complex so they can explain any options!

• The obvious place to look is the manufacturer's web site, the manufacturer actually also publishes the same documentation on their github page.
• If you have brought your Pi from a distributor, their web site (e.g. 'getting started' instructions provided by this distributor) might have simple instructions tailored to their product,
• or you can find the details at many general forum type sites with "how to" advice.

In the sections that follow, each step in buying and installation is covered. It is difficult to decide how much detail to include, a novice, and someone who wants to plug holes in their existing knowledge, have different ideas of exactly what detail is needed.

I did experiment (in an earlier version of this page) with including a Précis, then going into more detail. I found that made navigation harder than relying on the multiple sub-section approach now used.

Anyone who feels able to improve these sections is welcome to do some editing, provided the page remains relevant to both novice and established user wishing to look up these notes.

What to buy

You can buy a kit that includes several of the separate items listed below, or buy the components separately. Generally buying as a kit is cheaper than buying items individually. A typical kit includes the Pi board (with components and interfaces on it), a power supply (with a plug suitable for your mains sockets), a micro-SD card (see later sub-section), some connection leads, and a case (designed for board in kit).

The Raspberry Pi board

The Raspberry PI is just a circuit board. As time passes, new models are released, generally each offers more functionality than earlier models. Some retailers may only have latest model available. However, many retailers will still sell older models.

The information in this section was up to date in January 2020, future developments may make parts of the text here obsolete. Maybe you are a contributor who can edit some sections to bring the facts up to date.

A standard desktop computer (running Microsoft Windows) consumes at least 200 Watts of power (that is when it is idle, it will increase as more peripherals are attached and increase depending on any processing being done) all the time it is switched on.

A Pi Zero W consumes half a Watt when idle, and up to 1.78 W when running tasks or connected to peripherals that take power from RPi.

A Pi model 4 B consumes 2.85 to 80 W depending on whether it is idle or working hard; also consumption is higher if peripherals are being powered from the RPi.

When MX interrogates some weather station types, only the current values are available; in this case if you stop MX, you lose any readings during the time MX is not running. For these staion types, normally MX must run all the time (24 hours a day, 7 days a week; i.e. 24/7).

MX may be able to get historic (archive) readings from some weather station types, but these will only be available at an interval such as every half an hour (or every 10 minutes), so you still miss any readings from inbetween times. For these station types, it is an advantage to run 24/7, but not essential.

When MX is actually running, the frequency at which it obtains readings depends on the weather station type, but it is typically either every half-minute to every couple of minutes. Consequently, if MX is run all the time, derived values like highest, lowest, average, and so on, will be more accurately calculated if MX is left running, than when it is sometimes stopped.

Although the Pi is not the only small computer model available, than can safely be left unattended to run all the time, it is probably the most popular and the easiest one to use. Its low power consumption implies it will not wreck the planet by running all the time, in the way a larger computer would! It is obviously much cheaper to buy and much cheaper to run.

If you do a search on the support forum, you will find a lot of different opinions about which model you should buy, but in the end you decide! The following sub-sections contain just suggestions on how to decide, there is no intention to force any single decision.

Which Raspberry Pi to buy

If you want to own 2 computers, and will run your Pi headless by sending commands from your other computer, see Raspberry Pi Image article instead of reading any further here.

The following sub-sections are worth reading, if you want to buy a Raspberry Pi as a small computer. As a novice, you are likely to connect a screen and keyboard. You can use such a RPi for those word processing tasks you need to do, for maintaining a spreadsheet on your expenditure against budget, for looking at photos from your mobile phone, for a database that lists your CD or book collection, and even for playing games.

First make a list of what you need

• It is possible to buy a RPi model sold with the component board inside a keyboard, this means all you need to add to make it a usable computer is to add a TV or other monitor with HDMI input, this might be ideal if this is to be your only computer.
  • At time of writing only the latest RPi board is sold integrated within the keyboard, so subsequent bullet points are irrelevant.
• Do you want to buy a RPi board on its own, then add a box to hold it? You can buy a mouse and key board (or use existing hardware), so that you can use your Raspberry Pi, with a TV (or computer monitor), as a computer for tasks like browsing the web and word processing, not just for CumulusMX?
  • If so, a model with multiple USB sockets is advisable (like 3 B+ or 4)
  • Multiple USB sockets also allow you to use a memory stick, or external drive, to run MX on, eliminating wear on the micro-SD card that contains the kernal and other boot up software (MX is constantly creating or updating many files (mostly in /data and /web sub-folders)
  • Multiple USB sockets are also useful if you want to be able to plug in a USB stick and then remove it, (perhaps for transferring files between devices, e.g. Cumulus configuration and data folder files; this saves using slow file transfer, or removing the micro-SD disc)
• Do you want a wired connection to your hub or router?
  • Maybe you are going to update external sites, a wired connection may provide a faster and more dependable communication than a wireless link
  • If so, a model including an Ethernet socket is advisable (like 3 B+ or 4)
  • You can add a USB hub and Ethernet dongle to model Zero, but by the time you have done so would have been better to start with a 3 B+ or 4)
  • Remember that if you are operating the RPi in headless mode, a wired or wireless connection to your LAN is needed for your other device to communicate with the RPi
• Will your MX need to update a database, feed data to a web site, upload to external sites, or control other devices?
  • If so, a model ZeroW will have to do each task in turn, and you will see some delay in information updates, plus you will need to set a larger time interval between updates.
  • If so, a model 3 B+ (or 4) will be noticeably faster, and support all options in MX, and can update external sites more frequently
• What interface does your weather station use?
  • If your station communicates to MX via wireless, then you choose a model that supports wireless at the right frequency, all models support basic wireless
  • If your station communicates via Ethernet, then either a wired, or wireless, connection is possible between router/hub and Pi as the station will be plugged into your hub or router
  • If your station communicates to MX via USB, then tou might prefer to buy the model 3 B+ with 4 USB sockets, so you have spare USB ports without buying a hub
  • If your station uses another communication port (such as serial interface), then you need the additional components that support that interface

Now research how the various models relate to your needs

You can look up online what features are included in the various Pi models, and how they differ in power consumption, and cost. But your decision also needs to consider what you need as discussed in last sub-section.

Here, I will compare just 2 (Pi Zero W and 3 B+) for simplicity. Your research above might lead you to choose an older or newer model, and models available may change, so the folowing comparison is just an example written based on what was avaialble in January 2020.

The model Zero W is appealing as it has very low power consumption, it is perfectly adequate for running MX (but has limited speed, it runs the various threads MX uses sequentially) especially if you only use standard MX functionality and don't ask MX to do all the optional extras, and has limited interfaces for wired peripherals.

The model 3 B+ is appealing as it has medium power consumption, but can cope better with the multiple threads that MX starts, and has more physical interfaces built in, such as 4 USB 2.0 ports (useful if you want to connect a weather station using USB, connect a memory stick, and connect a keyboard).

While both models support WiFi and Bluetooth, the latter model also allows a wired Ethernet connection, and that may be useful if that is how you connect to your weather station (an Ethernet connection is also advisable if your WiFi connection is not dependable where you choose to install your RPi).

Having an Ethernet connection, as explained later, makes it possible to easily install any Operating System on your Raspberry Pi on first boot. Without that Ethernet connection, you can only install the operating system already on the micro-sd card (that might be obsolete).

• Raspberry Pi Zero W
  • Pi Zero W has WiFi, one micro USB port and an HDMI output. Because it has WiFi, it is good for headless running, and this leaves the micro USB port free to connect a USB weather station.
  • If you need more physical connections than that
  • Installing onto a faster Pi might speed parts of the installation process, but for actual ‘production’ running this slower, and simpler, Pi will be perfectly adequate.
  • It could run a web server, but that might really slow it down.
  • If you run this headless, all updates are done remotely, for example using an SSH terminal program like PuTTY and a file transfer program like FileZilla on your PC.

• Raspberry Pi 3 B+ (or 4 B; considerations are very similar)
  • The faster speed of this Pi although NOT necessary for running Cumulus MX, will cope better if you are asking MX to do lots of processing (e.g. updating database tables or external sites as well as standard processing).
  • Pi 3 B+ has a socket for an external power supply, Ethernet socket (supports wired link); a HDMI socket for audio/video to TV, or computer monitor; a standard jack audio socket for external headphone, or speaker; 4 standard USB type 2 sockets for weather station, mouse, keyboard, USB stick, or other storage device; plus other connections (e.g. camera).
  • This might be better if you also want to run a web server, and if you want to do other tasks (e.g. word processing - Libre Office is installed as standard on a Pi) on the same Pi.
  • Also consider this model if it is to be used on a remote site so when you visit it is useful to be able to plug in other peripherals, and to spend as little time on updating as possible.

Other models are available, but you need to check their specification against your needs. For example, the current model 4 B has more capabilities, but may be less appealing as it also consumes more power.

A micro-SD card

You will need a micro-SD card (preferably class 10, the class number indicates the relative speed of read/write compared to original design, so this class is 10 times faster).

1. A Pi will work with both a class 4 (only 4 times faster), and a class 10, micro-SD card.
2. Just for the standard RPi OS (with GUI) install you need a card with a minimum of 8 GB.
3. Given we are going to add Mono and Cumulus MX to the card, I advise you buy a card with at least 16 GB (the default operating system installation takes up almost half of that),
   • but you might prefer to buy a 32 GB or 64 GB (or add an external USB drive or USB memory stick) if you intend to keep a lot of data on the Pi.

I won't mention manufacturer names here, but one well known brand (that uses descriptions like extreme) is the market leader, and does have greater reliability than cheaper cards from other manufacturers.

Setting up a Pi is simpler if you buy a micro-SD card that is:

• either pre-installed with NOOBS (Novel Out of Box Software),
• or pre-installed with the latest Raspberry Pi operating system (check you won't get an obsolete OS).

NOOBS makes it easy to install (by default) Raspberry Pi operating system, as if you insert such a micro-SD card into a new Raspberry Pi computer, when you power up the Pi, the operating system will be installed during that first boot.

If you have a Raspberry Pi model with an Ethernet connection, and you connect your Pi to your hub/router before you first switch it on, then at that first boot, NOOBS will offer you a choice of latest downloads available for several operating systems, with Raspberry Pi as first choice.

Various suppliers offer cards of 16 to 64 GB with NOOBS pre-installed ready for use in a Pi (I bought from a firm in Haverhill, Suffolk, UK).

My advice is to buy your micro-SD card from a firm that specialises in selling Raspberry Pi computers and accessories. That should ensure you buy a card with the latest version of NOOBS (or Raspberry Pi Operating System).

Having pre-installed software on the card will make your life simpler than buying a blank micro-SD card and having to down load and add the operating system yourself. But if you are technically skilled, you may prefer starting with a blank card, creating the necessary partitions, some in Ext4 that suits Linux, and doing all the downloads and installations yourself.

If you want to be able to use the micro-SD card in other devices (like your PC), you may need to also buy an adapter which allows the micro-SD card to be plugged into a standard SD socket. This may be included if you buy a micro-SD card not sold specifically for the Pi, or may be available with the Pi micro-SD under a special offer for buying two items together.

Finally, you may wish to buy a second micro-SD unit as a spare. Providing you have a suitable holder, and sufficient capacity, the RPi GUI even has an option that allows you to produce a back-up of the internal micro-SD card with all the partitions (e.g. recovery, system, user).

A case to protect the board

You may want to buy a case, that will protect your Pi from accidental damage. A case specifically designed for your Pi model will have cut-outs in the right place for each interface connection, and will have sufficient ventilation for the electrical components to not over-heat. Some designs have additional holes for securing peripherals.

A power supply

Unless you already have a portable unit that can output power to a micro USB connector (USB type C), it is likely you will want to power your RPi off the mains electricity where you install your RPi.

You may need to buy a power supply.

• This could be an official Raspberry Pi power supply. That will have a suitable plug for your nation, that plug clips onto the transformer (that will reduce the voltage and rectify it to direct current), an inbuilt leads to a USB C plug (that can connect to your RPi).
• Alternatively, other power supply units that have a (micro) USB C connector will often suffice, as the power consumption of a Pi (whichever model) is fairly small.
  • Remember, the power consumption varies depending on model, and on how many tasks are running concurrently on the RPi, and if the RPi has to power additional peripherals.
  • As it will be powered on 24/7, a low power consumption ‘switched mode’ type is preferred – i.e. one that does not become warm when plugged in with nothing attached (not that you should be disconnecting your RPi from its power source, you should do a tidy shutdown first)
  • You may have a suitable power supply unit left over from an earlier mobile phone.

Connection leads used with a RPi

You may need to buy connection leads:

• You may need a HDMI lead to connect your PI to your TV or a spare computer monitor.
• You may need a USB lead ([1]) to connect to your weather station, your station probably has a USB A end connection (the Pi model Zero requires a USB C end, the Pi model 3 requires a standard USB A end).
• If your weather station connects by Ethernet, you will need one lead to connect the station to the router and possibly another to connect the hub or router to the Pi.

USB peripherals

• If you do choose a model 3 (or later), consider whether you want to buy a USB mouse and USB keyboard to use with your RPi.
• Next consider if you want to buy any external disc or stick storage. You might use this for running MX on (MX does lots of inputs and outputs, creating files particularly in "/data" and "/web" sub-folders) to save wear on internal micro-SD card. You might want to connect external storage simply to do regular back-ups (file transfer to another computer over LAN, or to the cloud, is a slow alternative).

The Raspberry Pi Operating System

The Raspberry Pi Operating System comes in both full and lite variants, and these will be explained here:

• Full edition supports a Graphical User Interface (GUI), as well as a Terminal interface
  • A graphical interface means you can attach a keyboard and TV (or other monitor), plus optionally a mouse. With these you can have a "Windows" like experience, where you select an icon (on desktop or in task bar), which brings up a menu that you scroll through and drill down until you have selected option required. Many people find this easy to use, and a novice using the GUI does not need to learn all the different Linux syntax.
  • A terminal interface, resembles the old teletype experience (if you are old enough to have met those machines) lets you type in commands, back space is treated as a control character (it does not remove the previous character, just cancels it out). When you press ENTER, the system types back a response. This gives more flexibility, as you can issue instructions that are not present in the GUI menu dropdown. One example is a chain of commands, another is being able to specify different parameters to a command. However, you do need to develop a good knowledge of Linux commands to achieve progress using a terminal interface, and that can be difficult for a novice, but much qyuicker than a GUI for someone who has used Linux before.
• The lite edition of the OS, excludes the GUI, and is normally installed for a RPi that depends on a separate device (such as a Windows PC) to send all the commands via terminal sessions over a Local Area Network (wired or wireless), so the RPi does not have a keyboard, mouse, nor monitor attached. All the comments above for terminal mode still apply, but you also need some understanding of Secure Shell Protocol (SSH) which is the way any remote terminal session connects to the RPi. The lite edition is used in the single download file available at Software page Current_Release section.

Is the operating system obsolete or up to date?

It is important that your Raspberry Pi (or other device) has the latest operating system version installed. If the Operating System installed is an obsolete one, then each package it includes (e.g. Libre Office), and each package you add (e.g. Mono or PHP), will also be obsolete versions. In the worst case scenario, any attempt to install a package might fail giving an error message that the relevant Raspberry Pi repository is archived.

If you have a micro-SD card pre-installed with NOOBS, as described above, the first boot will install the operating system. It is the version of NOOBS that is included on the micro-SD card that determines which Raspberry Pi Operating System version it offers to set up.

Here are the names of Linux operating systems as at mid-2020:

• Wheezy (7) released in 2013
• Jessie (8) dating from 2015
• Stretch (9) released in 2017 (up to this called Raspbian Operating System)
• Buster (10) available from 2019 (the first to be called Raspberry Pi Operating System)
• Bullseye (11) under test in 2020, and expected to become available sometime in 2021

Be aware that many NOOBS pre-loaded and pre-formatted cards include an obsolete version of NOOBS.

• You may find your card installs the obsolete Raspbian Jessie (version 8 of Debian from 2015),
• a few install the old Raspbian Stretch (Version 9 of Debian, dating from 2017),
• a good supplier sells a card that installs latest Raspberry Operating System Buster (Version 10 of Debian, released in 2019).

How to add Raspberry Operating System to a card yourself

You can boot up a RPi:

• if it has NOOBS pre-installed, at first boot the NOOBS will load,and then you choose the OS to install from options listed
  • more options will be listed if your RPi has wired ethernet connection to internet and can find various available OS as well as the full and lite versions of RPi OS
  • without wired internet, you might only see two options; the full, and lite, versions of Raspberry Pi OS
• A micro-SD card where NOOBS is used to install the RPi OS, will have multiple partitions created
  • the boot partition will ensure RPi OS is loaded in future, together with settings
  • a recovery partition is created, this allows you to return to NOOBS and do a clean install
  • partitions are created for different parts of the Linux file structure
  • optionally a partition can be inserted in any free space and this final partition by default is mounted as "data" under "media" in the Linux file structure
• if you press shift key while your RPi is booting from an operating system, it will load from the recovery partition, and that might offer NOOBS options as at first boot
• if the RPi has Raspberry Pi OS already installed, a normal boot will load up as defined for a normal boot
• there are Linux commands to change the partitions on any storage attached to RPi (including the micro-SD card)
  • as an alternative gparted provides a GUI way to edit partitions (as a super-user), you will need to use apt-get to install gparted.

If you cannot boot up your RPi (perhaps you have a blank micro-SD card)

1. Decide whether you want
   • the full version of the operating system that supports a graphical user interface (choose this if you want to connect a TV or other monitor to your Raspberry Pi),
   • or the lite version of the operating system that only supports SSH or terminal mode (choose this if you will operate headless - explained at end of this article)
2. Download, on another device (like a PC or tablet) the latest version of the Raspberry Pi operating system you have selected from https://www.raspberrypi.org/downloads.
   • the latest Raspberry Operating System is version Buster at time of typing
   • That Raspberry Pi download page has full instructions.
   • However, the supplier who sold your RPi may also have guidance, e.g. those at this supplier's tutorial guide
   • Some people may prefer to look in the Cumulus support forum, e.g. those in Cumulus support forum.
3. To save you looking any of those up, this summarises what you need to do.

• You download the O.S as an imager file onto say your pc,

1. Using imager software (such as belenaEtcher) you select that download image, and then you select write to save it onto the micro-SD card (don't forget this overwrites anything already on the card).
   • This should work without a need to format the card first, (but if you do need to format it, do so using a SD card formatter downloaded from https://www.sdcard.org/downloads/formatter_4/index.html, not for example Windows format tool).
2. After this image has been stored it will have created two (or three) partitions on the micro-SD card (one the boot partition is a FAT partition that can be accessed by Windows (so you can edit files in this partition), the larger Linux EXT4 partition is invisible to Windows, the optional third partition is also formatted as Linux EXT4 and uses up most of any space left on a larger micro-SD card and this final partition by default is mounted as "data" under "media" in the Linux file structure).

Setting up Wireless Network

There is a way to set this by creating a file in the partition that Windows can see, if you are preparing your micro-SD card on a PC before moving the card to your RPi. See the Raspberry_Pi_Image page.

How this is set up on your RPi (see instructions here for RPi OS), depends on the 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 may not prompt you
  • in this case, with RPi OS, you need to use the terminal mode configuration tool (see next sub-section) sudo raspi-config (select 1=configure system settings, then select, then S1=Wireless LAN)
  • or you might need to click on an icon with two red crosses.

If you have had to enter wireless details into a mobile phone, you will realise what is needed:

• Most wireless networks will use Wi-Fi Protected Access (WPA) or (from 2006) Wi-Fi Protected Access II (WPA2) protocols, so WPA-PSK setting here is correct for you.
  • Some hubs or routers or wi-fi extenders may create multiple wireless networks, and there are two possible frequencies for these.
  • 2.4 GHz frequency group contains 14 channels, the 802.11 Wi-Fi standards specify a bandwidth of 22 MHz, and most channels are 5 MHz apart (but there is a 12 MHz gap between channels 13 and 14). You may get interference from a microwave oven as these use a channel in this group. The early RPi models only support this frequency group.
  • 5.8 GHz (sometimes abbreviated to 5 GHz) frequency group provides additional bandwidth so 802.11a & n say it carries 23 non-overlapping channels, and being at a higher frequency gives a shorter range than 2.4 GHz. There is less interference as fewer devices (including newer RPi) can afford to use the equipment that can transmit/receive at these higher frequencies.
• 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. Your mobile phone probably displays the SSID under any wireless icon, when it is connected to your wireless network
  • 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).
  • Note that your Pi is only able to use these protocols.
• Note on the Raspberry Pi 3B+ and Raspberry Pi 4B, which use channels in 5.8 GHz group, there is also a Wi-Fi network country which might be set by default, or might need to be set using GUI configuration tool Localisation tab.
  • 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

There are various other configurations you need to do on your PI. 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 sudo raspi-config in Terminal where more options are available.

Mandatory configurations

Within either 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.

The default network (host) name for your Pi is raspberrypi, that will cause a conflict if you have more than one RPi!

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 sudo nano /etc/hostname.

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).

Recommended configurations

The default locale for a Pi is normally en_GB.UTF-8, as they are designed by a company based in UK. Within the configuration option, you can add additional locales (in most cases there is a UTF-8 option which is preferred and at least one other encoding), there are also a number of special alternative locales, but I am not going to explain all the options, look it up if the default locale is not acceptable.

• 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 also 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!
• To change the locale, enter Localisation Options within the configurator provided in RPi O S in terminal mode.

In the same option area, there are some more options:

1. 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, and you want rollover at 10am BST, not 10am UTC.
2. 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

To leave configuration

Select ‘Finish’.

A very quick introduction to Linux

This article is not the place to teach you Linux, you can find books and on-line articles for yourself, but I list here enough for you to understand the instructions used elsewhere in this article.

If you have a Raspberry Pi with a monitor attached, you will see a raspberry icon that you can click to get Graphical User Interface access to many features, including shutdown options.

You might find bash-shell-command-cheat-sheet useful if you are wanting to learn some useful commands to enter in terminal mode, but there are hundreds of other Linux command guides available online.

su and sudo

There is a command su 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 sudo su, 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.

You might use a "sudo" prefix if you need to access a part of the file structure that your user does not have any access to, or where the standard user does not have write (or execute) access.

There are also some commands (like displaying mounted storage) that are not available to a standard user. Here are 3 system commands that in terminal mode will only ever work with this prefix (although if you have installed the version of the Raspberry Pi Operating System that supports a graphical user interface you can also select these actions from a menu):

• 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 poweroff = makes pi do a tidy shutdown and turn off its power; used when you will not be using your Pi for a while
• sudo reboot (or "sudo reboot -verbose" for diagnostic output during shutdown and reboot) = makes your Pi close down and then reboot; used when you change settings, and after you install new software, to ensure Pi starts with all applications running using the latest settings and latest already installed software

~ and /

The tilde symbol ~ denotes the home directory for the current user. Sub-directories within the current user's folder can be identified by ~/documents or similar notation.

To reference a folder in root or any other area, the prefix is always /.

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 dir for just names or ls for details.

external storage

Generally, if you attach USB storage (a disc or a stick), Linux OS distributions will detect any existing partitions (yes a technical term) and allow you to read files stored in them. This applies whether the partition is formatted for Linux or for Microsoft Windows.

However, you may have a brand new, unformatted, drive, or you may want to delete, or add partitions, or to format them as Linux partitions (as these make the input/output significantly more efficient).

You can install software that uses a GUI to make this easy, e.g. gparted partition editor.

Alternatively, you can use a terminal session, and lots of commands:

1. connect your external storage
2. type su to gain administrative access
3. enter your RPi password
4. type fdisk -l (this is only available to root user) to see names for all storage your Linux computer can see
5. an external drive will be named something like /dev/sd'a although that "a" might be "b" or a subsequent letter in alphabet depending on what has already been assigned
6. if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
7. if your drive has partitions, then you will see further entries like /dev/sda1 and /dev/sda2.
8. type df to see whether your drive is currently mounted (being used by computer system)
9. 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"!) umount /dev/sda, obviously replace the "a" by the appropriate letter seen in the earlier command
10. if the drive does not have a partition, create one using fdisk /dev/sda, 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 p to make this the primary partition on this drive
    • type 1 to make this the first partition
    • accept default offered for first cylinder
    • accept default offered for last cylinder, if this is only partition, as that ensures the whole disk (apart from partition table) is available for your data
    • for simplicity, this guidance will not cover the possibility of multiple partitions
    • type t to say you are specifying the way you want this partition to be specified in partition table
    • optionally type L to see what file system types are available for the partition table
    • to select a "Linux" partition, type 83
    • type w to create the partition you have now specified for Linux.
11. 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
12. To format this partition for Linux, we specify "ext4" as the way to format it using mkfs.ext4 /dev/sda1, again replacing the "a" as required.
13. we need to create a folder within
    • "/media" for Linux in general
    • "/media/pi" for Raspberry PI OS
14. 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
15. To mount our partition, we type mount /dev/sda1 /media/pi/my_short_name, 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.
16. To (optionally) get our partition mounted at boot, we can use an editor (see later) to change the boot instructions, by typing nano /etx/fstab
    • 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.
    • exit nano by holding control key and pressing "x" key.

folder commands

To make a new folder in the current directory, type sudo mkdir folder_name.

To remove a directory type in a particular path, type sudo rmdir /path/directory. 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, 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 cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive

To create a logical pointer to a folder or file elsewhere, within a folder that does not have that folder/file, ln -s /path/elsewhere path/pointer_location. 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 rm filename will remove a file even if it is write protected, for nano you need to change the file permissions with sudo chmod -R ugo+rw ~/CumulusMX for modify access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

• 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
  • 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 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 (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
• + = add permission
• - = remove permission
• letters indicating what permission is being changed
  • r = read [4]
  • w = write [2]
  • x = execute [1]

Note that as an alternative shorter syntax you can use numbers e.g. 666 is equivalent to ugo+rw. The first digit in the number relates to u, the second to g and the last to o. The values in [] brackets in list of permissions above are added to derive each digit. So if you are reading the Cumulus support forum and you see a reference to permissions which includes a string of 3 digits, now you can understand what is meant.

editing files

• Do remember that file names are case sensitive.
• If you use the wrong case in a path/file name, it will be treated as a different "new" file.
• If a file editor does not display content you were expecting, 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,

• if you have a mouse and click on a file, you should see "text editor" listed, that loads Mousepad which has a menubar at the top of its "Windows" like interface.
• in terminal mode nano is a text editor that by default lists the actions available making it easier for a novice to use.
• in both the GUI and terminal mode, Geary is a programmer's editor with lots of useful funtionality

All editors 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 irrespective of ownership, 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.

nano

The full syntax is sudo nano -B Path_file_name 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 sudo nano /var/www/html/index.php.

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:

• First is ^O which is used to save the file whilst staying in the editor, to do this press the control key down and type O. Next it shows the current file name, if you press Enter then that file will be overwritten.
  • it allows you to type over the file name shown. If you choose to save as another file, you will be asked if the new name is correct (type Y to continue saving).
• 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 sudo nano /etc/nanorc as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options.

Geany

This uses a GUI, you can set preferences and do all other actions using either menu selections (use mouse or keyboard) or control sequences (on keyboard). Once it knows what type of programming language, it can colour up the code; it can show you how many times variable identifiers are used; it can match opening and closing quotes, tags, and brackets; and it can ensure encoding and line terminators are correct.

Line-numbering is an option, so it can be used to edit MX log files, and (as BOM is an encoding option) you can be sure it won't add unwanted encoding.

removing an unwanted file

You can remove a file with various commands, including sudo rm filename.

install

This is used for installing packages, you will often see it used with a parameter -y; as without that parameter you have to type Y to continue at each step of an install.

It is important to mention here that the version of packages installed using apt-get may well be obsolete, this install is finding versions from a Raspberian repository, more recent versions may be available from the providers of each package.

To keep this guidance simple, it says accept the Operating System that is installed by NOOBS, even if it is not the latest available from the Raspberian web site, it says accept the versions of Mono, Apache, PHP, MariaDB, and others, that are found at the time you issue the install command.

The update and upgrade command that appears in multiple places in this article is still only finding the versions available in the repository, and is included just in case the repository is being updated after any install finishes.

If you have more skill than the level of the person at which this guidance is aimed at, then you should know how to install the latest version from the appropriate web sites. However, most download pages will recognise if they are accessed from a computer running Linux, and will give you guidance on how you ensure latest version is installed. The optional "phpMyAdmin" installation described later describes a way to install the latest version, as the version available in Raspberry respository is not compatible with the default PHP version in that respository!

Miscellaneous

I have created a section here, in case anyone wants to add any more instructions. Please feel free to rename it, or indeed add any clarification anywhere in this article.

Meanwhile, look at either this web page or this one for more commands.

Optional actions

An alternative way to load Cumulus MX onto a Raspberry Pi is by using docker (a package installation), it may not be kept up to date but there is such a package at rpi-cumulusmx and a very old one at CumulusMX-Docker.

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.

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.

Standard action before adding any extra packages

• We run sudo apt update && sudo apt upgrade -y 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.

This action is not repeated below, but potentially applies to all options below.

Databases built into Cumulus MX

You do not need to know what is in these databases to use MX.

Cumulus MX includes two SQLite databases;

1. 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!
2. The second database is the Weather Diary documented here added by Mark Crossley. Also see in the support forum for a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.
   • The Admin Interface provides a page to view, or edit, a single date in the weather diary. You can install another tool that edits SQLite databases if you want (see next section).

Editing the Weather Diary

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 sudo apt install phpliteadmin. 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;

• when a successful insert or update happens, a confirmation message is returned
• when it fails to store an update, there is no error either on the editing screen or in the MXDiags file.

The admin interface has a calendar type interface to pick the entry you want to insert or update; this is probably quickest for any edits in current month. The phpliteadmin graphical interface will list the whole database table and let you edit (or delete) any row, you can also insert (to create a new row), or import/export (using SQL), or copy the whole database. Note that sqlite databases use sequential file structure and so for updates rows are physically identifed by row number (order of creation), not by the primary key that SQL uses.

I can use phpliteadmin, or the admin interface editor, for making changes to my Weather Diary database now. Both can be accessed from a browser on any of my devices.

Adding a web server and a database server

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)

I will mention 3 possible web servers:

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

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 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 sudo apt install php -y, 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 php -m.
• 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 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. 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 php -v 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 wish to create a index.php web page at /var/www/html which is the web server root for browsing, or of course you may wish to copy or FTP here all your existing web pages. To view a php web page, go into a browser and type in a url with the same IPv4 address as you use for the admin interface, omit the port (:8998) and instead type in your web page name (e.g. //192.168.1.xy/index.php, where you need to determine digits that replace xy).

Finding your PHP configuration file

For sake of simplicity in this article, from now on I will assume the web server you installed is "apache2", change that segment (in the paths quoted below here), if you installed a different web server.

The web server main php.ini is found at /etc/php/7.n/apache2/php.ini (where 'n' depends on your Raspberry OS version and therefore which PHP version was installed, that was found out in last sub-section).

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 php - f <file_name>. 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 /home/pi/CumulusMX/MXutils/autoEOD.sh will run a script "autoEOD.sh" you have added to the "MXutils" folder. In that script, you put something like (assuming you have added a folder 'batch' with a subfolder 'log'):

#!/bin/sh
# This MX batch command file is initiated automatically by Cumulus MX software during last stage of processing the end of a meteorological day
echo "It stores feedback in log file CumulusMXDailyBatch (file name ends with day of month)"
sudo php -f the_path_and_filename_goes_here.php > /home/pi/CumulusMX/batch/log/DailyBatch_Day$(date +%d).log

Install Maria database

MySQL database software is controlled by Oracle and not made available for inclusion in Raspberry Pi repository.

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 sudo apt install mariadb-server php-mysql -y.

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 sudo mysql_secure_installation. That brings up a screen:

1. where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
2. next type Y to signify we are going to set a new password for root,
3. next type in a new password that you will not forget,
4. next as explained on the screen we are going to say whether users must select a user name as well as a password, type Y to Remove anonymous users
5. next we have to decide whether we will only be logging into the database on our Pi (using Localhost) or we might be logging in remotely; type Y or N respectively, but if you choose N remember someone other than you might guess there is a root user and might guess the password you set,
6. next we have another option of whether to retain or delete a test database, answer N or Y respectively, I would keep the test database for now as you can play with it and then remove it later,
7. finally you type in another Y as that will Reload the privilege tables and ensure all is set up for your access to the database later.

The message, when the process successfully completes, is "Thanks for using MariDB".

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.

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.

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).

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)

1. Start the install with sudo apt install phpmyadmin -y.
2. The PhpMyAdmin installer will ask some questions.
3. Use your tab key to select <Yes> when it asks whether you want to configure with dbconfig-common.
4. The version of phpmyadmin in the repository is not compatible with PHP7.2 and above, so follow the instructions at https://devanswers.co/manually-upgrade-phpmyadmin/ to upgrade it to latest phpmyadmin (you might substitute "english" for "all-languages" if you only need the one language).

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 sudo apt install adminer (I leave you to work out the commands needed after that).

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 (here I choose "admin") 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 database name (here I choose "cumulus" for the data base name), user name (here I choose "weather" for the user name), and password, must all match those set in MX using the MySQL_settings in the admin interface. You could of course use PhpMyAdmin (or AdMiner) to create additional user names, and to create the database, but I assume all is done in the following bit of SQL. Remember, the Windows operating system is not case sensitive, but all Linux based operating systems are case sensitive (so whatever pattern of capitals and lowercase you choose must be used every time. Also all names must start with a letter, can contain only letters or digits (no punctuation), and must not be a reserved word ("password" is a reserved word, so you cannot use that for a password, nor for a column name).

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. After you press "Enter" key you will get a response saying "OK" if you have remembered the semi-colon. You can actually use "\G" or "\g" instead of a semi-colon, but here we will keep it simple and stick to semi-colon.

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.

sudo mysql --user=root --password=InitialPassword
create user admin@localhost identified by 'PhpMyAdminPassword';
create user weather@localhost identified by 'MXPassword';
grant all privileges on *.* to admin@localhost;
grant all privileges on *.* to weather@localhost;
FLUSH PRIVILEGES;
create database cumulus;
exit;

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:

sudo phpenmod mysqli
sudo service apache2 restart
sudo ln -s /usr/share/phpmyadmin /var/www/html/phpmyadmin
sudo  chown -R pi:www-data /var/www/html/

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 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.

Populating your database tables on your Pi

Cumulus MX has functionality to update database tables at one of 3 intervals:

1. real-time
2. standard interval
3. end of day

The database tables can use the column names in the schemas pre-defined by Cumulus MX or in a custom schema (where you specify the column names). The settings are all in MX_Administrative_Interface#MySQL_settings, so read that section to find out more.

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 cd CumulusMX && sudo mono ExportMySQL.exe monthly to run the executable. The first parameter is "monthly" even if the table has a different name.

1. 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.
2. There is an optional second parameter that specifies the log file name to read.
   • if the second parameter is not specified, this executable will look at every log file (in "data" folder and with file name that starts with month, then has "log.txt"),
3. for each line in the log file the executable will try to insert a row in the database table
   • 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 cd CumulusMX && sudo mono ExportMySQL.exe dayfile.

There is no way to use this executable for insert of past rows into the real-time table.

If you have been running Cumulus on another device previously and already have database tables, the next section explains how you can create SQL to export your old database and use that SQL to populate the new table.

Transferring database tables to your Pi

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. You may prefer to use "ExportMySQL.exe" as described in previous section to recreate your bigger tables from the Cumulus log files.

You might want to also export/import the tables in the PhpMyAdmin database (as they contain your preferences for each of your tables) 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 database server 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

After all these installs, we need to restart Apache (so it loads the PHP and MariaDB), by typing sudo service apache2 restart or (if we just want the Apache configuration reloaded) by typing sudo systemctl reload apache2. 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.

Operating your Raspberry Pi in headless mode

The terminology "headless" means using another device to send commands to a Pi via a wired or wireless network, instead of connecting a keyboard and monitor (or TV) directly to the Pi so you make all selections directly on it.

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

There are various different ways that another device can access the Pi over networks. The most popular lets a Terminal mode on your other device connect to your Raspberry Pi using Secure Shell Home, and the commands you type in on your other device are just the same ones you would type directly into the Raspberry Pi terminal mode. The responses you get are also the same. What is likely to be different is

• any control sequences,
• any copy and paste operations,
• and any other actions that are specific to the terminal mode on the other device.

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 RPi

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 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.

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 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. 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.

Pre-configuring the Pi for headless operation

If you want to set up your Pi headless (without monitor, keyboard, mouse), then you must ensure SSH (which is off by default) is switched on as your Pi boots up. Otherwise you have no access to do any setting up, and you cannot even close down the Pi tidily! The only way to achieve this, is by adding a file SSH to the boot partition before the micro-SD card is put into the Pi. If you don't do this you cannot get headless operation, and you will need to move a monitor or TV, mouse, and keyboard, across to the Pi.

The file, you add to the boot partition (there is a second partition that may be invisible), must be named "SSH" with those three letters in capitals, but with no file extension. You can create the file with whatever text editor you have available.

• 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 touch ssh, 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).

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, and that your other device is on the same local network), type ssh pi@raspberrypi 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 https://www.putty.org/).

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.

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 installed on a RPi by issuing commands from your PC

If you choose to use the simple sudo mono CumulusMX.exe 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 RPi

In the Cumulus Support forum, there are articles about a stop/start routine, a backup routine, and 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:

1. 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.
2. 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
3. Use Screen software to start up a separate session that you can log off from without MX stopping (see how to run using screen}
4. 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

Headless Wireless Network set up

If you don't connect a keyboard and monitor to your Raspberry Pi, you can't set up the wireless network configuration on your Pi using one of the provided configuration tools as described in the earlier wireless network sub-section.

You can use the SSH approach described immediately above to access the Raspi-config tool and in that do the necessary configuration.

There is one further, complicated, way to set up the wireless configuration so that the wireless network will work when you first boot up your Raspberry Pi. If you have brought the Zero model, that does not allow Ethernet connection, you might decide to follow this complex approach that involves creating a text file in the boot partition of your micro-SD card, and store it in the boot directory on your micro-SD card with a file name wpa_supplicant.conf before you insert that card in your Pi and do its first boot.

A note of caution here, it is easy to make mistakes, and you may find this does not work. It is presented here just to cover all options, to use this does require some technical skill, a novice will be better off avoiding this.

Ensuring you are using a text editor that won't add any unwanted control characters, add the following text using UTF-8 encoding:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
    ssid="YourNetwork"
    psk="YourNetworkPassword"
    key_mgmt=WPA-PSK
}

• Obviously, if you are not in United Kingdom, you will replace GB by the country code that applies to you.
• Within the first set of quotes, replace YourNetwork by whatever Service Set IDentifier (SSID) is used for your wireless network.
  • 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, but you may have changed it from that initial setting.
  • Whatever it is, and it can be up to 32 characters (letters, numbers, and symbols), type it within the double quotes.
  • 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.
• Within the next set of quotes, which relate to the key (or password) that protects access to your network, replace YourNetworkPassword by 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.
  • In this case, 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.

Should you wish to set up your Pi with several network definitions, please see 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 winSCP to copy the installation to your RPi.

Use of FTP or SFTP was described earlier at #using file transfer.