This document is 'Work In Progress' so content may not be complete.

Request for help from Wiki Readers

Do you understand how MX works?
Do you use hardware, or MX functionality, that is not yet documented? Can you begin that documenting?
Can you contribute simple text for novice users, examples of what you have done, correction of typing or factual errors, or supply missing details?
Will you make this page more useful by bringing content up-to-date as new releases change some information written for older releases?
Does any page need a section for novices, so they don't need to read more technical information further down that page?
Is there some information on this page, that should be on a separate page? Can you create the new page and move the less relevant information off this page, don't forget this page needs a link to the new page so people who expect to find it here know where it has moved to?

If you plan on contributing to the Wiki, then you will need an account.

Please use the Request Account form to apply for an account. Note that the Wiki is currently undergoing restructuring and is largely locked for editing, but please apply for an account if you wish to contribute in the future.
You will find help on how to contribute to this wiki at How to Edit.
If you need to consult others, please use the Cumulus Wiki suggestions forum.

Please be aware that information on this page may be incorrect.

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

Using MX on UNIX-derived Operating Systems

MX runs on any UNIX-derived operating systems (OS):

including those found on Apple Mac computers,
and those found on a multitude of devices running Linux.

UNIX is a long established operating system, and both UNIX and its derivatives have good long term compatibility. This means that commands are generally easy to learn and use. Most devices also have a graphical user interface that can do the more straightforward tasks without needing to know all the commands.

Device Coverage

This page is intended to cover all Linux-based devices, but the content here is based on experience of those who have contributed to this page.

Linux is available in a multitude of different kernels, on a multitude of devices, but this Wiki page will largely ignore any technical variations (some included at end of page) and focus on giving some background content to support the basics.

The Raspberry Pi Operating System is based on Debian, one of the Linux kernels.

If you use a different kernel, or feel that this page inadequately covers what you want to know, can you add sub-sections to this page to ensure it covers the Linux device you use?

Until somebody creates a separate page for Apple Mac computers (that would be a good idea), this page is the closest.

What do people think about MX on Linux?

Contributions to the Cumulus Support Forum suggest that:

Use on a Raspberry Pi (RPi) computer is very popular
In general, people find installing, and running, MX on Linux is easy
The few people who do have difficulties are those who have good knowledge of Microsoft systems and feel scared to swap to something different.

Microsoft has had a deliberate policy of being different, so it is not UNIX-like. The Running Cumulus MX on Microsoft Windows page covers those aspects of MX that are specific to Personal Computers running Microsoft's Windows Operating System.

In the Cumulus support forum, there are many posts from people who are struggling with MX on PCs, as it seems people often find “installing”, and using, MX is more difficult when using Microsoft Windows.

Page Content

This page:

describes the options available for installing MX, and the other Cumulus packages
describes the pre-requisite MONO software needed to run the various Cumulus executables, (for Raspberry Pi only), how to add the Mono repository to your system, and how to upgrade MONO
explains the few key Linux commands it uses
describes the administrative interface and instructions for configuring MX
it tries to be useful to anyone who has never used MX, and anyone who knows Cumulus, but has not run MX on Linux before
describes the various options available to run MX
describes the optional parameters you can add when starting MX
describes the other executables

There are various related pages to get more information:

Go to Category:Terminology for links to pages that explain terminology used by Cumulus (some of these need updating for MX)
Go to Category:Cumulus MX for links to all pages in this Cumulus Wiki that relate specifically to MX
Admin interface provides information on configuration and web pages for viewing your weather data locally
Go to Category:Cumulus Files for links to all pages describing the sub-folders and files used by MX
If you encounter a problem when running MX, see What to do when I have a problem with MX
The Cumulus MX FAQ page was created with snippets from the forum, but nobody has yet sorted this out into a useful page or updated it for recent releases
If you were using the original (now 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 want to use a script language, you might want to read PHP Hypertext Pre-processor and JavaScript page

For those using Raspberry Pi computers

You have two choices:

CHOICE ONE: ‘’’Create a micro-SD card that has everything on it to load a kernel onto your computer and run MX’’’

The developer has created an image you can download.

That image contains:

Raspberry Pi Lite Operating System as kernel (no graphical user interface, designed for a RPi without keyboard or monitor)
Mono-complete package
Cumulus MX package

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.

If you want to pursue that approach, please read Raspberry_Pi_Image page, instead of continuing to read this page. Obviously, you can return to this page if you want to learn more.

CHOICE TWO: ‘’’Load the software packages individually’’’

Please read on, this page will tell you all you need to know.

Do you have a Kernel?

Is your Linux computer already working? Or does it need a Kernel to be installed?

Operating system is alternative name for the kernel, this is the software that is loaded onto your computer to provide Linux commands and everything else that males a computer work.

Please see Raspberry Pi computer page if you want guidance on choosing which model to buy and how to install an operating system, so you are ready to install MX.

Ready to install MX?

Assuming our Linux computer has a kernel, how do we add packages to our system? We need a short technical digression to explain the command, skip this next section if you already know how to install packages.

The various components to commands for installation

Linux computers have a “source list” which references the repositories from which software packages can be installed.

If a particular package can not be found in repositories already in the source list, then another repository can be added to the source list.

sudo

The initial "sudo" part of many commands gives us super-user (root) rights when executing the instruction that follows.

apt

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

There is a longer technical explanation towards the end of this page, all I will say here is that you might see “apt-get” used in some on-line examples. I suggest you replace “apt” where “apt-get” is seen as generally “apt” is more friendly. Equally, “apt” can replace “apt-cache”, which I won’t explain.

install

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

For the record only, here is full list of what can follow “apt”:

Instruction following “apt”	Description
install	To install a package and its dependencies
update	To make sure your computer has up to date information about repositories installed and to report if these contain packages that can be upgraded
upgrade	To see which of your packages have newer versions now available in repositories, and to replace those packages with the newer versions
autoremove	To check all components in the packages you have installed and remove those components that are not needed by the dependencies of the packages you use. As an example, when you install mono-complete, there might be components that are never used and “autoremove” can be used to tidy up when you finish all your installations
remove	If you want to remove just one component manually, use “remove” followed by the name of component you no longer want
purge	To remove any installed package and delete all related configuration files
search	To search in repositories in source list for a package you specify after “search”
show	To show any information available about a package that you name after the “show”

Flags

The basic syntax is either one or two hyphens, followed by one or two letters (each letter has to be a specific case). Various examples will be seen on this page, but here just one is explained here.

After the “install” part mentioned above, we can add “-y” to signify that we want the install to continue where without the “y” the package manager will ask periodically if we want it to continue.

Name

The final part of the installation command is the name of the package or component that we want to install.

Preparing for an install

Before we do an install of a new package, we typically use some of these commands to ensure our computer is in the best state to work out dependencies of what we are about to install: sudo apt update sudo apt -y upgrade sudo apt autoremove

Each of these can be understood from information in previous section.

Which software packages will we install?

If you read all the previous section, it explained Linux has a ‘’’source list’’’ of ‘’’repositories’’’ from which it can load software packages.

Our first task will be to install the appropriate mono repository, if that is not already in our source list
Our second task will install a package called ‘’’mono-complete’’’ from the repository we just installed, (this is needed to run software written in the C# languages)
Then to install ‘’’CumulusMX’’’, this is written in C# and we download it from Software#Latest_build_distribution_download
Next to install ‘’’ Create Missing’’’ another C# package (it will missing fields or missing lines in log files) package downloading from Software#Create_Missing
Finally, install ‘’’Export (old data) To a Maria (or other MySQL) database server’’’ package downloaded from Software#ExportToMySQL

Changing the Source List

If you type sudo apt search mono-complete, you will find out whether the package is available from one of the repositories already in our source list. Each of the parts of that command was explained earlier.

If mono-complete is not available (or only available in an older version incompatible with MX), then we have to add a new repository, and the one to add depends on which kernel we have, so choose the right sub-section below.

Add the Mono repository for a Raspberry Pi

The two Mono repositories listed here are specific to the 2017 and 2019 releases (respectively) of the operating system for a Raspberry Pi computer. These are taken from [1].

the first line (in each case) installs a certificate
the echo line defines a repository to add to the sources list.

Raspberry Operating System 9 (stretch)	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-raspbianstretch main" \| sudo tee /etc/apt/sources.list.d/mono-official-stable.list </code`	`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`

Add the Mono repository to Ubuntu, Debian, Fedora

At time of writing, [2], shows the instructions for versions 16, 18, and 20 of Ubuntu.

Equally, [3], gives details for debian, and [4] for Fedora.

Others can be found by choosing other tabs on any of those links.

Installing Mono instruction

Now we have the certificate needed, and the repository for mono-complete is added to our source list, we can do the actual install:

sudo apt install -y mono-complete.

The “sudo”, “apt”, “install”, and “-y” have already been explained.

The "mono-complete" is the package we want.

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

Please note that a particular MX build might specify it needs a particular version of Mono. Hence, although normally you can upgrade a cumulus package without upgrading Mono, sometimes you will need to install Mono again.

The latest release of Mono can always be downloaded from [5], follow step 1 there, but in step 2 replace ‘’’mono-devel‘’’ by ‘’’mono-complete’’’

Cumulus packages

Note use of plural in section name above, the following sub-sections will install MX and the other packages already mentioned, all by Developer Mark Crossley.

Where to install all packages?

For simplicity on this page EXISTING PATH is used to represent any location in the Linux file structure where you decide to install Cumulus:

Some people install it into ‘’’/home/pi/’’’, the default folder for the default user (Pi), because then the default user has full permissions automatically
Mark suggests you install into ‘’’/opt/’’’ which is where other additional software is often installed
- This does mean you may need to change permisisons for the CumulusMX sub-folder
Many with a Raspberry Pi add an external drive to reduce wear on the internal micro-SD card, and so if they have to reload the kernal (sometimes called “operating system”), they don’t lose their Cumulus packages and data.
- This is more complicated in that you might have to create linux partitions on this disc, then mount these partitions, and this page is not the place to get too technical

All the Cumulus packages, should be put into a folder called “CumulusMX” (note where capital letters must be used).

You can create that folder as you unzip a MX release, or you can type sudo mkdir EXISTING PATH/CumulusMX first (note that EXISTING PATH is explained above and always starts with a slash “/”.

Download links

Using your preferred browser, navigate to the following links to download each package:

“Cumulus MX” package from Software#Latest_build_distribution_download
“Create Missing” (rectify missing fields or missing lines in log files) package from Software#Create_Missing
“Export (old data) To a Maria (or other MySQL) database server” package from Software#ExportToMySQL

Alternative download link for older MX releases

For completeness, you may have discovered (from posts in the Cumulus Support Forum that the current release of MX has a bug that affects an aspect of MX that you intend to use. Remember, it is impossible for the developer to check all the ways in which versatile MX can be used (different weather station types, different computer types, plus a whole host of features, and different external upload sites, that are only used by a sub-set of people).

In such a case, download any earlier build, without the bug, from CumulusMX/releases.

Handling zip files

Each release is presented as a zip.

The download and unzip procedure is exactly same on your Linux computer, as it would be on a Windows PC. So if you have two devices available, you can download on either device, and if it is not the computer you want to install on, you can use a file transfer package to move the files between devices, or use a drive (or even a memory card) with a partition formatted so that you can read it on both devices. Windows and Linux partitions are formatted in different ways, and it is likely that Linux can read a Microsoft partition, but unlikely that Windows can read a Linux partition.

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

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

Where to install MX

As mentioned earlier, you can choose where you install your three Cumulus downloads. It is important to minimise the length of the path name, because this has to be passed between various different software languages (and longer paths risk truncation). Here I use “EXISTING PATH” (which will start with a slash “/”, but not end with a slash) to represent whatever path you have selected.

It was also mentioned before that you can create the folder to hold the packages in advance using sudo mkdir EXISTING PATH/CumulusMX.

Upgrading a Cumulus package

Upgrading to a new MX release is explained here, but basically follow instructions above, and install over your existing files. The alternative is to install in a new folder (or rename the old one), and copy across files not in the release.

Folders to copy across from previous Cumulus installations

If you have used Cumulus before, you will be seeking to keep your existing (data and extremes in) log files. This means you must transfer the whole /data sub-folder.

If you are using the optional “NOAA report” functionality, you must also transfer the whole Reports sub-folder.

Line terminators in these files

If you are moving from Microsoft Windows to Linux, you need to be aware that Microsoft ends each line with two characters (Carriage Return and Line Feed) while Unix/Linux ends each line with a single character (Line Feed).

The kernel in your Linux computer might be able to detect that it is getting Microsoft files, and discard the extra end of line character.

However, if you are reading that file in a script, it might not detect the end of line encoding and so if that script uses “LF” to terminate the line, when the script is reading the final field of each line has an unwanted “CR” in it. Equally, if the script uses “CR” as line terminator, then the “LF” is added to the first field of the next line.

In each case, any checking for numerical input might fail, and any attempt to check/extract characters from these fields might fail because their position relative to start/end is changed.

Changing line terminators

Many editors designed for programmers (they might be described as providing a programming development environment) can change the line ending of every line (either while file is being edited or when file is saved).

‘’’Geany’’’ is a programming development editor provided on some Linux systems including Raspberry Pi, that can do this.

Notepad++ is another editor available for multiple operating systems.

Both have capabilities to make such changes on either the single file that has focus or all loaded files.

Files to copy across from a previous MX installation

There are two configuration files that are not included in any MX release:

strings.ini (note all lower case) – optional file to customise output
Cumulus.ini (note initial capital, then lower case) – main configuration file

If your old installation was for a relatively recent release, then just copy these files to new installation and optionally skip the next 2 sub-sections.

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

strings.ini

This is an optional file based on samplestrings.ini. As the latter can change dramatically sometimes when a new release comes out, your existing “strings.ini” might need to be modified.

There is no automatic way to check your “strings.ini” file, if MX does not understand any parameter in this file, it ignores it.

Therefore, you need to manually check each parameter you have in your “strings.ini” file against parameters in “samplestring.ini” of your new install.

Cumulus.ini

Some people prefer to omit their existing “Cumulus.ini” file from their new install. Instead, they work through all the settings manually, so that MX can create a fresh file, with them having confidence every setting reflects their preference.

If you previously used an older release of Cumulus, but in this new installation will be using the latest release, you may want to read up on all the changes.

There were significant changes to “Cumulus.ini” when moving from 1.9.4 to 3.0.0, see Cumulus_3_(MX)_beta_documentation and Migrating_from_Cumulus_1_to_MX pages. Documentation for the 1.9.4 file can be found here.

There were gradual changes to “Cumulus.ini” as releases went from 3.0.0 to 3.9.7, documentation can be found here where the changes are made clear. Please note, that page was not maintained after 3.7.x releases, and so does not show all changes from 3.8.0 to 3.9.7.

The documentation for the latest release can be found at Cumulus.ini, note that this does not explain the changes from 3.9.7 to 3.10.1, but it does include advice on (while MX is running) it can automatically update the file. This automatic approach is easy, but you might want to work through settings to change preferences for any new parameters.

Running MX on Linux

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

as a service and
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.

There is a task to do just once to configure the service
Find the EXISTING PATH/CumulusMX/MXutils/linux/ sub-folder, that might be in home directory and therefore found using "~/CumulusMX/MXutils/linux" as explained elsewhere on this page
- At time of typing this, the sub-folder only contains one file, the one we need to edit
As described later there is a choice of editors, but you can use sudo nano cumulusmx.service to edit the service configuration file
Look for ExecStart=/usr/bin/mono-service -d:
- Replace the path that follows the above text with the path to your CumulusMX.exe, add the -service and optionally add any other parameter (e.g. -debug, -locale, -port) as described in sub-sections above.
save file
now copy file

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.

That is all folks

If you have read up to hear, you now know the basics for using MX on Linux.

The remaining sections are more technical and so you can skip them.

Technical Extra

PLEASE SKIP ALL SUBSEQUENT SUB-SECTIONS IF YOU WANT TO AVOID TECHNICAL EXPLANATIONS.

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.

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.

folder commands

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

To remove a folder, that has no files in it, type in a particular path, type sudo rmdir /path/directory.

To remove a folder that does have files, and/or sub-folders within it, type tt>sudo rm -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 something like cp -R --update --preserve /home/pi/CumulusMX/backup/daily /media/pi/data/CumulusMX/archive

Sometimes, you have a folder or file in just one place in the file system, but want to be able to access it at a different place (because something expects it in the second place), the syntax is ln -s /path/elsewhere path/pointer_location.

An example might be ln -s /var/lib/phpliteadmin/diary.db ~/CumulusMX/data/diary.db (phplite admin can only update databases in one folder /var/lib/phpliteadmin, or in older releases in /usr/share/phpliteadmin; while MX expects the file to be in its data folder but is happy with a logical pointer to another folder).

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.

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:

connect your external storage
type su to gain administrative access
enter your RPi password
type fdisk -l (this is only available to root user) to see names for all storage your Linux computer can see
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
if "sda" and "sdb" appear, or any others up to "sdz", the last one will relate to the most recently connected storage
if your drive has partitions, then you will see further entries like /dev/sda1 and /dev/sda2.
type df to see whether your drive is currently mounted (being used by computer system)
if it is mounted, the command to use next is (type this accurately, there is a temptation to type an English word that adds an extra "n"!) umount /dev/sda, obviously replace the "a" by the appropriate letter seen in the earlier command
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.
Now we have a partition table and a partition on our drive, we can repeat fdisk -l to see the entry now added, it might be /dev/sda1, where again the "a" might be a different letter
To format this partition for Linux, we specify "ext4" as the way to format it using mkfs.ext4 /dev/sda1, again replacing the "a" as required.
we need to create a folder within
- "/media" for Linux in general
- "/media/pi" for Raspberry PI OS
As we will learn later, the relevant command (in RPi OS) is mkdir /media/pi/my_short_name, where "my_short_name" is selected by you
To mount our partition, we type 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.
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.

Package Manager – a brief technical aside

Linux operating systems install software by looking in repositories, and checking a register showing dependencies. When you ask Linux to install a particular package using “apt”, it also checks if all dependencies of the selected package are already present, and installs any that are missing.

If you look up on-line how to install any software in Linux, it may use “apt-get”, that is an earlier package manager, in general you can use “apt” instead now.

The full differences between “apt” and “apt-get” depends on your Linux flavour, so this technical aside now splits further discussion by Linux flavour.

Debian as used by Raspberry Pi

“Debian Linux” (and its derivatives such as “Raspberry Pi Operating System”) uses “apt” to mean a ‘’’Package Manager’’’ that can install, update, and remove packages from these computer systems.

For Debian Linux, “apt” is directed at the end-user (it has user friendly features like a staus bar showing progress on a long install or long upgrade, and can produce prompts about what it is doing and can give choices about whether to do individual actions).

There is an alternative “apt-get” which is more powerful, but directed at system level users (those who don’t want to be watching progress and possibly responding to prompts).

As “apt-get” is updated less frequently than “apt”, it may be it will not work with new packages. Put another way “apt-get” may never change what it can do, but “apt” may get modified to do more than it did before.

Ubuntu

For Ubuntu only “apt-get” was available up to 2014, when “apt” was added. Both work as described above for Debian. Again “apt” is best to use.

Mint

Linux Mint has a different variation. Its “apt” calls its “apt-get” and adds extra features. So both effectively do the same, but (as with previous flavours) “apt” is best to use.

It is likely that other Linux variants will also vary how these alternative commands differ.