Cumulus Wiki - User contributions [en]

Updating MX to new version

2021-08-06T23:52:39Z

Cortmalaw: /* Latest release */

=Who this article is for=

Please be aware that if you want to move from Cumulus 1 to MX, you should read [[Migrating_from_Cumulus_1_to_MX]] article instead.

This article is for those who already use MX, and so are comfortable with basic MX installation and running.

=Who is not intended reader=

Cumulus MX has been updated so frequently in 2020, that you may be used to upgrading to a new build, and for you this article is not useful.

=Where to download a release distribution=

==Latest release==

Download release distribution zip from [[Software|the Software article in this Wiki]] for latest version.

Be aware that the developer needs to remember to update this link each time there is a new release.

An image that contains a '''Raspberry Pi lite operating system''' and a recent CumulusMX release already included, can be downloaded from the same wiki article. Not every CumulusMX release is provided as a Raspberry Pi image, so you may need to perform an update to get the latest release. The Raspberry Pi image places CumulusMX in /opt/CumulusMX.

==Any release developed by Mark Crossley==

Download release distribution zip from https://github.com/cumulusmx/CumulusMX/releases for earlier versions.

=Introduction to upgrading MX=

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>
[[Category:Cumulus MX]]

You can download and unzip in advance, but cannot replace existing files while they are being used, so how you stop MX is in next two sub-sections.

My preference, after download, and unzip into a holding area, is to copy (it would be file transfer if you download on another device) over my existing installation all files except:
*CumulusMX.exe
*CumulusMX.exe.config
while MX is still running. I then stop MX for minimal time needed to replace just those two files before I restart MX. That way I minimise downtime, especially useful for a patch release when few files have changed, as it takes some time to replace all the files in the installation.

For simplicity, in guidance below, MX is stopped before any files are replaced.

==Upgrading on a Raspberry Pi (RPi) computer by commands from a Microsoft Windows computer (PC)==

I recommend you download WinSCP (this and PuTTy share some settings). This will allow you to connect your PC to your rPi and copy files back and forth. You can use it to copy the MX distribution, you download and unzip on your PC, onto the RPi. You can also use it to take a back-up of your RPI files onto your PC, and to pick certain files off your RPi. e.g. copy log files from [[MXdiags folder]] to your PC to read diagnostics etc.

You can download PuTTy (shares some settings with WinSCP) to enable you to open a terminal session and send commands to your RPi computer.

If you have Cumulus MX setup to run as a service then you will need to do one of these, should you wish to add debugging when the upgraded MX begins...
# Edit the CumulusMX service file (see [[MX_on_Linux#Running_as_a_service]]) to add the -debug parameter (do this if always want debugging on, not usually needed)
# Just set it from Program Settings | Logging Options (easiest for turning debug on when you need it and off when you don't need it)
# Edit the Cumulus.ini file and enable it in there (no longer recommended)

==Upgrading if you run MX as a service==

Don't forget to stop the service, before you do the upgrade.

For a Linux Operating system: <code>sudo systemctl stop cumulusmx</code>.

For Microsoft Windows Operating System: (a contributor who uses Microsoft Windows needs to modify this page)

==Upgrading if you run MX interactively==

If you do NOT run as a service, you will want to use '''Control and C''' in the terminal (or command) window running MX to make the software close tidily.

== Updating to the next MX release if you have not upgraded before ==

The simplest upgrade is from the immediate preceding build, and the steps required are summarised as follows:
# Download the release distribution zip for the next build (see later for where from)
#* My advice is to have a separate download location away from the location where you are installing/running the software; it can retain older releases to make regression simple if the new release proves to have a bug.
# Use '''Control-C''' to stop Cumulus MX (see later if running as a service)
# Take a backup of your complete existing MX installation (as it is not running, no files will be locked)
# Unzip the new distribution, overwriting the previous installation (the release announcement might ask you to delete obsolete files)
# Run any one-off batch scripts needed to prepare for upgrade
#* These might be needed if log files in the new release contain fields that were not in earlier release
#* These might be needed if you use optional database functionality (see later for examples)
# Do any actions that require you to use [[MX Administrative Interface|Admin Interface]] to change settings
# Do any one-off actions in relation to any files provided by MX for you to run a web site with the default pages
# Restart your Cumulus MX (consider running with '''-debug''' parameter if you are not sure the new build is bug free)

The remainder of this article explains all options for updating, and is thus less simple than above.

==Installer Option==

[https://cumulus.hosiene.co.uk/memberlist.php?mode=viewprofile&u=9016 HansR] on support forum has developed an multi-platform installer, see [https://cumulus.hosiene.co.uk/viewtopic.php?f=44&t=18916 Multiplatform Installer for CumulusMX] which makes life a lot easier if you do not wish to dive into the (file level contents) internals of CumulusMX.

#Copy the '''InstallCMX.exe''' to any directory you want, on the drive where you wish to install (or have previously installed) MX.
#Copy the CumulusMX release distribution zip(s) to that same directory, if you have not already done so. You may have more than one distribution in the same directory.
#*The install procedure gives you the possibility to select, or define, the Archive to install, and the location where to install.
#Stop CumulusMX
#Run '''InstallCMX''' and confirm / fill in (on the console) where you wish to install (or update) CMX. The default for Windows is C:\CumulusMX\ and for Linux it is : /home/CumulusMX. The Installation directory can be modified.
#* You can give the '''build number''', for the release distribution zip, to install as command line '''argument'''.
#Start CumulusMX

'''NOTE:''' On Windows you run the installer as any other command line executable and it is best to open a command window in which you start the installer. On Linux you run it on the command line as "mono ./InstallCMX.exe", the mono command can be omitted if mono is already active (e.g. if you run CumulusMX as a service, and stop it, mono remains active).
'''NOTE:''' In an existing installation with modified files, make sure those are in a different, either filename or folder (a safe place). If they have the same name as files in the distribution, they will be overwritten.
'''NOTE:''' Check in the <code>webfiles</code> directory to see if any files there have been modified, since your last upload to your web server. If so, move those new files to the website.

After the installation, there is a '''log file'''. Check the log file to see everything has gone well.
There is an '''ini file''' where you can control:
* NormalMessageToConsole=true or (default) NormalMessageToConsole=false
* TraceInfoLevel=Warning (out of: Error, Warning, Info, Verbose, None)

Any reactions (thank you, issues and questions) please post in the [https://cumulus.hosiene.co.uk/viewtopic.php?f=44&t=18916 download thread of the installer].

Modifications and additions on user request can be discussed (e.g. think about automated start/stop, upload of webfiles to the directory etc....), use the talk for this page.

==Upgrading if you are running MX on a Linux computer==

You might want to read galfert's post on the support forum [https://cumulus.hosiene.co.uk/viewtopic.php?p=148851#p148851 here] for the relevant Linux instructions in a concise format.

If you want more detailed information, on any Linux (including Raspberry Pi operating system) aspects of the upgrade instructions on this page, see [[MX on Linux]] page.

== Updating if you use the start/stop management script ==

This section contributed by ''Jank'' on support forum. Note the version on the forum might have been updated from the original included here.

1. look on [[Software|Software download page]], find the link to latest version, and fill out the '...' below appropriately as you run these 2 commands on your device where you do downloads:
<pre>cd /tmp
wget https://github.com/cumulusmx/CumulusMX/ ... .zip</pre>

2. Once that download is complete, start cumulusmx.sh with option -u
<pre>/home/pi/CumulusMX/cumulusmx.sh -u</pre>

3.When asked for the zip file, enter
<pre>/tmp/CumulusMXDist</pre> and hit the TAB Button

4.Choose the zip file with the CumulusMX upgrade and hit return.

5. Follow the on screen instructions

6. With each update component .....you can choose: [y]es, [n]o, [A]ll, [N]one, [r]ename

I would recommend select '''A''' as that will simply replace all files without further action.

CumulusMX will be restarted after upgrade completes.

You can check if the upgrade was successful by using option -s:
<pre> /home/pi/CumulusMX/cumulusmx.sh -s</pre>

=Considerations that determine when to upgrade=

Cumulus MX will nag you, in various places, to make you aware if you are not running the latest build. Some people will choose to upgrade as soon after a new release as they can. However, each upgrade does involve a period when MX is not running, and that causes some loss of data:
*for some weather station types readings taken every minute, or more frequently, are replaced by whatever period you station data logger records at;
*for other stations, without their own logging, all data is lost for the period when MX is not running.

Other, more cautious, people (like the present writer) will not upgrade each time a new release becomes available (and there are a lot of new releases in 2020), here are some of the reasons:
* you will see in the Cumulus Support Forum that many builds have bugs, and so you realise that it is better to stick with your fully working release, than install one with bugs;
* you may wish to avoid the loss of data mentioned above, by minimising the number of times that you stop MX;
* you may run MX on a computer that you rarely visit, perhaps even in a remote location not often visited, so you prefer to leave it untouched, rather than risk possibility of being unable to restart remotely;
* you may just have more important ways to use your time than updating your MX software, and some new builds might not give you any benefits that make it worthwhile to change your priorities.

It is perfectly possible to '''upgrade from rather old versions of MX, to the latest''', skipping intermediate versions, '''but there are some key versions that you should not skip over'''. This page, in subsequent sections, includes suggestions for which releases to install (and get running) before moving onto newer releases. This will be especially useful for those people who do not immediately upgrade to new releases, as per above suggestions.

===Advice about skipping versions===

Please see [[Updating_MX_to_new_version#Updating_from_a_very_old_version]] sub-section later on this page (and preceding sub-sections where relevant)

The important point to make here is that when you do an upgrade, you should copy in '''ALL''' files from the release distribution you want to run next. This is because there are dependencies between files within a distribution, so missing out any particular file may stop other files from working. However, if you are skipping versions, read the in-between release announcements to see if there are any one-off actions.

= What to read (and when) before upgrading =

== Upgrading from immediately preceding build ==

=== The release announcement ===

The release announcement is found in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic of the support forum.

*Generally, a release announcement WILL contain
*#An overall purpose for that particular release (e.g. fixing bugs or adding functionality)
*#Details of what functionality has been added
*#Details of what bugs have been fixed, or where the processing has been improved
*# (For older releases only) A list of the main files that have been added or amended in the release (excluding "updates.txt" which is amended in each release)
*#* (Publishing a list of changed files has been discontinued, because people were updating selected files, and often missed crucial ones, like '''CumulusMX.cfg''')
*Sometimes, a release announcement MAY contain
**Descriptions of one-off actions (like changing the schema if you use a database, or editing your web pages to take advantage of new web tags).
**Actual scripts to download and run to perform the necessary one-off actions.
*Be aware that it is worth while checking back on the release announcement for a few days after a release.
**It may have been edited because the original announcement forgot to mention something.
** It may have been edited to mention that some bugs have now been found
***That may mean you are advised to regress to an earlier version and use that
***It might mean that some supporting files in current version are wrong, and you only need to regress those named files
***There might be an emergency release to fix the bugs, and you need to upgrade to that emergency release
***Finally you might be given advice to avoid using certain parts of the functionality or take some other action until the next release is available.

===Other places where you can find information about release content ===

Although it is not always kept in step, a concise summary of all formal MX releases is available at [[Cumulus_MX_formal_release_versions]].

You can also view the latest [https://github.com/cumulusmx/CumulusMX/blob/master/Updates.txt Updates.txt].

===Deciding whether to upgrade to new release ===

This has been covered earlier in this article, but I repeat here 2 critical considerations:
*Any new development or change in a new version of MX might cause problems for some users. You might want to stick with the version you are already using unless you really need any new functionality or the fixes gained by upgrading.
*Also remember that there are bugs in (almost) all versions of MX, this is a large and complicated package, and the current developer has not been able to test all the code with all possible settings and all possible weather stations.

==Updating to a new minor build, skipping in-between minor builds==

For a minor version build either the associated version number does not change or only the final section changes (3.x.y to 3.x.z).

===Reading multiple release announcements===

If you are skipping some intermediate builds, then you will need to read each of the formal release announcements for builds after the build you currently use.

The other sources of release information mentioned above may be consulted as an alternative and may highlight something useful, but the formal release announcement contains what the developer wants you to know.

===Action to take when skipping minor intermediate builds===

You need to apply the cumulative actions recommended (i.e. apply any actions in sequence as listed for each intermediate build). Unfortunately, for Cumulus MX, one cannot assume that minor builds have no one-off actions associated with them. Luckily, most of the advice above for updating from immediately preceding build still applies.

==Updating to a new major version==

Generally, if the developer decides a new build warrants classification as a major version (i.e. 3.w.0) then the change being implemented is significant enough that updating might be more complex.

=== Examples of what might be classified as a major change===

*Additions to fields in log files (whilst older lines can continue to be read, you might want to consider [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 amending your standard data log] by populating the additional derivatives for older lines)
*Schema changes for database tables (if you don't use the standard tables, this might be irrelevant to you), the standard insert operations by MX can cope with extra columns in a table, but will fail if any column they try to update is missing
*Additions, changes, or removals, in configuration file (in general MX will ignore unrecognised parameters, but it does need correct values for those attributes it does recognise), see release announcements to discover if new lines in configuration file need you to add them manually or you need to use the admin interface to select the right setting for you
*New pages in Administrative Interface (additional pages require menu on every other page to be amended)
*Changes to existing pages in admin interface that involve changes to associated files (it is vital that all associated files are from same build)
*Catering for new weather station sensors, or new ways of communicating (this might not seem relevant to you)
*Any interface functionality changes (it may look the same, but what it does has changed)
*Additions to files being generated for web server (i.e. changes to template files, or additions to ''web'' or ''webfiles'' folders), even if you use your own versions of such files you may want to check the revisions

=== What you need to read ===

*Basically, check the corresponding release announcements for every version since the one you have been using before planning your upgrade.
**Make a note of any one-off actions required at particular in-between versions, remember these actions are only in forum release announcements.
**Although one-off actions will not be described in the Wiki (whether on the [[Software]] page or the [[Cumulus_MX_formal_release_versions]] page), the Wiki can give you an idea of what functionality has been improved to help you decide whether to upgrade.
*It is still worth reading all the points made above for updating from immediately preceding build.

=== Doing the upgrade===

# Download the release distribution
# Use '''control-c''' (or equivalent for MX running as service) to stop your existing MX software
# Backup your existing installation
# Do the on-off actions identified (e.g. changing schema of database tables, adding new configuration
# Unzip the distribution over existing one (alternative installation options listed later)
# Restart MX, considering whether to use '''-debug''' parameter in case the new release does not work for you
# Check the latest file in the MXDiags folder after an hour, to see if there have been any problems with reading from station, real-time uploads, standard uploads, or hourly uploads. (You may wish to recheck after an End of Day action has been done).

==Updating from a very old version==

Many people believe if it works, it don't need fixing. So they install whatever MX version is available when they start using MX and ignore all the bug fixing and new functionality being added, and stick with their existing installation.

Suddenly they realise that perhaps their version does lack functionality that would be useful to them. Maybe their version does not have an editor for correcting rogue extreme records and they realise correcting log files is something that is hard for them to do.

This section is therefore included to give advice on why you should not jump from an old version to the latest directly, but how it can be safely done in stages.

===Recommendations for staged updating===

<big>This section will need to be updated, new contributors are needed to keep this advice current.</big>

====If using 3.0.0 (the MX original beta)====

Upgrade to 3.5.1 by downloading it at https://github.com/cumulusmx/CumulusMX/releases/tag/b3072.

This gives you essential new functionality in the admin interface like editors for the log files and extreme records. But it also fixes multiple bugs in the beta you were using and adds some useful validation missing in the beta.

It does not involve any updates to the fields in the log files nor to the columns in any database tables you use.

It skips you past the problems in 3.5.0. It gives you benefits introduced in 3.1.x, 3.2.y, 3.3.z, and 3.4.w releases.

Now follow instructions below, for ''If using a 3.5.x release''

====If using either 3.1.x, 3.2.y, 3.3.z, or 3.4.w releases====

As above, update to 3.5.1 by downloading it at [[https://github.com/cumulusmx/CumulusMX/releases/tag/b3072 Mark's Github respository]]. The actual installation is done using the instructions above for simple next build upgrades. You can safely skip reading the intermediate release announcements, as there are no special one-off actions.

When you are happy running 3.5.1, then you should continue to upgrade, initially follow instructions in next sub-section.

====If using a 3.5.x release ====

My advice is to upgrade directly to 3.7.0 available at [https://github.com/cumulusmx/CumulusMX/releases Mark's Github repository].

You should skip the intermediate releases because several 3.6.y releases have bugs in them, and you want to avoid those problems (the bugs vary in severity between mistakes in calculations done by MX to particular functionality not working).

But there may be additional actions you need to do when moving from 3.5.x to 3.7.y, depending on what features you use in MX:
*there are no additional actions if '''you use standard web pages and you do not use database tables''', just enjoy the bug fixes and extra features after your update!
*'''If you use database tables''', be aware that the schema (Column names that must be in a table) varies between 3.5.x versions and 3.7.y versions.
**The updating database table features in MX will only work if all the columns named in each such upload update ''already exist'' in the database table it is trying to update.
**Look at individual release announcements for both 3.6.0 and 3.7.0, to see the SQL provided for adding the columns added at particular versions.
***At 3.6.0 the SQL was provided as a separate attachment to the release announcement (read [https://cumulus.hosiene.co.uk/viewtopic.php?p=142085#p142085 UpdateMYSQL-b3076.zip])
***At 3.7.0 the SQL was provided as part of the main zip (read [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 AlterSQLTables3098.sql])
***In both cases, the SQL provided assumes you are using the default names for database tables, it does not read [[Cumulus.ini]] to see whether you have selected different names for the tables (unlike ExportMySQL.exe and standard CumulusMX.exe uploads which check what tables names you have selected for updates).
*'''If you have your own customised web pages''', then there are changes to web tags that might lead to you needing to edit your web pages.
*'''If you use commas to separate integer and decimal parts of real numbers''', then various releases from 3.6.0 to 3.7.0 add "rc=y" to various web tags, that option will replace the decimal commas you use by decimal points that are required for some script languages (like the JavaScript used by HighCharts), and that makes it easier if you want to customise your web site.

When you are happy with running 3.7.0, then you should continue to upgrade, and the next sub-section describes what to do next.

====if using a 3.7.y release ====

If you are using 3.7.0 (there were no other builds in 3.7.y series), then you should upgrade directly to version 3.9.6 - build 3101.

Only 3.7.0 was ever released, it introduced a lot of changes, so that is why staged upgrades recommend that this version is implemented, and run for a while, before continuing to upgrade.

Version 3.8.0 was a major release, as it introduced the ability to run Cumulus MX as a service. However, there were bugs in the builds in all 3.8.z versions, and in some 3.9.x versions, so that is why you need to skip through intermediate builds below 3101.

'''IMPORTANT''' one-off actions needed:
* There is a one-off change described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=146957#p146957 v3.9.0 - b3095 release announcement] for those using RG-11 rain sensor.
* There is a further on-off change described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=147329#p147329 release announcement for Patch release 3.9.1 - b3096] for those who use '''Mono''' to enable the executables to run.

When you are happy with running version 3.9.6 build 3101, you can continue to upgrade, and that will be covered in subsequent sub-sections (assuming someone is bothered to keep this article up to date).

====if using either 3.8.x or 3.9.y release====

See previous entry, upgrade directly to 3.9.6, or any later build, within 3.9.x, without any major change.

====From 3.9.y to 3.10.x====

The major aspects that changes at 3.10.1 (3.10.0 was withdrawn) are:
* Changes to settings
** You need to open the [[MX Administrative Interface]] and work through all pages in the '''Settings''' menu.
*Changes to web files in <code>CumulusMX/web</code>, <code>CumulusMX/webfiles</code> and introduction of <code>CumulusMX/webfiles-legacy</code>
**If you used the provided templates to produce web pages in earlier releases, or you had directly customised provided [[Customised templates|web templates]], these will no longer work
**Please see [[New Default Web Site Information|New Default Web Site Information page]] for further advice

====From 3.10.x to 3.11.y====

Treat like any other major version upgrade as described above.

= Knowing when a new release is available =

== CREDIT ==

Thanks to ''Billy'' on support forum for suggesting text for this section.

== Using forum notifications ==

As new releases are announced in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic, you can use the spanner tool to '''subscribe''' to this topic to receive notifications of a new post announcing a new release (or any other release-related announcement).

== MX terminal message ==

If ...
#...you have a monitor to see the terminal output from the Cumulus MX engine (Windows calls this either a command window, powershell window, or a terminal window depending on how you invoke it, for Unix-based implementations this is the output window when using the terminal functionality), AND
#...your device running MX is connected to internet, AND
#...your MONO (if not Windows) is not obsolete (SSL certificate out of date), AND
#...you restart MX
... then you will see a prompt when a new version of MX is available.

It is worth stressing that if you leave MX running, then this feature will leave you blissfully unaware that an update is available; it only checks when MX is restarted.

== MXDiags ==

In addition ...
#...if you can view the MXdiags file for the current session of MX, AND
#... MX is running with connection to the internet, AND
#...you restart MX
... if a new version of MX is available, the MXDiags file will say so (the message is not easy to spot as there is a lot of output before it, and variation in what output appears before it). Anyway, here is one example, just one example as in my experience '''the message has appeared at different places for each of the recent upgrades'''):
<pre>
2020-05-27 04:18:48.326 Calculating sunrise and sunset times
2020-05-27 04:18:48.326 Sunrise: 04:58:11
2020-05-27 04:18:48.326 Sunset : 21:19:54
2020-05-27 04:18:48.326 Tomorrow sunrise: 04:57:08
2020-05-27 04:18:48.326 Tomorrow sunset : 21:21:11
2020-05-27 04:18:48.388 You are not running the latest version of CumulusMX, build 3080 is available.
2020-05-27 04:18:48.763 Station type:</pre>

There is no message in whatever place it can appear ...
*... if you are using latest version, OR
* ... if you are not connected to the internet, OR
*... if you keep MX running all the time!

== Start/Stop script ==

When the '''Status''' option of this script is used, whenever a new release of MX is available, it will output a message.

== Dashboard in MX Admin Interface ==

In recent releases, one of the alarm indicators shown at the bottom of the dashboard page of the administrative interface, will flash red when you are not running latest build, and glow green when there is no newer release compared to the one you are running.

== Web Tags ==

Since 3.7.0 release of MX, two relevant web tags have become available:
* <#NewBuildAvailable> Returns a boolean value
** 0 - MX running the latest build available
** 1 - MX is running an earlier build than the latest public release
* <#NewBuildNumber> Displays the latest public release build number

= Recommended Actions when Updating =

== Back-ups ==

It is always best to take a backup of your existing MX installation before you do an upgrade, this allows you to regress back to the earlier version if either you mess up installing the new version, or the new version has a issue that prevents it working with the versions of other software (like MONO) that your installation uses.

== The two approaches ==

Contributors to this section are named in text.

Some people upgrade by just copying in the files that the release announcement says have changed, others copy in all files from the downloaded zip. The first should only be used with caution, files like '''CumulusMX.exe.config''' can change between versions, but not be mentioned in a release announcement, and the developer will have been making edits to files since the previous release, and might forget exactly which files have been edited between releases. Also you may be upgrading from an earlier version and therefore be skipping several intermediate releases.

You may be able to see the dates when files were changed within the zip and therefore be able to decide for yourself if you compare those dates with the previous release you were using if you have kept the download for the version you were using. However, do not assume that only files with later date are needed; in some releases the new build regresses one or more files and so a file with an older date is the correct one to retain.

===The rename old approach===

#The popular approach, recommended by many forum contributors, in many different posts (including at [https://cumulus.hosiene.co.uk/viewtopic.php?p=141763#p141763 this post by Mark Crossley for example] is to rename your current install directory, then unzip the new release, letting it create a new '''CumulusMX''' folder (or whatever name you prefer and specify in unzip options).
#However, you will find that this option is not being recommended any more, because it relies on you knowing which files (see next 2 points) you need to copy back.
#Copy across '''Cumulus.ini''' and (if you use it) '''string.ini''' into that new directory, and then copy the contents of the '''data''' and '''Reports''' directories from your ''current install'' to the new install.
#Don't forget to copy any other set-up files across too.
#*The advantage (as Mark says) is that you ensure you do use all the files in the new release, and don't miss out any he may have forgotten to mention in his release announcement.
#* A key advantage is that you don't retain files that an old release migt have needed but the new release does not use.
#*Another advantage (as PaulMy says [https://cumulus.hosiene.co.uk/viewtopic.php?p=140262#p140262 here for example]) is that you retain your old set-up intact and can easily restore it should you have a problem with new release.
#Various people advise that you don't delete your old installation for a week or so; as you may notice something from the older version that you haven't copied across!
#Check again that you copied across (you may not have all of these files, but if you have them in old installation then you need them in new installation) '''strings.ini''', '''twitter.txt''', '''Cumulus.ini''', and similar files in the same folder level as CumulusMX.exe, as well as all the files in the '''data''' and '''Reports''' sub-folders. Then, provided you are happy, you can delete the old release when you want to reduce clutter on your storage discs.

===The overwrite approach===

The general advice is that if you want custom pages for the administrative interface, or custom templates to process to produce your web pages, then these custom files should be given different names (and ideally be placed in different folders) to the standard files included in the release distributions. If you follow this advice, the approach described in this sub-section is the best for you, if you don't follow this advice, see later section on dealing with customised files.

#* if you have a lot of set-up files, or other custom files, (i.e. files with names that are not part of release), these won't be overwritten by files in the release distribution, but you do want to keep them;
#*or if you are downloading on a different computer, or on a different disc, to where you are running MX, it is easiest to keep your MX installation in the same place
#Note the forum administrator, David, [https://cumulus.hosiene.co.uk/viewtopic.php?p=140355#p140355 (see this post)] recommends this particular approach.
#After downloading a new release unzip it on the device/disc where you down load it. Next stop your existing Cumulus MX software and take a backup of your existing installation. After that, simply copy the files (optionally only those that have newer dates because they have changed) into the existing MX directory on the device where you run MX. Then you know all your existing files are there, and your MX can be run as before.
#The great advantage of this approach, and the reason that it is widely recommended as best, is that you can't lose any data or configuration files (i.e. files that are not part of the release distribution).
#Provided you did the backup, '''the only problem with this approach is that in some releases files are removed from the distribution''', yet unless you check carefully, this approach may ''leave files that are no longer required'' in your installation, and it is just possible you might continue to use the obsolete file instead of the intended alternative. Such a non-standard installation is difficult for others to support. So do check through file by file to ensure you only have files in the distribution you have just installed, not any from earlier distributions. The only files that you still want (that are not in distribution) will be those that either configure your system or contain your data in log files.
#*The updated files can be tracked by their modification date, some will be specified in the release notes (find them on [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 this forum]). There is a list indicating what files vary in [[Cumulus_MX_formal_release_versions|this Wiki article]].
#*In general, especially if updating a major release, it is best to overwrite with all files in zip, whether they are listed as changed or not. This ensures you have a consistent set of files, and avoids any issues when the developer does not correctly list all the files that have changed, or a file might be regressed to an earlier version and not have a newer date than the file in your previous installation.

====Example: downloading on PC and installing on pi ====

#On your pc: Download zip either from [[Software]] for latest version or from https://github.com/cumulusmx/CumulusMX/releases for earlier versions.
#On your pc: Use Filezilla (or similar file transfer program, or it might even be a copy over network depending on way set up) to transfer zip to pi (e.g. <tt>FileZilla CumulusMXDist3089.zip to /home/pi</tt>), but remember you might want to install to a different location (perhaps on an external USB drive, or SSD)
#Control C on pi to stop MX
#On pi go to directory where zip now is, for example it might be <tt>cd /home/pi</tt>
# Unzip the installation over your existing installation, by running on your Raspberry Pi this instruction: <tt>unzip -o CumulusMXDist3089.zip</tt>
# Restart MX
# Remove any files that were needed by earlier releases but release announcement says are not needed by the release you are installing

===The customised approach===

If you edit a file that is included in the release distribution, you should give it a different name (e.g. I have placed an underline in front of original file name for some of the files I edited in the admin interface), and/or place it in a different folder (e.g. I place all the cumulus templates I have created in a folder called '''cumulus_Templates'''). If you follow this advice, then you won't lose your files by following the advice above, regardless of whether you overwrite or not.

If you won't listen to best practice advice, and have decided to for example modify the provided Cumulus web templates without allocating new names, then installing the whole release distribution will overwrite your edited file(s) with the standard file content provided by the developer. Therefore you need to do a customised approach where you select which files from the distribution to copy into your installation. If you have changed one or more web templates, you might think it safe just to omit the relevant files in the zip within folder '''web''', but some builds change the files in the '''webfiles''' folder too, and you need to retain consistency.

==== Updating when files within release might overwrite your own edits ====

To further explain the customised approach, here are some more examples.

===== web site files =====

If you have edited any files that sit on your '''web site''', then these can remain on your web site. However, if those web pages are generated from templates that you expect MX to process and upload for you, you do need to take special action. Maybe you edited a template to give the look you desire, or the content you want (e.g. adding rain this month to this month page, or combining this month and this year page).

The first step is to see if the release notice says that file has been revised, if it has not then it is easy to keep your edited file by not copying in the replacement file from within the zip. If the release revises any file you previously edited, take a backup of your edited file, before you copy the new file into your folder. You can then use a file comparing tool to see what has changed in the release and what you changed and hopefully manage to merge to a new file that keeps any functionality change in a new release and keeps your customisation. Do think about changing name of the template file, or placing it in a different folder, and using the '''Extra Files''' settings. That will make it easier for you next time you do an upgrade to a new MX build.

If you have done major customisation to the standard website then you probably have followed the guidance and stored your new web page templates in a different directory and you use '''Extra Files''' to specify where they are, so they cannot be overwritten, and the new MX will still find them. It might be that new web tags have been added since whatever build you were running before, and that you decide to edit your customised template file, but that can be done any time after you install the new MX build.

===== admin interface files =====

If you have done any customisation to the '''interface''' (perhaps you don't like seeing solar in the tables when you don't measure that) then again you can skip over these files when copying. Hopefully you will have copies of the files that you have customised of the ''interface folder'' so you have ability to copy them back into installation if you do overwrite with the release version.

'''You do have to be careful''', as many releases change the interface in some way, even if the change is not in the file you have customised, it might be in an asociated file, and all the various components of the interface have to work together as a coherent unit. For instance when feels like was added to MX, the api used for sending data from the MX engine to the admin interface was updated. In some releases, a new web page is added to the admin interface, with the consequence that all the navigation menus were adjusted in all web pages. Any HTML page in the admin interface may be edited to refer to a different styling page (so it, and the .css file, must be updated together) or to a different script (so the .HTML, and the .js file, must be updated together). The settings pages in the admin interface are dependent on the correct pair of json files to define the options or values that appear on that web page, so again all must be consistent.

To sum up, admin interface files are interdependent, and you cannot always update some, but not all, of the admin interface pages.

Be prepared to go back to the standard file for whatever you customised if something it depends upon has changed, after all you must not lose any vital functionality.

On my site, my own versions of interface files have a "_" (underline character) added to the start of the standard MX file name. This applies to both HTML pages, and JavaScript files that I have edited. I edit the menu items within my edited pages so those all go to my versions where I have a HTML customised page, leaving unchanged the menu items that can still go to a standard MX web page where I don't have my own version of the .HTML page. This makes it easy for me to navigate between my pages, as all of them link to my other pages. If I am on a standard MX page and want to go to one of my customised pages, I select the equivalent standard page, then edit the URL to add the underline and get easily to my page. This naming means I can always use a standard page instead of my customised page when I need to, and I never miss out on any new features.

== After an upgrade if you use the standard web template files ==

If you do not use the example web template files, provided as standard, with a MX release, the remainder of this section can be ignored.

If you use the third party [[CumulusMX and Cumulus1 UI style Multilingual Websites]] web pages, as maintained by BCJKiwi, follow any instructions in his package as to which of the files in this section are required and any announcements in his forum topic about when such files need to be upgraded.

=== web folder from zip ===

If you do use the example web templates to produce web pages for your web server, and you have copied all files from the release distribution ....

....MX will find any new web template files in your '''web''' folder, MX will process those template files, and upload the web pages produced, ''as before with no further action by you''.

=== webfiles folder from zip ===

 
<big>PLEASE COULD SOMEONE USING LATEST MX RELEASE ENSURE THIS IS KEPT UP TO DATE</big>

 

You do need a further action, if any files in this folder have been updated. The updated files must be uploaded to your web site.

This may be easy to forget if you use the standard web templates, because you thought that upload was a one-off and maybe you cannot remember what you did.

Certain third-party web-pages still use files from that folder, if one of the files they use has been updated, then ensure you have a backup of your web site before you upload the updated file, it should work, but it might not, and you might need to regress.

Let me go through the files currently in webfiles folder:
*'''weatherstyle.css''' has not been updated since its last update by Steve Loft in 2009.
*subfolder '''images''' contains 2 pictures that have stayed same since MX launch
*subfolder '''js''' contains one file or two files (depending on which MX release you are using:
**The standard web page '''trends.htm''' will only work if the correct version of any file here has been uploaded to your web site, and placed in a sub-folder "js" of where "trends.htm" is installed. .
*** BCJKiwi's user interface '''charts.php''' also requires the same JavaScript file (or files?), so upload the file(s0 anytime there is a change in a MX release.
** The file '''\CumulusMX\webfiles\js\cumuluscharts.js''' has changed in a lot of releases, it is updated whenever there is a change in the JSON files used for providing data to the charts, and you must use the right upgrade.
** The file '''historiccharts.js'' (it was introduced from release 3.8.7) is similar to previous script, but drives the historic chart functionality on your web server
*subfolder '''lib''' currently contains 3 folders:
**'''highstock''' - this folder is no longer needed on your web site (and the most recent MX releases have emptied it)
**'''jquery''' - this folder is needed for "trends,htm" to work, but it has not been updated since 2014. Both the files included are obsolete packages, no longer officially available, and there are no plans to replace them.
**'''steelseries''' - this folder has 3 sub-folders, I can only think of 2 MX releases when anything was changed here, and I don't anticipate any further changes.

= After upgrade - checking for bugs in MX or mistakes in your installation =

Start the new installation of MX and watch out for any errors - If the device you run MX on has a monitor, then look in the terminal/command window. In all cases look at the latest file in the [[MXdiags_folder|MXdiags folder]] to see if any errors are reported.

In newer releases of MX, also see [[ServiceConsoleLog.txt]]

Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.

== Updating if you use a virus Checker ==
You may find that virus checkers such as Windows Defender reject your new version of MX. They need to be told it is safe.

Updating MX to new version

2021-08-06T23:49:59Z

Cortmalaw: /* Latest release */

=Who this article is for=

Please be aware that if you want to move from Cumulus 1 to MX, you should read [[Migrating_from_Cumulus_1_to_MX]] article instead.

This article is for those who already use MX, and so are comfortable with basic MX installation and running.

=Who is not intended reader=

Cumulus MX has been updated so frequently in 2020, that you may be used to upgrading to a new build, and for you this article is not useful.

=Where to download a release distribution=

==Latest release==

Download release distribution zip from [[Software|the Software article in this Wiki]] for latest version.

Be aware that the developer needs to remember to update this link each time there is a new release.

An image that contains a '''Raspberry Pi lite operating system''' and a recent CumulusMX release already included, can be downloaded from the same wiki article. Not every CumulusMX release is provided as a Raspberry Pi image, so you may need to perform an update to get the latest release.

==Any release developed by Mark Crossley==

Download release distribution zip from https://github.com/cumulusmx/CumulusMX/releases for earlier versions.

=Introduction to upgrading MX=

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>
[[Category:Cumulus MX]]

You can download and unzip in advance, but cannot replace existing files while they are being used, so how you stop MX is in next two sub-sections.

My preference, after download, and unzip into a holding area, is to copy (it would be file transfer if you download on another device) over my existing installation all files except:
*CumulusMX.exe
*CumulusMX.exe.config
while MX is still running. I then stop MX for minimal time needed to replace just those two files before I restart MX. That way I minimise downtime, especially useful for a patch release when few files have changed, as it takes some time to replace all the files in the installation.

For simplicity, in guidance below, MX is stopped before any files are replaced.

==Upgrading on a Raspberry Pi (RPi) computer by commands from a Microsoft Windows computer (PC)==

I recommend you download WinSCP (this and PuTTy share some settings). This will allow you to connect your PC to your rPi and copy files back and forth. You can use it to copy the MX distribution, you download and unzip on your PC, onto the RPi. You can also use it to take a back-up of your RPI files onto your PC, and to pick certain files off your RPi. e.g. copy log files from [[MXdiags folder]] to your PC to read diagnostics etc.

You can download PuTTy (shares some settings with WinSCP) to enable you to open a terminal session and send commands to your RPi computer.

If you have Cumulus MX setup to run as a service then you will need to do one of these, should you wish to add debugging when the upgraded MX begins...
# Edit the CumulusMX service file (see [[MX_on_Linux#Running_as_a_service]]) to add the -debug parameter (do this if always want debugging on, not usually needed)
# Just set it from Program Settings | Logging Options (easiest for turning debug on when you need it and off when you don't need it)
# Edit the Cumulus.ini file and enable it in there (no longer recommended)

==Upgrading if you run MX as a service==

Don't forget to stop the service, before you do the upgrade.

For a Linux Operating system: <code>sudo systemctl stop cumulusmx</code>.

For Microsoft Windows Operating System: (a contributor who uses Microsoft Windows needs to modify this page)

==Upgrading if you run MX interactively==

If you do NOT run as a service, you will want to use '''Control and C''' in the terminal (or command) window running MX to make the software close tidily.

== Updating to the next MX release if you have not upgraded before ==

The simplest upgrade is from the immediate preceding build, and the steps required are summarised as follows:
# Download the release distribution zip for the next build (see later for where from)
#* My advice is to have a separate download location away from the location where you are installing/running the software; it can retain older releases to make regression simple if the new release proves to have a bug.
# Use '''Control-C''' to stop Cumulus MX (see later if running as a service)
# Take a backup of your complete existing MX installation (as it is not running, no files will be locked)
# Unzip the new distribution, overwriting the previous installation (the release announcement might ask you to delete obsolete files)
# Run any one-off batch scripts needed to prepare for upgrade
#* These might be needed if log files in the new release contain fields that were not in earlier release
#* These might be needed if you use optional database functionality (see later for examples)
# Do any actions that require you to use [[MX Administrative Interface|Admin Interface]] to change settings
# Do any one-off actions in relation to any files provided by MX for you to run a web site with the default pages
# Restart your Cumulus MX (consider running with '''-debug''' parameter if you are not sure the new build is bug free)

The remainder of this article explains all options for updating, and is thus less simple than above.

==Installer Option==

[https://cumulus.hosiene.co.uk/memberlist.php?mode=viewprofile&u=9016 HansR] on support forum has developed an multi-platform installer, see [https://cumulus.hosiene.co.uk/viewtopic.php?f=44&t=18916 Multiplatform Installer for CumulusMX] which makes life a lot easier if you do not wish to dive into the (file level contents) internals of CumulusMX.

#Copy the '''InstallCMX.exe''' to any directory you want, on the drive where you wish to install (or have previously installed) MX.
#Copy the CumulusMX release distribution zip(s) to that same directory, if you have not already done so. You may have more than one distribution in the same directory.
#*The install procedure gives you the possibility to select, or define, the Archive to install, and the location where to install.
#Stop CumulusMX
#Run '''InstallCMX''' and confirm / fill in (on the console) where you wish to install (or update) CMX. The default for Windows is C:\CumulusMX\ and for Linux it is : /home/CumulusMX. The Installation directory can be modified.
#* You can give the '''build number''', for the release distribution zip, to install as command line '''argument'''.
#Start CumulusMX

'''NOTE:''' On Windows you run the installer as any other command line executable and it is best to open a command window in which you start the installer. On Linux you run it on the command line as "mono ./InstallCMX.exe", the mono command can be omitted if mono is already active (e.g. if you run CumulusMX as a service, and stop it, mono remains active).
'''NOTE:''' In an existing installation with modified files, make sure those are in a different, either filename or folder (a safe place). If they have the same name as files in the distribution, they will be overwritten.
'''NOTE:''' Check in the <code>webfiles</code> directory to see if any files there have been modified, since your last upload to your web server. If so, move those new files to the website.

After the installation, there is a '''log file'''. Check the log file to see everything has gone well.
There is an '''ini file''' where you can control:
* NormalMessageToConsole=true or (default) NormalMessageToConsole=false
* TraceInfoLevel=Warning (out of: Error, Warning, Info, Verbose, None)

Any reactions (thank you, issues and questions) please post in the [https://cumulus.hosiene.co.uk/viewtopic.php?f=44&t=18916 download thread of the installer].

Modifications and additions on user request can be discussed (e.g. think about automated start/stop, upload of webfiles to the directory etc....), use the talk for this page.

==Upgrading if you are running MX on a Linux computer==

You might want to read galfert's post on the support forum [https://cumulus.hosiene.co.uk/viewtopic.php?p=148851#p148851 here] for the relevant Linux instructions in a concise format.

If you want more detailed information, on any Linux (including Raspberry Pi operating system) aspects of the upgrade instructions on this page, see [[MX on Linux]] page.

== Updating if you use the start/stop management script ==

This section contributed by ''Jank'' on support forum. Note the version on the forum might have been updated from the original included here.

1. look on [[Software|Software download page]], find the link to latest version, and fill out the '...' below appropriately as you run these 2 commands on your device where you do downloads:
<pre>cd /tmp
wget https://github.com/cumulusmx/CumulusMX/ ... .zip</pre>

2. Once that download is complete, start cumulusmx.sh with option -u
<pre>/home/pi/CumulusMX/cumulusmx.sh -u</pre>

3.When asked for the zip file, enter
<pre>/tmp/CumulusMXDist</pre> and hit the TAB Button

4.Choose the zip file with the CumulusMX upgrade and hit return.

5. Follow the on screen instructions

6. With each update component .....you can choose: [y]es, [n]o, [A]ll, [N]one, [r]ename

I would recommend select '''A''' as that will simply replace all files without further action.

CumulusMX will be restarted after upgrade completes.

You can check if the upgrade was successful by using option -s:
<pre> /home/pi/CumulusMX/cumulusmx.sh -s</pre>

=Considerations that determine when to upgrade=

Cumulus MX will nag you, in various places, to make you aware if you are not running the latest build. Some people will choose to upgrade as soon after a new release as they can. However, each upgrade does involve a period when MX is not running, and that causes some loss of data:
*for some weather station types readings taken every minute, or more frequently, are replaced by whatever period you station data logger records at;
*for other stations, without their own logging, all data is lost for the period when MX is not running.

Other, more cautious, people (like the present writer) will not upgrade each time a new release becomes available (and there are a lot of new releases in 2020), here are some of the reasons:
* you will see in the Cumulus Support Forum that many builds have bugs, and so you realise that it is better to stick with your fully working release, than install one with bugs;
* you may wish to avoid the loss of data mentioned above, by minimising the number of times that you stop MX;
* you may run MX on a computer that you rarely visit, perhaps even in a remote location not often visited, so you prefer to leave it untouched, rather than risk possibility of being unable to restart remotely;
* you may just have more important ways to use your time than updating your MX software, and some new builds might not give you any benefits that make it worthwhile to change your priorities.

It is perfectly possible to '''upgrade from rather old versions of MX, to the latest''', skipping intermediate versions, '''but there are some key versions that you should not skip over'''. This page, in subsequent sections, includes suggestions for which releases to install (and get running) before moving onto newer releases. This will be especially useful for those people who do not immediately upgrade to new releases, as per above suggestions.

===Advice about skipping versions===

Please see [[Updating_MX_to_new_version#Updating_from_a_very_old_version]] sub-section later on this page (and preceding sub-sections where relevant)

The important point to make here is that when you do an upgrade, you should copy in '''ALL''' files from the release distribution you want to run next. This is because there are dependencies between files within a distribution, so missing out any particular file may stop other files from working. However, if you are skipping versions, read the in-between release announcements to see if there are any one-off actions.

= What to read (and when) before upgrading =

== Upgrading from immediately preceding build ==

=== The release announcement ===

The release announcement is found in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic of the support forum.

*Generally, a release announcement WILL contain
*#An overall purpose for that particular release (e.g. fixing bugs or adding functionality)
*#Details of what functionality has been added
*#Details of what bugs have been fixed, or where the processing has been improved
*# (For older releases only) A list of the main files that have been added or amended in the release (excluding "updates.txt" which is amended in each release)
*#* (Publishing a list of changed files has been discontinued, because people were updating selected files, and often missed crucial ones, like '''CumulusMX.cfg''')
*Sometimes, a release announcement MAY contain
**Descriptions of one-off actions (like changing the schema if you use a database, or editing your web pages to take advantage of new web tags).
**Actual scripts to download and run to perform the necessary one-off actions.
*Be aware that it is worth while checking back on the release announcement for a few days after a release.
**It may have been edited because the original announcement forgot to mention something.
** It may have been edited to mention that some bugs have now been found
***That may mean you are advised to regress to an earlier version and use that
***It might mean that some supporting files in current version are wrong, and you only need to regress those named files
***There might be an emergency release to fix the bugs, and you need to upgrade to that emergency release
***Finally you might be given advice to avoid using certain parts of the functionality or take some other action until the next release is available.

===Other places where you can find information about release content ===

Although it is not always kept in step, a concise summary of all formal MX releases is available at [[Cumulus_MX_formal_release_versions]].

You can also view the latest [https://github.com/cumulusmx/CumulusMX/blob/master/Updates.txt Updates.txt].

===Deciding whether to upgrade to new release ===

This has been covered earlier in this article, but I repeat here 2 critical considerations:
*Any new development or change in a new version of MX might cause problems for some users. You might want to stick with the version you are already using unless you really need any new functionality or the fixes gained by upgrading.
*Also remember that there are bugs in (almost) all versions of MX, this is a large and complicated package, and the current developer has not been able to test all the code with all possible settings and all possible weather stations.

==Updating to a new minor build, skipping in-between minor builds==

For a minor version build either the associated version number does not change or only the final section changes (3.x.y to 3.x.z).

===Reading multiple release announcements===

If you are skipping some intermediate builds, then you will need to read each of the formal release announcements for builds after the build you currently use.

The other sources of release information mentioned above may be consulted as an alternative and may highlight something useful, but the formal release announcement contains what the developer wants you to know.

===Action to take when skipping minor intermediate builds===

You need to apply the cumulative actions recommended (i.e. apply any actions in sequence as listed for each intermediate build). Unfortunately, for Cumulus MX, one cannot assume that minor builds have no one-off actions associated with them. Luckily, most of the advice above for updating from immediately preceding build still applies.

==Updating to a new major version==

Generally, if the developer decides a new build warrants classification as a major version (i.e. 3.w.0) then the change being implemented is significant enough that updating might be more complex.

=== Examples of what might be classified as a major change===

*Additions to fields in log files (whilst older lines can continue to be read, you might want to consider [https://cumulus.hosiene.co.uk/viewtopic.php?f=18&t=18096 amending your standard data log] by populating the additional derivatives for older lines)
*Schema changes for database tables (if you don't use the standard tables, this might be irrelevant to you), the standard insert operations by MX can cope with extra columns in a table, but will fail if any column they try to update is missing
*Additions, changes, or removals, in configuration file (in general MX will ignore unrecognised parameters, but it does need correct values for those attributes it does recognise), see release announcements to discover if new lines in configuration file need you to add them manually or you need to use the admin interface to select the right setting for you
*New pages in Administrative Interface (additional pages require menu on every other page to be amended)
*Changes to existing pages in admin interface that involve changes to associated files (it is vital that all associated files are from same build)
*Catering for new weather station sensors, or new ways of communicating (this might not seem relevant to you)
*Any interface functionality changes (it may look the same, but what it does has changed)
*Additions to files being generated for web server (i.e. changes to template files, or additions to ''web'' or ''webfiles'' folders), even if you use your own versions of such files you may want to check the revisions

=== What you need to read ===

*Basically, check the corresponding release announcements for every version since the one you have been using before planning your upgrade.
**Make a note of any one-off actions required at particular in-between versions, remember these actions are only in forum release announcements.
**Although one-off actions will not be described in the Wiki (whether on the [[Software]] page or the [[Cumulus_MX_formal_release_versions]] page), the Wiki can give you an idea of what functionality has been improved to help you decide whether to upgrade.
*It is still worth reading all the points made above for updating from immediately preceding build.

=== Doing the upgrade===

# Download the release distribution
# Use '''control-c''' (or equivalent for MX running as service) to stop your existing MX software
# Backup your existing installation
# Do the on-off actions identified (e.g. changing schema of database tables, adding new configuration
# Unzip the distribution over existing one (alternative installation options listed later)
# Restart MX, considering whether to use '''-debug''' parameter in case the new release does not work for you
# Check the latest file in the MXDiags folder after an hour, to see if there have been any problems with reading from station, real-time uploads, standard uploads, or hourly uploads. (You may wish to recheck after an End of Day action has been done).

==Updating from a very old version==

Many people believe if it works, it don't need fixing. So they install whatever MX version is available when they start using MX and ignore all the bug fixing and new functionality being added, and stick with their existing installation.

Suddenly they realise that perhaps their version does lack functionality that would be useful to them. Maybe their version does not have an editor for correcting rogue extreme records and they realise correcting log files is something that is hard for them to do.

This section is therefore included to give advice on why you should not jump from an old version to the latest directly, but how it can be safely done in stages.

===Recommendations for staged updating===

<big>This section will need to be updated, new contributors are needed to keep this advice current.</big>

====If using 3.0.0 (the MX original beta)====

Upgrade to 3.5.1 by downloading it at https://github.com/cumulusmx/CumulusMX/releases/tag/b3072.

This gives you essential new functionality in the admin interface like editors for the log files and extreme records. But it also fixes multiple bugs in the beta you were using and adds some useful validation missing in the beta.

It does not involve any updates to the fields in the log files nor to the columns in any database tables you use.

It skips you past the problems in 3.5.0. It gives you benefits introduced in 3.1.x, 3.2.y, 3.3.z, and 3.4.w releases.

Now follow instructions below, for ''If using a 3.5.x release''

====If using either 3.1.x, 3.2.y, 3.3.z, or 3.4.w releases====

As above, update to 3.5.1 by downloading it at [[https://github.com/cumulusmx/CumulusMX/releases/tag/b3072 Mark's Github respository]]. The actual installation is done using the instructions above for simple next build upgrades. You can safely skip reading the intermediate release announcements, as there are no special one-off actions.

When you are happy running 3.5.1, then you should continue to upgrade, initially follow instructions in next sub-section.

====If using a 3.5.x release ====

My advice is to upgrade directly to 3.7.0 available at [https://github.com/cumulusmx/CumulusMX/releases Mark's Github repository].

You should skip the intermediate releases because several 3.6.y releases have bugs in them, and you want to avoid those problems (the bugs vary in severity between mistakes in calculations done by MX to particular functionality not working).

But there may be additional actions you need to do when moving from 3.5.x to 3.7.y, depending on what features you use in MX:
*there are no additional actions if '''you use standard web pages and you do not use database tables''', just enjoy the bug fixes and extra features after your update!
*'''If you use database tables''', be aware that the schema (Column names that must be in a table) varies between 3.5.x versions and 3.7.y versions.
**The updating database table features in MX will only work if all the columns named in each such upload update ''already exist'' in the database table it is trying to update.
**Look at individual release announcements for both 3.6.0 and 3.7.0, to see the SQL provided for adding the columns added at particular versions.
***At 3.6.0 the SQL was provided as a separate attachment to the release announcement (read [https://cumulus.hosiene.co.uk/viewtopic.php?p=142085#p142085 UpdateMYSQL-b3076.zip])
***At 3.7.0 the SQL was provided as part of the main zip (read [https://cumulus.hosiene.co.uk/viewtopic.php?p=145048#p145048 AlterSQLTables3098.sql])
***In both cases, the SQL provided assumes you are using the default names for database tables, it does not read [[Cumulus.ini]] to see whether you have selected different names for the tables (unlike ExportMySQL.exe and standard CumulusMX.exe uploads which check what tables names you have selected for updates).
*'''If you have your own customised web pages''', then there are changes to web tags that might lead to you needing to edit your web pages.
*'''If you use commas to separate integer and decimal parts of real numbers''', then various releases from 3.6.0 to 3.7.0 add "rc=y" to various web tags, that option will replace the decimal commas you use by decimal points that are required for some script languages (like the JavaScript used by HighCharts), and that makes it easier if you want to customise your web site.

When you are happy with running 3.7.0, then you should continue to upgrade, and the next sub-section describes what to do next.

====if using a 3.7.y release ====

If you are using 3.7.0 (there were no other builds in 3.7.y series), then you should upgrade directly to version 3.9.6 - build 3101.

Only 3.7.0 was ever released, it introduced a lot of changes, so that is why staged upgrades recommend that this version is implemented, and run for a while, before continuing to upgrade.

Version 3.8.0 was a major release, as it introduced the ability to run Cumulus MX as a service. However, there were bugs in the builds in all 3.8.z versions, and in some 3.9.x versions, so that is why you need to skip through intermediate builds below 3101.

'''IMPORTANT''' one-off actions needed:
* There is a one-off change described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=146957#p146957 v3.9.0 - b3095 release announcement] for those using RG-11 rain sensor.
* There is a further on-off change described in [https://cumulus.hosiene.co.uk/viewtopic.php?p=147329#p147329 release announcement for Patch release 3.9.1 - b3096] for those who use '''Mono''' to enable the executables to run.

When you are happy with running version 3.9.6 build 3101, you can continue to upgrade, and that will be covered in subsequent sub-sections (assuming someone is bothered to keep this article up to date).

====if using either 3.8.x or 3.9.y release====

See previous entry, upgrade directly to 3.9.6, or any later build, within 3.9.x, without any major change.

====From 3.9.y to 3.10.x====

The major aspects that changes at 3.10.1 (3.10.0 was withdrawn) are:
* Changes to settings
** You need to open the [[MX Administrative Interface]] and work through all pages in the '''Settings''' menu.
*Changes to web files in <code>CumulusMX/web</code>, <code>CumulusMX/webfiles</code> and introduction of <code>CumulusMX/webfiles-legacy</code>
**If you used the provided templates to produce web pages in earlier releases, or you had directly customised provided [[Customised templates|web templates]], these will no longer work
**Please see [[New Default Web Site Information|New Default Web Site Information page]] for further advice

====From 3.10.x to 3.11.y====

Treat like any other major version upgrade as described above.

= Knowing when a new release is available =

== CREDIT ==

Thanks to ''Billy'' on support forum for suggesting text for this section.

== Using forum notifications ==

As new releases are announced in [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 Cumulus MX Announcements and Download - PLEASE READ FIRST] topic, you can use the spanner tool to '''subscribe''' to this topic to receive notifications of a new post announcing a new release (or any other release-related announcement).

== MX terminal message ==

If ...
#...you have a monitor to see the terminal output from the Cumulus MX engine (Windows calls this either a command window, powershell window, or a terminal window depending on how you invoke it, for Unix-based implementations this is the output window when using the terminal functionality), AND
#...your device running MX is connected to internet, AND
#...your MONO (if not Windows) is not obsolete (SSL certificate out of date), AND
#...you restart MX
... then you will see a prompt when a new version of MX is available.

It is worth stressing that if you leave MX running, then this feature will leave you blissfully unaware that an update is available; it only checks when MX is restarted.

== MXDiags ==

In addition ...
#...if you can view the MXdiags file for the current session of MX, AND
#... MX is running with connection to the internet, AND
#...you restart MX
... if a new version of MX is available, the MXDiags file will say so (the message is not easy to spot as there is a lot of output before it, and variation in what output appears before it). Anyway, here is one example, just one example as in my experience '''the message has appeared at different places for each of the recent upgrades'''):
<pre>
2020-05-27 04:18:48.326 Calculating sunrise and sunset times
2020-05-27 04:18:48.326 Sunrise: 04:58:11
2020-05-27 04:18:48.326 Sunset : 21:19:54
2020-05-27 04:18:48.326 Tomorrow sunrise: 04:57:08
2020-05-27 04:18:48.326 Tomorrow sunset : 21:21:11
2020-05-27 04:18:48.388 You are not running the latest version of CumulusMX, build 3080 is available.
2020-05-27 04:18:48.763 Station type:</pre>

There is no message in whatever place it can appear ...
*... if you are using latest version, OR
* ... if you are not connected to the internet, OR
*... if you keep MX running all the time!

== Start/Stop script ==

When the '''Status''' option of this script is used, whenever a new release of MX is available, it will output a message.

== Dashboard in MX Admin Interface ==

In recent releases, one of the alarm indicators shown at the bottom of the dashboard page of the administrative interface, will flash red when you are not running latest build, and glow green when there is no newer release compared to the one you are running.

== Web Tags ==

Since 3.7.0 release of MX, two relevant web tags have become available:
* <#NewBuildAvailable> Returns a boolean value
** 0 - MX running the latest build available
** 1 - MX is running an earlier build than the latest public release
* <#NewBuildNumber> Displays the latest public release build number

= Recommended Actions when Updating =

== Back-ups ==

It is always best to take a backup of your existing MX installation before you do an upgrade, this allows you to regress back to the earlier version if either you mess up installing the new version, or the new version has a issue that prevents it working with the versions of other software (like MONO) that your installation uses.

== The two approaches ==

Contributors to this section are named in text.

Some people upgrade by just copying in the files that the release announcement says have changed, others copy in all files from the downloaded zip. The first should only be used with caution, files like '''CumulusMX.exe.config''' can change between versions, but not be mentioned in a release announcement, and the developer will have been making edits to files since the previous release, and might forget exactly which files have been edited between releases. Also you may be upgrading from an earlier version and therefore be skipping several intermediate releases.

You may be able to see the dates when files were changed within the zip and therefore be able to decide for yourself if you compare those dates with the previous release you were using if you have kept the download for the version you were using. However, do not assume that only files with later date are needed; in some releases the new build regresses one or more files and so a file with an older date is the correct one to retain.

===The rename old approach===

#The popular approach, recommended by many forum contributors, in many different posts (including at [https://cumulus.hosiene.co.uk/viewtopic.php?p=141763#p141763 this post by Mark Crossley for example] is to rename your current install directory, then unzip the new release, letting it create a new '''CumulusMX''' folder (or whatever name you prefer and specify in unzip options).
#However, you will find that this option is not being recommended any more, because it relies on you knowing which files (see next 2 points) you need to copy back.
#Copy across '''Cumulus.ini''' and (if you use it) '''string.ini''' into that new directory, and then copy the contents of the '''data''' and '''Reports''' directories from your ''current install'' to the new install.
#Don't forget to copy any other set-up files across too.
#*The advantage (as Mark says) is that you ensure you do use all the files in the new release, and don't miss out any he may have forgotten to mention in his release announcement.
#* A key advantage is that you don't retain files that an old release migt have needed but the new release does not use.
#*Another advantage (as PaulMy says [https://cumulus.hosiene.co.uk/viewtopic.php?p=140262#p140262 here for example]) is that you retain your old set-up intact and can easily restore it should you have a problem with new release.
#Various people advise that you don't delete your old installation for a week or so; as you may notice something from the older version that you haven't copied across!
#Check again that you copied across (you may not have all of these files, but if you have them in old installation then you need them in new installation) '''strings.ini''', '''twitter.txt''', '''Cumulus.ini''', and similar files in the same folder level as CumulusMX.exe, as well as all the files in the '''data''' and '''Reports''' sub-folders. Then, provided you are happy, you can delete the old release when you want to reduce clutter on your storage discs.

===The overwrite approach===

The general advice is that if you want custom pages for the administrative interface, or custom templates to process to produce your web pages, then these custom files should be given different names (and ideally be placed in different folders) to the standard files included in the release distributions. If you follow this advice, the approach described in this sub-section is the best for you, if you don't follow this advice, see later section on dealing with customised files.

#* if you have a lot of set-up files, or other custom files, (i.e. files with names that are not part of release), these won't be overwritten by files in the release distribution, but you do want to keep them;
#*or if you are downloading on a different computer, or on a different disc, to where you are running MX, it is easiest to keep your MX installation in the same place
#Note the forum administrator, David, [https://cumulus.hosiene.co.uk/viewtopic.php?p=140355#p140355 (see this post)] recommends this particular approach.
#After downloading a new release unzip it on the device/disc where you down load it. Next stop your existing Cumulus MX software and take a backup of your existing installation. After that, simply copy the files (optionally only those that have newer dates because they have changed) into the existing MX directory on the device where you run MX. Then you know all your existing files are there, and your MX can be run as before.
#The great advantage of this approach, and the reason that it is widely recommended as best, is that you can't lose any data or configuration files (i.e. files that are not part of the release distribution).
#Provided you did the backup, '''the only problem with this approach is that in some releases files are removed from the distribution''', yet unless you check carefully, this approach may ''leave files that are no longer required'' in your installation, and it is just possible you might continue to use the obsolete file instead of the intended alternative. Such a non-standard installation is difficult for others to support. So do check through file by file to ensure you only have files in the distribution you have just installed, not any from earlier distributions. The only files that you still want (that are not in distribution) will be those that either configure your system or contain your data in log files.
#*The updated files can be tracked by their modification date, some will be specified in the release notes (find them on [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17887 this forum]). There is a list indicating what files vary in [[Cumulus_MX_formal_release_versions|this Wiki article]].
#*In general, especially if updating a major release, it is best to overwrite with all files in zip, whether they are listed as changed or not. This ensures you have a consistent set of files, and avoids any issues when the developer does not correctly list all the files that have changed, or a file might be regressed to an earlier version and not have a newer date than the file in your previous installation.

====Example: downloading on PC and installing on pi ====

#On your pc: Download zip either from [[Software]] for latest version or from https://github.com/cumulusmx/CumulusMX/releases for earlier versions.
#On your pc: Use Filezilla (or similar file transfer program, or it might even be a copy over network depending on way set up) to transfer zip to pi (e.g. <tt>FileZilla CumulusMXDist3089.zip to /home/pi</tt>), but remember you might want to install to a different location (perhaps on an external USB drive, or SSD)
#Control C on pi to stop MX
#On pi go to directory where zip now is, for example it might be <tt>cd /home/pi</tt>
# Unzip the installation over your existing installation, by running on your Raspberry Pi this instruction: <tt>unzip -o CumulusMXDist3089.zip</tt>
# Restart MX
# Remove any files that were needed by earlier releases but release announcement says are not needed by the release you are installing

===The customised approach===

If you edit a file that is included in the release distribution, you should give it a different name (e.g. I have placed an underline in front of original file name for some of the files I edited in the admin interface), and/or place it in a different folder (e.g. I place all the cumulus templates I have created in a folder called '''cumulus_Templates'''). If you follow this advice, then you won't lose your files by following the advice above, regardless of whether you overwrite or not.

If you won't listen to best practice advice, and have decided to for example modify the provided Cumulus web templates without allocating new names, then installing the whole release distribution will overwrite your edited file(s) with the standard file content provided by the developer. Therefore you need to do a customised approach where you select which files from the distribution to copy into your installation. If you have changed one or more web templates, you might think it safe just to omit the relevant files in the zip within folder '''web''', but some builds change the files in the '''webfiles''' folder too, and you need to retain consistency.

==== Updating when files within release might overwrite your own edits ====

To further explain the customised approach, here are some more examples.

===== web site files =====

If you have edited any files that sit on your '''web site''', then these can remain on your web site. However, if those web pages are generated from templates that you expect MX to process and upload for you, you do need to take special action. Maybe you edited a template to give the look you desire, or the content you want (e.g. adding rain this month to this month page, or combining this month and this year page).

The first step is to see if the release notice says that file has been revised, if it has not then it is easy to keep your edited file by not copying in the replacement file from within the zip. If the release revises any file you previously edited, take a backup of your edited file, before you copy the new file into your folder. You can then use a file comparing tool to see what has changed in the release and what you changed and hopefully manage to merge to a new file that keeps any functionality change in a new release and keeps your customisation. Do think about changing name of the template file, or placing it in a different folder, and using the '''Extra Files''' settings. That will make it easier for you next time you do an upgrade to a new MX build.

If you have done major customisation to the standard website then you probably have followed the guidance and stored your new web page templates in a different directory and you use '''Extra Files''' to specify where they are, so they cannot be overwritten, and the new MX will still find them. It might be that new web tags have been added since whatever build you were running before, and that you decide to edit your customised template file, but that can be done any time after you install the new MX build.

===== admin interface files =====

If you have done any customisation to the '''interface''' (perhaps you don't like seeing solar in the tables when you don't measure that) then again you can skip over these files when copying. Hopefully you will have copies of the files that you have customised of the ''interface folder'' so you have ability to copy them back into installation if you do overwrite with the release version.

'''You do have to be careful''', as many releases change the interface in some way, even if the change is not in the file you have customised, it might be in an asociated file, and all the various components of the interface have to work together as a coherent unit. For instance when feels like was added to MX, the api used for sending data from the MX engine to the admin interface was updated. In some releases, a new web page is added to the admin interface, with the consequence that all the navigation menus were adjusted in all web pages. Any HTML page in the admin interface may be edited to refer to a different styling page (so it, and the .css file, must be updated together) or to a different script (so the .HTML, and the .js file, must be updated together). The settings pages in the admin interface are dependent on the correct pair of json files to define the options or values that appear on that web page, so again all must be consistent.

To sum up, admin interface files are interdependent, and you cannot always update some, but not all, of the admin interface pages.

Be prepared to go back to the standard file for whatever you customised if something it depends upon has changed, after all you must not lose any vital functionality.

On my site, my own versions of interface files have a "_" (underline character) added to the start of the standard MX file name. This applies to both HTML pages, and JavaScript files that I have edited. I edit the menu items within my edited pages so those all go to my versions where I have a HTML customised page, leaving unchanged the menu items that can still go to a standard MX web page where I don't have my own version of the .HTML page. This makes it easy for me to navigate between my pages, as all of them link to my other pages. If I am on a standard MX page and want to go to one of my customised pages, I select the equivalent standard page, then edit the URL to add the underline and get easily to my page. This naming means I can always use a standard page instead of my customised page when I need to, and I never miss out on any new features.

== After an upgrade if you use the standard web template files ==

If you do not use the example web template files, provided as standard, with a MX release, the remainder of this section can be ignored.

If you use the third party [[CumulusMX and Cumulus1 UI style Multilingual Websites]] web pages, as maintained by BCJKiwi, follow any instructions in his package as to which of the files in this section are required and any announcements in his forum topic about when such files need to be upgraded.

=== web folder from zip ===

If you do use the example web templates to produce web pages for your web server, and you have copied all files from the release distribution ....

....MX will find any new web template files in your '''web''' folder, MX will process those template files, and upload the web pages produced, ''as before with no further action by you''.

=== webfiles folder from zip ===

 
<big>PLEASE COULD SOMEONE USING LATEST MX RELEASE ENSURE THIS IS KEPT UP TO DATE</big>

 

You do need a further action, if any files in this folder have been updated. The updated files must be uploaded to your web site.

This may be easy to forget if you use the standard web templates, because you thought that upload was a one-off and maybe you cannot remember what you did.

Certain third-party web-pages still use files from that folder, if one of the files they use has been updated, then ensure you have a backup of your web site before you upload the updated file, it should work, but it might not, and you might need to regress.

Let me go through the files currently in webfiles folder:
*'''weatherstyle.css''' has not been updated since its last update by Steve Loft in 2009.
*subfolder '''images''' contains 2 pictures that have stayed same since MX launch
*subfolder '''js''' contains one file or two files (depending on which MX release you are using:
**The standard web page '''trends.htm''' will only work if the correct version of any file here has been uploaded to your web site, and placed in a sub-folder "js" of where "trends.htm" is installed. .
*** BCJKiwi's user interface '''charts.php''' also requires the same JavaScript file (or files?), so upload the file(s0 anytime there is a change in a MX release.
** The file '''\CumulusMX\webfiles\js\cumuluscharts.js''' has changed in a lot of releases, it is updated whenever there is a change in the JSON files used for providing data to the charts, and you must use the right upgrade.
** The file '''historiccharts.js'' (it was introduced from release 3.8.7) is similar to previous script, but drives the historic chart functionality on your web server
*subfolder '''lib''' currently contains 3 folders:
**'''highstock''' - this folder is no longer needed on your web site (and the most recent MX releases have emptied it)
**'''jquery''' - this folder is needed for "trends,htm" to work, but it has not been updated since 2014. Both the files included are obsolete packages, no longer officially available, and there are no plans to replace them.
**'''steelseries''' - this folder has 3 sub-folders, I can only think of 2 MX releases when anything was changed here, and I don't anticipate any further changes.

= After upgrade - checking for bugs in MX or mistakes in your installation =

Start the new installation of MX and watch out for any errors - If the device you run MX on has a monitor, then look in the terminal/command window. In all cases look at the latest file in the [[MXdiags_folder|MXdiags folder]] to see if any errors are reported.

In newer releases of MX, also see [[ServiceConsoleLog.txt]]

Also keep an eye on the support forum for first few days, some releases do have bugs, as developer cannot test all possible configurations.

== Updating if you use a virus Checker ==
You may find that virus checkers such as Windows Defender reject your new version of MX. They need to be told it is safe.

MX on Linux

2021-01-31T18:22:43Z

Cortmalaw: /* Which Raspberry Pi to buy */

[[Category:Cumulus MX]]
=Using MX on UNIX-derived Operating Systems=

MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>

==This article focuses on a computer called the Raspberry Pi==

Although the article focusses on one computer type, the Raspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to another Unix-derived devices.

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" MX difficult.

The same forum reveals few posts from people struggling with setting up the Raspberry Pi, and several posts reporting success with using MX on this small computer.

==Précis==

{{TOCright}}
*The Raspberry Pi is a simple computer that is far easier to learn than a complicated machine like a Personal Computer (PC) running Windows.
*You can choose either to install the Windows operating system on your Raspberry Pi or to install the simpler Raspberry Pi operating system (based on debian Linux).
**This article focusses on the latter as another article covers Windows.
**You don't need to learn much Linux, but this article does cover some commands.
*The Raspberry Pi is ideal to run Cumulus MX
**The Raspberry Pi is a computer that is better for the environment, unlike a PC manufactured with lot of components, and a PC wastes a lot of electricity if left running.
**Downloading the release distribution, and unzipping the files, is the same on any device
**On Linux you need to (simply) manually install one extra component (Mono-complete), while the equivalent component (.NET) is automatically installed on Windows.
**Running MX is same on any device (precise command syntax to start it varies, but what MX does when running does not depend on device)
*It is simplest to connect keyboard and monitor to the Raspberry Pi so all actions are done directly on it.
*Some optional topics are also covered.
**One option covered is adding a web server and a database server
**Another option discussed is using a PC to control a "headless" Raspberry Pi (i.e. one without keyboard and without monitor).

==Introduction==

It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).

In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi.

The Apple Mac runs its own version of Unix, and while standard Unix uses Line_Feed to terminate lines in files, the Mac uses Carriage_Return. Hopefully someone will write an article about the Mac in this Wiki, but in meantime this is closest you can get.

The article will give you some guidance on:
*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 optional extras!

=Which Raspberry Pi to buy=

A standard desktop computer consumes at least 200 Watts of power (that is when it is idle, it will increase depending on peripherals attached and 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. A Pi model 4 B (the latest model at time of writing) consumes 2.85 to 80 W depending on whether it is idle or working hard. Although Cumulus MX does not need to run 24/7, derived values like highest, lowest, average, and so on, will be more accurately calculated if MX is left running. Although the Pi is not the only small computer model available, it is probably the most popular and the easiest one to use if you do want to run MX all the time and not wreck the planet!

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 sections contain just suggestions on how to decide, there is no intention to force any single decision. This article focusses on those who buy a Raspberry Pi as a small computer, who might want to use it for other tasks like word processing, and for novices who feel happier to connect a screen and keyboard. This article is less useful if you want to own 2 computers and run your Pi headless by sending commands from your other computer, see [[Raspberry Pi Image]] article instead.

==First make a list of what you need==

*Do you want to use a mouse and key board so that you can use your Raspberry Pi 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)
** This also applies if you want to be able to plug in a USB stick (perhaps for holding/transferring files between devices, e.g. Cumulus configuration and data folder files; this will save wear on 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 pi in headless mode, a wired or wireless connection to your LAN is needed for your other device to communicate with the Pi
*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 use a larger time 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 choose between the model 0W with one USB socket, and the model 3 B+ with 4 USB sockets depending on whether you might want to use another USB socket ever
** 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. Here, I won't describe all the different models, but concentrate on just 2 (Pi Zero W and 3 B+) for simplicity. However, note that 3 B+ costs only pennies less than the much-more-powerful Model 4; it is probably about to become obsolete [Jan 2021]. Model 4 has all the same advantages as described for Model 3 B+, except that it may use more power.

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 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 so good). Having an Ethernet connection, as explained later, makes it possible to easily install the Windows Operating System on your Raspberry Pi on first boot.

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

== What else to buy ==

You can buy just the Pi, which is just a circuit board, or a kit that includes other components.

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 that you can fit the board into to protect it.

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.

You may need to buy a power supply.
* This could be an official Raspberry Pi power supply.
* Alternatively, other power supply units that have a micro USB connector will often suffice, as the power consumption of a Pi (whichever model) is fairly small, but it will be powered on 24/7, so a low power consumption ‘switched mode’ type is preferred – i.e. one that does not become warm when plugged in with nothing attached.
** You may have a suitable one left over from an earlier mobile phone.
** A Pi 3 B+ running other tasks may require a more powerful power supply.
** A Pi 4 needs more power and has a USB C connector.

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 to connect to your weather station (the Pi model Zero requires a micro USB, the Pi model 3 requires a standard A end USB) and your station probably has a USB A end connection.
* 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.

If you do choose a model 3 (or later), consider whether you do want to buy a USB mouse and USB keyboard to use with it.

Finally, you may wish to buy a second micro-SD unit as a spare, or some other USB connected (or network connected) storage for back-ups and extra storage needs.

= Setting up your Pi =

== Image alternative ==

If you are never going to use a keyboard nor TV (or other monitor) with your Raspberry Pi, there is now an alternative to installing operating system, mono, and MX separately, a single '''image''' that contains all elements needed can be downloaded from the [[Software#Current_Release|Software page Current_Release section]], read about using it in [[Raspberry_Pi_Image]] article. I will just stress here, that following this alternative option, provided by developer, installs the '''Raspberry Pi Lite Operating System'''. Also with this option if you are migrating from another computer you still need to add [[Cumulus.ini]], [[strings.ini]], all files in [[:Category:Log Files|data folder]], and any files in the Reports folder by file transfer from your other device to the Pi.

== Doing it 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 [https://www.raspberrypi.org/documentation/setup/ the manufacturer's web site], the manufacturer actually also publishes the same documentation on [https://github.com/raspberrypi/documentation/blob/master/setup/README.md their github page].
*If you have brought your Pi from a distributor, their web site (e.g. [http://www.okdo.com/gettingstarted '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 this article, each step in installation is covered, in the sections that follow. Obviously, this article is trying to balance the needs of a novice with the needs of someone who wants to plug holes in their existing knowledge, that need to be comprehensive means it might not seemed to be aimed exactly at what you need. ''Anyone who feels able to improve this article is welcome to edit it''.

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

#A Pi will work with either a class 4 (only 4 times faster), or a class 10, micro-SD card.
#Just for the standard install you need a card with a '''minimum of 8 GB'''.
#Given we are going to add Mono and Cumulus MX to the card, I advise you buy a card with at least 16 GB (as 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 [https://github.com/raspberrypi/documentation/blob/master/installation/noobs.md NOOBS (Novel Out of Box Software)],
* or pre-installed with the Raspberry Pi operating system.

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 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) and that will make your life simpler than buying a blank micro-SD card and having to down load and add the operating system 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.

=== The Operating System ===

As said before, a number of operating systems can be installed on your Pi, even Windows.

To keep this article simple, I will assume you have bought a micro-SD card either pre-installed with an operating system (OS) so you are ready to go, or you used NOOBS (as described earlier) to install your chosen OS.

If you do need to install any operating system you choose, normally the instructions will be found from where you download the system you have selected. If you have brought a card without NOOBS, you can download/install the Raspberry Operating System Buster yourself, following either instructions on the [https://www.raspberrypi.org/downloads/ Raspberry Pi download page], those at [https://thepihut.com/blogs/raspberry-pi-tutorials/the-raspberry-pi-tutorial-beginners-guide this supplier's tutorial guide], or [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 those in Cumulus support forum]. To save you looking any of those up, the next sub-section summarises what you need to do.

==== How to add Raspberry Operating System to a card yourself ====

*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)
*Download the latest version of the Raspberry Pi operating system you have selected from https://www.raspberrypi.org/downloads.
*That imager is run on any device, say your pc, 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).
*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, the larger Linux partition is invisible to Windows, the optional third partition uses up any space left on a larger micro-SD card and appears as "data" under "media" in the Linux file structure).

==== 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 card that determines which Raspberry Pi Operating System version is set up:
*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

Be aware that many such 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).

=== Wireless Network ===

How this is set up depends on your Pi model, and the operating system that is loaded on it,
*it may on first boot ask you to enter your wireless network details,
*it may list the wireless networks it finds and ask you to choose from the listed SSID,
*it might not prompt you so you need to use the configuration tool (see next sub-section),
*or you might need to click on an icon with two red crosses.

Note that there is also a Wi-Fi network country which must be set.

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

=== Other configuration ===

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),
*or by running a command <tt>sudo raspi-config</tt> in Terminal.

==== Mandatory configurations ====

Within the Raspberian configuration utility, you will see an option to change password. You will want to do this so nobody can hack into your Raspberry Pi computer. You will need to enter the new password twice before it replaces the old one.

The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name.
*The name can most easily be changed within the Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name.
*but it can also be edited by opening the file where it is stored using <tt>sudo nano /etc/hostname</tt>.

Network options can also be configured by clicking an icon on the Pi (this icon might be two red crosses if network settings are missing, two parallel arrows if the network settings are not correctly set, or the wireless symbol if your wireless network is working).

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

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

====To leave configuration====

Select ‘Finish’.

== 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. Before we can install Mono, there are other packages required and these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian 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):
<pre>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
</pre>

For Raspberry Operating System 10 (buster):
<pre>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</pre>

=== Checking all packages are up to date ===

'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.

=== Installing instruction ===

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

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

The "sudo" part of this gives us rights, "apt-get" is one of the ways to search the Raspberry repository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.

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

== Downloading and Unzipping MX Distribution ==

For simplicity, MX is installed into standard Pi user's home directory here. You might instead choose to install it on an external drive which has two significant advantages:
#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 are less likely to lose your operating system off your micro-SD card
#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 data

Both the optional "data" directory created by NOOBS and any external drive appear within "/media/" in the file structure, but the exact path depends on your set-up and can't be predicted here.

The procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution.
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#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 [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

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

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

'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
** It is important to see that whilst most settings can be done in the former, a few are read-only and must be done in latter
**Also 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 upload option; these are just the 2 most common errors)
*For general advice relating to [[Cumulus MX]], follow that link
*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
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions

'''If you have used Cumulus before''', but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
*Cumulus.ini
*strings.ini

The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder). Be aware that the characters terminating each line may need editing (see next sub-section).

Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].
*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 <tt>sudo chmod -R ugo+rw /var/www/html</tt> 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. If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed Windows on your Raspberry Pi. Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, then ideally all your files should be edited so they simply use Line_feed to terminate all lines. This can be easily done in an editor like Notepad++ that is designed for computer files.

The novice does not need to worry about changing end of line characters, it is advisable but not essential (as the Pi will treat the CR as a character it does not display)

To get the entire content of your existing '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).

First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).

== Running Cumulus MX ==

(When these notes were written, there were topics in the support forum about ways to use scripts for starting/stopping MX, but the distribution did not include any such controlling scripts. The latest MX version includes a script allowing MX to be run as a service, and perhaps someone would be kind enough to expand the first sub-section).

=== Running as a service ===

(awaiting someone to explain this)

=== Running with a terminal session left open ===

Whichever operating system you are using, to run MX requires an instruction that changes to the directory where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].

The simplest instruction to run Cumulus MX is <tt>cd CumulusMX && sudo mono CumulusMx.exe</tt>. 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 so that terminal session continues running.

== 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 access to many features including shutdown options.

=== sudo ===

Almost all instructions, given in this article, start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows a standard Pi user to do tasks that otherwise only work for the root user. You use it as a prefix to almost every command you type in terminal mode. There 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 '''/'''.

To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.

To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder. Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

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

=== nano ===

There are various text editors available on a Pi, '''nano''' is a simple one.

Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file.

Use prefix of 'sudo' to give you access to any file, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

When in nano you select to write out to a file, it allows you to change the file name shown. If you choose to save as another file, you will be asked if the new name is correct (again type '''Y''' to continue saving).

Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.

The full syntax is <tt>sudo nano -B Path_file_name</tt> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

You will probably find it useful to type <tt>sudo nano /etc/nanorc</tt> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options

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 <tt>sudo nano /var/www/html/index.php</tt>. 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.
*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.

=== 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 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 article simple, I accept the Operating System that is installed by NOOBS, even if it is not the latest available from the Raspberian web site, I 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 I use 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 article is aimed at, then you should know how to install the latest version from the appropriate web sites.

=== removing an unwanted file ===

You can remove a file or a folder with various commands, including <tt>sudo rm filename</tt>.

=== 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 [https://raspberrytips.com/raspberry-pi-commands/ this web page] or [https://www.ubuntupit.com/useful-raspberry-pi-commands/ 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 [https://github.com/magimat/rpi-cumulusmx rpi-cumulusmx] and a very old one at [https://github.com/Apollorion/CumulusMX-Docker 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 <tt>sudo apt update && sudo apt upgrade -y</tt> to ensure all packages are up to date before we attempt to add another package.
*I remind you here that this does not update everything on your computer to the latest versions available for a Pi, that requires a different (more risky) command not taught here.
*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;
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#*If you do find out what the first database is used for, please update the Wiki article on it!
#The second database is the Weather Diary [[Weather Diary|documented here]] added by Mark Crossley. Also see [https://cumulus.hosiene.co.uk/viewtopic.php?f=37&t=17919 in the support forum] for a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.
#* The [[MX Administrative Interface|Admin Interface]] provides a page to view, or edit, 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 <tt>sudo apt install phpliteadmin</tt>. 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.

I find the admin interface is not reliable for updating the weather diary; it often fails to store an update, without giving any error either on the editing screen or in the MXDiags file. So, I prefer to use phpliteadmin for making changes to the Weather Diary database now. I can use it 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:
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <tt>sudo apt-get install nginx -y</tt>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <tt>sudo apt-get install lighttpd -y</tt>.

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

*PHP is not the only script language available, but it is quite comprehensive
**being able to be used either in a fairly simple way by non-technical people
**or in an object-oriented way for those more technical to achieve success with more complex scripts.
*The simplest instruction to install it is <tt>sudo apt install php -y</tt>, which version you get depends on your Pi and its operating system.
*To check which PHP modules have been installed by the above command, type <tt>php -m</tt>.
*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 <tt>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</tt>. 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 <tt>php -v</tt> 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 <tt>php - f <file_name></tt>. 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'):
<pre>#!/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
</pre>

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

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 <tt>sudo mysql_secure_installation</tt>. That brings up a screen:
# where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
# next type '''Y''' to signify we are going to set a new password for '''root''',
# next type in a new password that you will not forget,
# 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''
# 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,
# 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,
# 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)

#Start the install with <tt>sudo apt install phpmyadmin -y</tt>.
#The PhpMyAdmin installer will ask some questions.
#Use your tab key to select <Yes> when it asks whether you want to configure with '''dbconfig-common'''.
#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 <tt>sudo apt install adminer</tt> (I leave you to work out the commands needed after that).

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

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 [[MX_Administrative_Interface#MySQL_settings|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.

<pre>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;</pre>

As I type this, Cumulus MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore in this situation it will crash out (with message press Enter to close).

=== Commands to ensure PhpMyAdmin will work ===

The following sequence of commands will
* add the mysqli module to our php install,
*will restart apache,
*will create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser,
*will give the standard user (pi) ownership of the database files and the web pages:

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

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

You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi 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:
#real-time
#standard interval
#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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe monthly</tt> to run the executable. The first parameter is "monthly" even if the table has a different name.
#if the table name is defined in the admin interface, and the table already exists in the database with the correct columns defined, then the executable will use that table.
#There is an optional second parameter that specifies the log file name to read.
#*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"),
# 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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe dayfile</tt>.

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 <tt>sudo service apache2 restart</tt> or (if we just want the Apache configuration reloaded) by typing <tt>sudo systemctl reload apache2</tt>. Similar commands apply for other web servers.

We will need to restart Apache (or whichever web server we installed) any time we change our php.ini files, database passwords, and anything else that is checked when the web server starts.

== 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 Pi====

On your Pi, there are various applications that you can run with graphical interfaces, these let you achieve what you want by on screen selections, without having to learn what Linux commands to type in. You might wish to use these when you are operating your Pi in a headless state (without keyboard or monitor), so you want to see these graphical interfaces on your PC. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.

An alternative way to work on your Pi is its its terminal mode. This lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, and can therefore allow you to achieve tasks where a graphical interface fails because of the ownership of the part of the file structure where your action is taking place. The commands you type into a terminal screen on a Pi can also be typed into a terminal screen on your PC, and you will see the same responses. For this to work, you need to switch Secure Shell Home (SSH) on as that is what controls access over a network. This article explains most aspects of SSH in the next few sub-sections.

==== 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 <tt>touch ssh</tt>, 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 <tt>ssh pi@raspberrypi</tt> to get access to default user in your Pi.

(As an alternative for Windows operating system, you can install PuTTY, this has the advantage that you can enter the connection settings into it, and configure various other options, and these are remembered, so might make it easier to use. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).

When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. The action that result from any key combinations depend on your terminal application, not just whatever you are running on your Pi. Your mouse can't affect cursor location, but the mouse might be needed to select text, the left click might copy what is selected, and the right click might paste (what is in your PC's clipboard) at current cursor position.

You can use SSH access from your PC:
* when you need to edit a file on your Pi,
*or do a file transfer between Pi and PC or vice versa.

=== Running MX from your PC ===

If you choose to use the simple <tt>sudo mono CumulusMX.exe</tt> command in a terminal (or command window or Powershell) session on your PC, remember MX will detect if that session is ended and will shut down MX. This means if you want to keep MX running you need to keep your session on your PC running and you loose the advantage of saving electricity by running MX on a PI because your PC remains on.

As I type this a new release 3.8.0 is to allow MX to run as a service, and a future release is planned to change the associated script, so anything I write here might become obsolete, and the next sub-section gives you some links to the support forum about alternatives to the new feature. Hopefully, someone will edit this article, when instructions have settled down and won't change on next release. Basically, the ability to run MX as a service, means that MX actually runs independent of the session that starts or stops the service; and therefore implies you can shut down your PC without stopping MX.

Hopefully someone will add notes to this article about the running as service option. I have not tried it, so I cannot add such notes.

=== Older information about using a PC and a PI ===

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

===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:
<pre>ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
ssid="YourNetwork"
psk="YourNetworkPassword"
key_mgmt=WPA-PSK
}</pre>

*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 [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).

===Downloading MX distribution on PC===

If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).

MX on Linux

2021-01-31T17:56:25Z

Cortmalaw: /* First make a list of what you need */

[[Category:Cumulus MX]]
=Using MX on UNIX-derived Operating Systems=

MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.

<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>

==This article focuses on a computer called the Raspberry Pi==

Although the article focusses on one computer type, the Raspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to another Unix-derived devices.

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" MX difficult.

The same forum reveals few posts from people struggling with setting up the Raspberry Pi, and several posts reporting success with using MX on this small computer.

==Précis==

{{TOCright}}
*The Raspberry Pi is a simple computer that is far easier to learn than a complicated machine like a Personal Computer (PC) running Windows.
*You can choose either to install the Windows operating system on your Raspberry Pi or to install the simpler Raspberry Pi operating system (based on debian Linux).
**This article focusses on the latter as another article covers Windows.
**You don't need to learn much Linux, but this article does cover some commands.
*The Raspberry Pi is ideal to run Cumulus MX
**The Raspberry Pi is a computer that is better for the environment, unlike a PC manufactured with lot of components, and a PC wastes a lot of electricity if left running.
**Downloading the release distribution, and unzipping the files, is the same on any device
**On Linux you need to (simply) manually install one extra component (Mono-complete), while the equivalent component (.NET) is automatically installed on Windows.
**Running MX is same on any device (precise command syntax to start it varies, but what MX does when running does not depend on device)
*It is simplest to connect keyboard and monitor to the Raspberry Pi so all actions are done directly on it.
*Some optional topics are also covered.
**One option covered is adding a web server and a database server
**Another option discussed is using a PC to control a "headless" Raspberry Pi (i.e. one without keyboard and without monitor).

==Introduction==

It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).

In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi.

The Apple Mac runs its own version of Unix, and while standard Unix uses Line_Feed to terminate lines in files, the Mac uses Carriage_Return. Hopefully someone will write an article about the Mac in this Wiki, but in meantime this is closest you can get.

The article will give you some guidance on:
*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 optional extras!

=Which Raspberry Pi to buy=

A standard desktop computer consumes at least 200 Watts of power (that is when it is idle, it will increase depending on peripherals attached and 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 Watt when running tasks or connected to peripherals. A Pi model 4 B (the latest model at time of writing) consumes 2.85 to 80 Watt depending on whether it is idle or working hard. Although Cumulus MX does not need to run 24/7, derived values like highest, lowest, average, and so on, will be more accurately calculated if MX is left running. Although the Pi is not the only small computer model available, it is probably the most popular and the easiest one to use if you do want to run MX all the time and not wreck the planet!

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 sections contain just suggestions on how to decide, there is no intention to force any single decision. This article focusses on those who buy a Raspberry Pi as a small computer, who might want to use it for other tasks like word processing, and for novices who feel happier to connect a screen and keyboard. This article is less useful if you want to own 2 computers and run your Pi headless by sending commands from your other computer, see [[Raspberry Pi Image]] article instead.

==First make a list of what you need==

*Do you want to use a mouse and key board so that you can use your Raspberry Pi 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)
** This also applies if you want to be able to plug in a USB stick (perhaps for holding/transferring files between devices, e.g. Cumulus configuration and data folder files; this will save wear on 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 pi in headless mode, a wired or wireless connection to your LAN is needed for your other device to communicate with the Pi
*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 use a larger time 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 choose between the model 0W with one USB socket, and the model 3 B+ with 4 USB sockets depending on whether you might want to use another USB socket ever
** 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. Here, I won't describe all the different models, but concentrate on just 2 for simplicity.

The model Zero W is appealing as it has 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 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 interfaces built in, such as 4 USB 2 ports (useful if you want to connect a weather station using USB and connect a keyboard).

While both models support wireless links 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 you want to install a web server, on your Pi). Having an Ethernet connection, as explained later, makes it possible to easily install the Windows Operating System on your Raspberry Pi on first boot.

* Raspberry Pi Zero W
** Pi Zero W has WiFi and one micro-USB port which is all that is needed for headless running.
** 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, so the connectivity and speed of the actual Pi are less important
* Raspberry Pi Three B Plus
** 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 Three B Plus 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 a monitor and 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 Four has more capabilities, but may be less appealing as it also consumes more power.

== What else to buy ==

You can buy just the Pi, which is just a circuit board, or a kit that includes other components.

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 that you can fit the board into to protect it.

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.

You may need a power supply.
*This could be an official Raspberry Pi power supply.
*Alternatively, any power supply unit that has a micro USB connector will do, the power consumption of a Pi (whichever model) is fairly small, but it will be powered on 24/7, so a low power consumption ‘switched mode’ type is preferred – i.e. one that does not become warm when plugged in with nothing attached.
**You may have a suitable one left over from an earlier mobile phone.

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 to connect to your weather station (the Pi model Zero requires a micro USB, the Pi model 3 requires a standard A end USB) and your station probably has a USB A end connection.
*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.

If you do choose a model 3 (or later), consider whether you do want to buy a USB mouse and USB keyboard to use with it.

Finally, you may wish to buy a second micro-SD unit as a spare, or some other USB connected (or network connected) storage for back-ups and extra storage needs.

= Setting up your Pi =

== Image alternative ==

If you are never going to use a keyboard nor TV (or other monitor) with your Raspberry Pi, there is now an alternative to installing operating system, mono, and MX separately, a single '''image''' that contains all elements needed can be downloaded from the [[Software#Current_Release|Software page Current_Release section]], read about using it in [[Raspberry_Pi_Image]] article. I will just stress here, that following this alternative option, provided by developer, installs the '''Raspberry Pi Lite Operating System'''. Also with this option if you are migrating from another computer you still need to add [[Cumulus.ini]], [[strings.ini]], all files in [[:Category:Log Files|data folder]], and any files in the Reports folder by file transfer from your other device to the Pi.

== Doing it 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 [https://www.raspberrypi.org/documentation/setup/ the manufacturer's web site], the manufacturer actually also publishes the same documentation on [https://github.com/raspberrypi/documentation/blob/master/setup/README.md their github page].
*If you have brought your Pi from a distributor, their web site (e.g. [http://www.okdo.com/gettingstarted '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 this article, each step in installation is covered, in the sections that follow. Obviously, this article is trying to balance the needs of a novice with the needs of someone who wants to plug holes in their existing knowledge, that need to be comprehensive means it might not seemed to be aimed exactly at what you need. ''Anyone who feels able to improve this article is welcome to edit it''.

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

#A Pi will work with either a class 4 (only 4 times faster), or a class 10, micro-SD card.
#Just for the standard install you need a card with a '''minimum of 8 GB'''.
#Given we are going to add Mono and Cumulus MX to the card, I advise you buy a card with at least 16 GB (as 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 [https://github.com/raspberrypi/documentation/blob/master/installation/noobs.md NOOBS (Novel Out of Box Software)],
* or pre-installed with the Raspberry Pi operating system.

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 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) and that will make your life simpler than buying a blank micro-SD card and having to down load and add the operating system 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.

=== The Operating System ===

As said before, a number of operating systems can be installed on your Pi, even Windows.

To keep this article simple, I will assume you have bought a micro-SD card either pre-installed with an operating system (OS) so you are ready to go, or you used NOOBS (as described earlier) to install your chosen OS.

If you do need to install any operating system you choose, normally the instructions will be found from where you download the system you have selected. If you have brought a card without NOOBS, you can download/install the Raspberry Operating System Buster yourself, following either instructions on the [https://www.raspberrypi.org/downloads/ Raspberry Pi download page], those at [https://thepihut.com/blogs/raspberry-pi-tutorials/the-raspberry-pi-tutorial-beginners-guide this supplier's tutorial guide], or [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 those in Cumulus support forum]. To save you looking any of those up, the next sub-section summarises what you need to do.

==== How to add Raspberry Operating System to a card yourself ====

*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)
*Download the latest version of the Raspberry Pi operating system you have selected from https://www.raspberrypi.org/downloads.
*That imager is run on any device, say your pc, 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).
*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, the larger Linux partition is invisible to Windows, the optional third partition uses up any space left on a larger micro-SD card and appears as "data" under "media" in the Linux file structure).

==== 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 card that determines which Raspberry Pi Operating System version is set up:
*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

Be aware that many such 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).

=== Wireless Network ===

How this is set up depends on your Pi model, and the operating system that is loaded on it,
*it may on first boot ask you to enter your wireless network details,
*it may list the wireless networks it finds and ask you to choose from the listed SSID,
*it might not prompt you so you need to use the configuration tool (see next sub-section),
*or you might need to click on an icon with two red crosses.

Note that there is also a Wi-Fi network country which must be set.

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

=== Other configuration ===

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),
*or by running a command <tt>sudo raspi-config</tt> in Terminal.

==== Mandatory configurations ====

Within the Raspberian configuration utility, you will see an option to change password. You will want to do this so nobody can hack into your Raspberry Pi computer. You will need to enter the new password twice before it replaces the old one.

The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name.
*The name can most easily be changed within the Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name.
*but it can also be edited by opening the file where it is stored using <tt>sudo nano /etc/hostname</tt>.

Network options can also be configured by clicking an icon on the Pi (this icon might be two red crosses if network settings are missing, two parallel arrows if the network settings are not correctly set, or the wireless symbol if your wireless network is working).

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

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

====To leave configuration====

Select ‘Finish’.

== 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. Before we can install Mono, there are other packages required and these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian 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):
<pre>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
</pre>

For Raspberry Operating System 10 (buster):
<pre>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</pre>

=== Checking all packages are up to date ===

'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.

=== Installing instruction ===

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

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

The "sudo" part of this gives us rights, "apt-get" is one of the ways to search the Raspberry repository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.

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

== Downloading and Unzipping MX Distribution ==

For simplicity, MX is installed into standard Pi user's home directory here. You might instead choose to install it on an external drive which has two significant advantages:
#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 are less likely to lose your operating system off your micro-SD card
#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 data

Both the optional "data" directory created by NOOBS and any external drive appear within "/media/" in the file structure, but the exact path depends on your set-up and can't be predicted here.

The procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution.
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#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 [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

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

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

'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
** It is important to see that whilst most settings can be done in the former, a few are read-only and must be done in latter
**Also 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 upload option; these are just the 2 most common errors)
*For general advice relating to [[Cumulus MX]], follow that link
*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
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions

'''If you have used Cumulus before''', but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
*Cumulus.ini
*strings.ini

The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder). Be aware that the characters terminating each line may need editing (see next sub-section).

Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].
*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 <tt>sudo chmod -R ugo+rw /var/www/html</tt> 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. If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed Windows on your Raspberry Pi. Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, then ideally all your files should be edited so they simply use Line_feed to terminate all lines. This can be easily done in an editor like Notepad++ that is designed for computer files.

The novice does not need to worry about changing end of line characters, it is advisable but not essential (as the Pi will treat the CR as a character it does not display)

To get the entire content of your existing '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).

First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).

== Running Cumulus MX ==

(When these notes were written, there were topics in the support forum about ways to use scripts for starting/stopping MX, but the distribution did not include any such controlling scripts. The latest MX version includes a script allowing MX to be run as a service, and perhaps someone would be kind enough to expand the first sub-section).

=== Running as a service ===

(awaiting someone to explain this)

=== Running with a terminal session left open ===

Whichever operating system you are using, to run MX requires an instruction that changes to the directory where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].

The simplest instruction to run Cumulus MX is <tt>cd CumulusMX && sudo mono CumulusMx.exe</tt>. 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 so that terminal session continues running.

== 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 access to many features including shutdown options.

=== sudo ===

Almost all instructions, given in this article, start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows a standard Pi user to do tasks that otherwise only work for the root user. You use it as a prefix to almost every command you type in terminal mode. There 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 '''/'''.

To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.

To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder. Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

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

=== nano ===

There are various text editors available on a Pi, '''nano''' is a simple one.

Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file.

Use prefix of 'sudo' to give you access to any file, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

When in nano you select to write out to a file, it allows you to change the file name shown. If you choose to save as another file, you will be asked if the new name is correct (again type '''Y''' to continue saving).

Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.

The full syntax is <tt>sudo nano -B Path_file_name</tt> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

You will probably find it useful to type <tt>sudo nano /etc/nanorc</tt> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options

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 <tt>sudo nano /var/www/html/index.php</tt>. 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.
*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.

=== 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 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 article simple, I accept the Operating System that is installed by NOOBS, even if it is not the latest available from the Raspberian web site, I 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 I use 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 article is aimed at, then you should know how to install the latest version from the appropriate web sites.

=== removing an unwanted file ===

You can remove a file or a folder with various commands, including <tt>sudo rm filename</tt>.

=== 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 [https://raspberrytips.com/raspberry-pi-commands/ this web page] or [https://www.ubuntupit.com/useful-raspberry-pi-commands/ 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 [https://github.com/magimat/rpi-cumulusmx rpi-cumulusmx] and a very old one at [https://github.com/Apollorion/CumulusMX-Docker 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 <tt>sudo apt update && sudo apt upgrade -y</tt> to ensure all packages are up to date before we attempt to add another package.
*I remind you here that this does not update everything on your computer to the latest versions available for a Pi, that requires a different (more risky) command not taught here.
*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;
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#*If you do find out what the first database is used for, please update the Wiki article on it!
#The second database is the Weather Diary [[Weather Diary|documented here]] added by Mark Crossley. Also see [https://cumulus.hosiene.co.uk/viewtopic.php?f=37&t=17919 in the support forum] for a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.
#* The [[MX Administrative Interface|Admin Interface]] provides a page to view, or edit, 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 <tt>sudo apt install phpliteadmin</tt>. 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.

I find the admin interface is not reliable for updating the weather diary; it often fails to store an update, without giving any error either on the editing screen or in the MXDiags file. So, I prefer to use phpliteadmin for making changes to the Weather Diary database now. I can use it 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:
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <tt>sudo apt-get install nginx -y</tt>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <tt>sudo apt-get install lighttpd -y</tt>.

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

*PHP is not the only script language available, but it is quite comprehensive
**being able to be used either in a fairly simple way by non-technical people
**or in an object-oriented way for those more technical to achieve success with more complex scripts.
*The simplest instruction to install it is <tt>sudo apt install php -y</tt>, which version you get depends on your Pi and its operating system.
*To check which PHP modules have been installed by the above command, type <tt>php -m</tt>.
*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 <tt>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</tt>. 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 <tt>php -v</tt> 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 <tt>php - f <file_name></tt>. 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'):
<pre>#!/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
</pre>

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

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 <tt>sudo mysql_secure_installation</tt>. That brings up a screen:
# where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
# next type '''Y''' to signify we are going to set a new password for '''root''',
# next type in a new password that you will not forget,
# 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''
# 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,
# 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,
# 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)

#Start the install with <tt>sudo apt install phpmyadmin -y</tt>.
#The PhpMyAdmin installer will ask some questions.
#Use your tab key to select <Yes> when it asks whether you want to configure with '''dbconfig-common'''.
#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 <tt>sudo apt install adminer</tt> (I leave you to work out the commands needed after that).

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

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 [[MX_Administrative_Interface#MySQL_settings|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.

<pre>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;</pre>

As I type this, Cumulus MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore in this situation it will crash out (with message press Enter to close).

=== Commands to ensure PhpMyAdmin will work ===

The following sequence of commands will
* add the mysqli module to our php install,
*will restart apache,
*will create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser,
*will give the standard user (pi) ownership of the database files and the web pages:

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

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

You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi 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:
#real-time
#standard interval
#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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe monthly</tt> to run the executable. The first parameter is "monthly" even if the table has a different name.
#if the table name is defined in the admin interface, and the table already exists in the database with the correct columns defined, then the executable will use that table.
#There is an optional second parameter that specifies the log file name to read.
#*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"),
# 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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe dayfile</tt>.

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 <tt>sudo service apache2 restart</tt> or (if we just want the Apache configuration reloaded) by typing <tt>sudo systemctl reload apache2</tt>. Similar commands apply for other web servers.

We will need to restart Apache (or whichever web server we installed) any time we change our php.ini files, database passwords, and anything else that is checked when the web server starts.

== 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 Pi====

On your Pi, there are various applications that you can run with graphical interfaces, these let you achieve what you want by on screen selections, without having to learn what Linux commands to type in. You might wish to use these when you are operating your Pi in a headless state (without keyboard or monitor), so you want to see these graphical interfaces on your PC. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.

An alternative way to work on your Pi is its its terminal mode. This lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, and can therefore allow you to achieve tasks where a graphical interface fails because of the ownership of the part of the file structure where your action is taking place. The commands you type into a terminal screen on a Pi can also be typed into a terminal screen on your PC, and you will see the same responses. For this to work, you need to switch Secure Shell Home (SSH) on as that is what controls access over a network. This article explains most aspects of SSH in the next few sub-sections.

==== 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 <tt>touch ssh</tt>, 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 <tt>ssh pi@raspberrypi</tt> to get access to default user in your Pi.

(As an alternative for Windows operating system, you can install PuTTY, this has the advantage that you can enter the connection settings into it, and configure various other options, and these are remembered, so might make it easier to use. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).

When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. The action that result from any key combinations depend on your terminal application, not just whatever you are running on your Pi. Your mouse can't affect cursor location, but the mouse might be needed to select text, the left click might copy what is selected, and the right click might paste (what is in your PC's clipboard) at current cursor position.

You can use SSH access from your PC:
* when you need to edit a file on your Pi,
*or do a file transfer between Pi and PC or vice versa.

=== Running MX from your PC ===

If you choose to use the simple <tt>sudo mono CumulusMX.exe</tt> command in a terminal (or command window or Powershell) session on your PC, remember MX will detect if that session is ended and will shut down MX. This means if you want to keep MX running you need to keep your session on your PC running and you loose the advantage of saving electricity by running MX on a PI because your PC remains on.

As I type this a new release 3.8.0 is to allow MX to run as a service, and a future release is planned to change the associated script, so anything I write here might become obsolete, and the next sub-section gives you some links to the support forum about alternatives to the new feature. Hopefully, someone will edit this article, when instructions have settled down and won't change on next release. Basically, the ability to run MX as a service, means that MX actually runs independent of the session that starts or stops the service; and therefore implies you can shut down your PC without stopping MX.

Hopefully someone will add notes to this article about the running as service option. I have not tried it, so I cannot add such notes.

=== Older information about using a PC and a PI ===

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

===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:
<pre>ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
ssid="YourNetwork"
psk="YourNetworkPassword"
key_mgmt=WPA-PSK
}</pre>

*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 [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).

===Downloading MX distribution on PC===

If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).

Debug.log

2021-01-12T18:09:02Z

Cortmalaw:

The debug logging feature is extremely useful in troubleshooting problems with Cumulus and/or connectivity to your weather station or FTP upload communications.

By default this is not enabled, but can be turned on and off as required. Click on the Settings / Program settings menu within CumulusMX (Settings / Station settings menu in Cumulus 1) and ''tick'' the 'Debug Logging' menu option.

The file contains a wealth of data including the raw data received from your weather station, connectivity attempts, file uploads, etc.

Note: Logging is turned on when you 'Save' the chnage in settings. It is automatically turned off if Cumulus is restarted. The file can grow very large very quickly so turn the Debug Log option off it not required. If the file grows too large it can cause Cumulus to crash.

=File Location, Name and Format=

In Cumulus 1, the file is called Debug.log, and is located in the root of the Cumulus folder.

In CumulusMX, debug logging adds additional detail into the standard logging file. This is located in folder MXdiags within the CumulusMX root directory. It is a text (*.txt) file named by the date and time that the CumulusMX session began, for example: 20210112-171450.txt

The log file is a simple text file containing the time and a description of each event.

The file can be deleted at any time as Cumulus does not read from it.

=Sample File=

An extract from a debug.log file

9168.735 : 14:23:54 Realtime FTP Put attempt
9168.766 : 14:23:54 Realtime FTP local file: C:\Program Files\Cumulus\realtime.txt
9168.766 : 14:23:54 Realtime FTP remote file: /var/www/html/data/realtime.txt
9173.500 : 14:23:59 USB device is plugged in
9173.500 : 14:23:59 request EW data block, written = 9, addr = 000000
9173.516 : 14:23:59 EW data line 01 55 AA FF FF FF FF FF FF
9173.516 : 14:23:59 EW data line 02 FF FF FF FF FF FF FF FF
9173.531 : 14:23:59 EW data line 03 0A 20 08 25 11 00 00 00
9173.531 : 14:23:59 EW data line 04 81 00 00 F0 0F 00 10 DD
9173.531 : 14:23:59 USB device is plugged in
9173.547 : 14:23:59 request EW data block, written = 9, addr = 00DD10
9173.563 : 14:23:59 EW data line 05 00 3A BF 00 47 97 00 FD
9173.578 : 14:23:59 EW data line 06 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 Data: 00 3A BF 00 47 97 00 FD 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 EW data line 07 0A 2D D5 00 55 57 00 16
9173.594 : 14:23:59 EW data line 08 26 00 00 00 06 65 07 00
9175.328 : 27/08/2009 14:24:00 Minute timer 24
9175.328 : Adding LH entry, ts = 14:24:00 raintot = 618
9175.328 : TD = 0.0833333358168602 Lastval = 618 Firstval = 618 rate = 0

[[Category:Log Files]]

Debug.log

2021-01-12T18:04:10Z

Cortmalaw: /* File Location, Name and Format */

The <tt>debug.log</tt> file is extremely useful in troubleshooting problems with Cumulus and/or connectivity to your weather station.

By default this is not enabled, but can be turned on and off as required. Click on the Settings / Program settings menu within Cumulus and ''tick'' the 'Debug Logging' menu option.

The file contains a wealth of data including the raw data received from your weather station, connectivity attempts, file uploads, etc.

Note: the file can grow very large very quickly so turn the Debug Log option off it not required. If the file grows too large it can cause Cumulus to crash.

=File Location, Name and Format=

In Cumulus 1, the file is called Debug.log, and is located in the root of the Cumulus folder.

In CumulusMX, debug logging adds additional detail into the standard logging file. This is located in folder MXdiags within the CumulusMX root directory. It is a text (*.txt) file named by the date and time that the CumulusMX session began, for example: 20210112-171450.txt

The log file is a simple text file containing the time and a description of each event.

The file can be deleted at any time as Cumulus does not read from it.

=Sample File=

An extract from a debug.log file

9168.735 : 14:23:54 Realtime FTP Put attempt
9168.766 : 14:23:54 Realtime FTP local file: C:\Program Files\Cumulus\realtime.txt
9168.766 : 14:23:54 Realtime FTP remote file: /var/www/html/data/realtime.txt
9173.500 : 14:23:59 USB device is plugged in
9173.500 : 14:23:59 request EW data block, written = 9, addr = 000000
9173.516 : 14:23:59 EW data line 01 55 AA FF FF FF FF FF FF
9173.516 : 14:23:59 EW data line 02 FF FF FF FF FF FF FF FF
9173.531 : 14:23:59 EW data line 03 0A 20 08 25 11 00 00 00
9173.531 : 14:23:59 EW data line 04 81 00 00 F0 0F 00 10 DD
9173.531 : 14:23:59 USB device is plugged in
9173.547 : 14:23:59 request EW data block, written = 9, addr = 00DD10
9173.563 : 14:23:59 EW data line 05 00 3A BF 00 47 97 00 FD
9173.578 : 14:23:59 EW data line 06 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 Data: 00 3A BF 00 47 97 00 FD 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 EW data line 07 0A 2D D5 00 55 57 00 16
9173.594 : 14:23:59 EW data line 08 26 00 00 00 06 65 07 00
9175.328 : 27/08/2009 14:24:00 Minute timer 24
9175.328 : Adding LH entry, ts = 14:24:00 raintot = 618
9175.328 : TD = 0.0833333358168602 Lastval = 618 Firstval = 618 rate = 0

[[Category:Log Files]]

Debug.log

2021-01-12T18:03:11Z

Cortmalaw: /* File Format */

The <tt>debug.log</tt> file is extremely useful in troubleshooting problems with Cumulus and/or connectivity to your weather station.

By default this is not enabled, but can be turned on and off as required. Click on the Settings / Program settings menu within Cumulus and ''tick'' the 'Debug Logging' menu option.

The file contains a wealth of data including the raw data received from your weather station, connectivity attempts, file uploads, etc.

Note: the file can grow very large very quickly so turn the Debug Log option off it not required. If the file grows too large it can cause Cumulus to crash.

=File Location, Name and Format=

In Cumulus 1, the file is called Debug.log, and is located in the root of the Cumulus folder.

In CumulusMX, debug logging adds additional detail into the standard logging file. This is located in folder MXdiags within the Cumulus root directory. It is a text (*.txt) file named by the date and time that the CumulusMX session began, for example: 20210112-171450.txt

The log file is a simple text file containing the time and a description of each event.

The file can be deleted at any time as Cumulus does not read from it.

=Sample File=

An extract from a debug.log file

9168.735 : 14:23:54 Realtime FTP Put attempt
9168.766 : 14:23:54 Realtime FTP local file: C:\Program Files\Cumulus\realtime.txt
9168.766 : 14:23:54 Realtime FTP remote file: /var/www/html/data/realtime.txt
9173.500 : 14:23:59 USB device is plugged in
9173.500 : 14:23:59 request EW data block, written = 9, addr = 000000
9173.516 : 14:23:59 EW data line 01 55 AA FF FF FF FF FF FF
9173.516 : 14:23:59 EW data line 02 FF FF FF FF FF FF FF FF
9173.531 : 14:23:59 EW data line 03 0A 20 08 25 11 00 00 00
9173.531 : 14:23:59 EW data line 04 81 00 00 F0 0F 00 10 DD
9173.531 : 14:23:59 USB device is plugged in
9173.547 : 14:23:59 request EW data block, written = 9, addr = 00DD10
9173.563 : 14:23:59 EW data line 05 00 3A BF 00 47 97 00 FD
9173.578 : 14:23:59 EW data line 06 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 Data: 00 3A BF 00 47 97 00 FD 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 EW data line 07 0A 2D D5 00 55 57 00 16
9173.594 : 14:23:59 EW data line 08 26 00 00 00 06 65 07 00
9175.328 : 27/08/2009 14:24:00 Minute timer 24
9175.328 : Adding LH entry, ts = 14:24:00 raintot = 618
9175.328 : TD = 0.0833333358168602 Lastval = 618 Firstval = 618 rate = 0

[[Category:Log Files]]

Raspberry Pi Image

2021-01-12T16:14:18Z

Cortmalaw: /* Starting Cumulus MX from the command line */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, scroll down to the bottom of the list and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - do not unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt filename extension 
* Eject the SD card from your computer. Insert it into your Raspberry Pi and power up.

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow '''[https://cumuluswiki.org/a/Cumulus.ini#Cumulus_MX this guide for configuring your station].'''
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudo systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMX.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-12T16:13:51Z

Cortmalaw: /* systemctl commands */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, scroll down to the bottom of the list and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - do not unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt filename extension 
* Eject the SD card from your computer. Insert it into your Raspberry Pi and power up.

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow '''[https://cumuluswiki.org/a/Cumulus.ini#Cumulus_MX this guide for configuring your station].'''
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudo systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Debug.log

2021-01-12T16:12:38Z

Cortmalaw: Update menu link. Typos.

The <tt>debug.log</tt> file is extremely useful in troubleshooting problems with Cumulus and/or connectivity to your weather station.

By default this is not enabled, but can be turned on and off as required. Click on the Settings / Program settings menu within Cumulus and ''tick'' the 'Debug Logging' menu option.

The file contains a wealth of data including the raw data received from your weather station, connectivity attempts, file uploads, etc.

Note: the file can grow very large very quickly so turn the Debug Log option off it not required. If the file grows too large it can cause Cumulus to crash.

=File Format=

The debug.log file is a simple text file containing the time and a description of each event.

It is located in the root of the Cumulus folder and can be deleted at any time as Cumulus does not read from it.

=Sample File=

An extract from a debug.log file

9168.735 : 14:23:54 Realtime FTP Put attempt
9168.766 : 14:23:54 Realtime FTP local file: C:\Program Files\Cumulus\realtime.txt
9168.766 : 14:23:54 Realtime FTP remote file: /var/www/html/data/realtime.txt
9173.500 : 14:23:59 USB device is plugged in
9173.500 : 14:23:59 request EW data block, written = 9, addr = 000000
9173.516 : 14:23:59 EW data line 01 55 AA FF FF FF FF FF FF
9173.516 : 14:23:59 EW data line 02 FF FF FF FF FF FF FF FF
9173.531 : 14:23:59 EW data line 03 0A 20 08 25 11 00 00 00
9173.531 : 14:23:59 EW data line 04 81 00 00 F0 0F 00 10 DD
9173.531 : 14:23:59 USB device is plugged in
9173.547 : 14:23:59 request EW data block, written = 9, addr = 00DD10
9173.563 : 14:23:59 EW data line 05 00 3A BF 00 47 97 00 FD
9173.578 : 14:23:59 EW data line 06 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 Data: 00 3A BF 00 47 97 00 FD 25 00 03 00 0B 0C 08 00
9173.578 : 14:23:59 EW data line 07 0A 2D D5 00 55 57 00 16
9173.594 : 14:23:59 EW data line 08 26 00 00 00 06 65 07 00
9175.328 : 27/08/2009 14:24:00 Minute timer 24
9175.328 : Adding LH entry, ts = 14:24:00 raintot = 618
9175.328 : TD = 0.0833333358168602 Lastval = 618 Firstval = 618 rate = 0

[[Category:Log Files]]

Raspberry Pi Image

2021-01-09T15:50:14Z

Cortmalaw: /* Configure Cumulus MX */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, scroll down to the bottom of the list and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - do not unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt filename extension 
* Eject the SD card from your computer. Insert it into your Raspberry Pi and power up.

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow '''[https://cumuluswiki.org/a/Cumulus.ini#Cumulus_MX this guide for configuring your station].'''
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-09T15:35:09Z

Cortmalaw: /* Installing the Image */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, scroll down to the bottom of the list and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - do not unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt filename extension 
* Eject the SD card from your computer. Insert it into your Raspberry Pi and power up.

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T13:08:39Z

Cortmalaw: /* Using the pre-built Raspberry Pi Image */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is to be run on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a Graphical User Interface (GUI), it is a command line only installation. It is possible to add the GUI later if you want it.

=== Pre-Installation Steps ===
You will need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
:You can use an SSD instead if preferred [with the minor complication that in a later step you will need non-WiFi access to the Raspberry Pi (keyboard and monitor, or SSH over ethernet) as you cannot enter the WiFi details from a Windows PC to the linux SSD due to the different file system used]
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide uses Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:55:27Z

Cortmalaw: /* Image Customisations */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Based on the 'Lite' version of the Raspberry Pi OS (ie the graphical desktop GUI is not included; it can be added later if you want it)
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:52:10Z

Cortmalaw: /* Additional Steps */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed IP address for your Raspberry Pi, there are 2 methods

1. Adjust your router settings to always assign the same IP address. This facility has different names on different brands of router, look for a section named DHCP. You may be able to choose the IP address (possibly within or possibly outside the range assigned by DHCP), or you may only be allowed to choose 'always assign the address it currently has'. You may need to know the MAC address of the Raspberry PI, but if so that will likely be displayed alongside the current connection.

2. Adjust Raspberry Pi settings to always request the the same fixed address. This is less reliable, because your router may have assigned the requested address to a different device since the Pi was last active. To do this you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connection a line specifying port '''eth0''' is needed to describe your ethernet configuration, as the example below. For a wireless connection, it needs similar with '''wlan0''':
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:41:22Z

Cortmalaw: /* Configure Cumulus MX */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:40:44Z

Cortmalaw: /* Configure Cumulus MX */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>''' or '''http://<ip_address>:8998'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' or URL: '''http://<ip_address>:8998''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:39:30Z

Cortmalaw: /* Verify your SSH Connection */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (As before, you may need to enter the Pi's IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:37:32Z

Cortmalaw: /* First Boot */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router). It just depends on your router whether it allows use of the name (cumulusmx) or requires the IP address.

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (You can use the IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:35:53Z

Cortmalaw: /* First Boot */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: '''<nowiki>http://192.168.1.123:8998</nowiki>''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router)

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (You can use the IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:33:43Z

Cortmalaw: /* First Boot */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: URL: '''<nowiki>http://192.168.1.123:8998''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router)

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (You can use the IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

Raspberry Pi Image

2021-01-07T12:33:02Z

Cortmalaw: /* First Boot */

== Using the pre-built Raspberry Pi Image ==
We have created an customised version of the Raspberry Pi Lite image with Cumulus MX pre-installed and ready to go.

This is designed to be what is called a "headless" installation, that is you can run it on a Raspberry Pi without a monitor or keyboard attached to it. As such the image does not contain a GUI, it is a command line only installation.

=== Pre-Installation Steps ===
You are going to need:
* A suitable SD card for your Raspberry Pi
:A minimum size of 16GB is recommended. Be sure to buy a good quality card.
* An image installer to copy the image file to the SD card
:The [https://www.raspberrypi.org/documentation/installation/installing-images/ Raspberry Pi site] has a list of suitable software for your operating system. Scroll down to "Writing the image". 
: This guide with use Raspberry Pi Imager
* The image file to install
:Download the latest image file from here: [//{{SERVERNAME}}/Downloads/rpi-CMX-3.9.4.zip rPi Cumulus MX 3.9.4].
* An SSH terminal program to configure your Raspberry Pi
: For Windows we recommend using [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY]
* A file transfer program - though you will not need this right away, you will need it at some point. The main uses will be...
:* Copying Cumulus MX updates to your Raspberry Pi
:* Extracting the diagnostic files from Cumulus MX if this go wrong
:* Setting up a web site 
:A popular program for Windows is [https://winscp.net/eng/download.php WinSCP]

=== Installing the Image ===
This installation was performed on a Windows computer using the [https://www.raspberrypi.org/downloads/ Raspberry Pi Imager v1.4] software
[[File:PiImager-01.png|none]]
* Insert your blank SD card into your computer - if not blank whatever is on the card will be erased.
* Start Raspberry Pi Imager
:* Click the CHOOSE OS button, and select '''Use custom'''
:*; [[File:PiImager-02.png|none]]
:* Browse to the location of the OS Image zip file you downloaded - no need to unzip it
:* Click CHOOSE SD CARD, and select the SD card from the Device dropdown - check you have the correct drive selected!
:*; [[File:PiImager-04.png|none]]
:* Click the WRITE button. Writing the image will take a few minutes
:* Once the image has finished been written, you can close Raspberry Pi Imager 
* '''''OPTIONAL''''' - If you wish to connect your Pi to the network using WiFi from the first boot, then you will need to follow these additional steps.
*;Note. If you connect via an cabled network, you can always configure the WiFi later using the command line
:* Eject your SD card from your computer and re-insert it
:* Locate the SD drive in File Explorer.
:* On the SD drive edit a file called '''wpa_supplicant.conf.txt''' with a text editor and...
::* Change the country code to match your location - eg. US, GB, FR etc
::* Set the ssid to match your WiFi id
::* Set the psk to your WiFi password
:* Save the file, and then rename it to '''wpa_supplicant.conf''' - i.e. remove the .txt file extension 
* Eject the SD card from your computer and insert it into your Raspberry Pi

=== First Boot ===
* Connect the Pi to your wired network if you did not configure the WiFi as per the steps above.
* Power on the Pi.
* Now wait 5 minutes. The first boot will be resizing your disk and optionally configuring your WiFi
* Start your browser and see if you can connect to this URL: '''<nowiki>http://cumulusmx:8998</nowiki>'''
:* If you can great - you should now see the Cumulus MX console
:* If not, then you will have to find out the Raspberry Pi's IP address from your router. Then try connecting to this URL: '''http://<ip_address>:8998''' (example: URL: '''http://192.168.1.123:8998''' where the numbers before :8998 are those for YOUR Raspberry Pi from YOUR router)

=== Verify your SSH Connection ===
* Fire up your SSH Client - we use PuTTY here
:* Enter the hostname as "cumulusmx", and check the protocol is set to SSH. Then open the connection. 
: (You can use the IP address instead of the hostname if that does not work)
:*; [[File:PuTTY-01.png|none]]
* You will have the accept the SSH key the first time you connect
* Enter the username "pi" and password "raspberry" - these are the default Raspberry Pi username credentials
* When you login it will display a warning about you using the default password and ask you to change it
:* Use the '''passwd''' command to do this now...
<nowiki>pi@cumulusmx:~ $ passwd
Changing password for pi.
Current password:
New password:
Retype new password:
passwd: password updated successfully</nowiki>
* Check the status of the Cumulus MX service with the command '''sudo systemctl status cumulusmx''' 
: You will get some information back, the important bit to note is the line starting '''Active:''', it should say '''active (running)'''
* You can leave the SSH session open, you will need it again soon...

=== Configure Cumulus MX ===
Now it is time to configure Cumulus MX for your station.
* Start your browser and connect to the same URL as before - '''<nowiki>http://cumulusmx:8998</nowiki>'''
* From the menu select '''Settings | Station Settings''', then follow the guide on [this page?] for configuring your station
* Once your have completed all the settings for for station, and successfully saved them, Cumulus MX will need to be restarted.
* Back in your SSH session, send the command '''sudo systemctl stop cumulusmx''', this stops the Cumulus MX service.
* Wait a few seconds, then enter the command '''sudo systemctl start cumulusmx''', this starts the Cumulus MX service again.
* Back to your browser and check that URL - '''<nowiki>http://cumulusmx:8998</nowiki>''' - again. If all is well, the default dashboard page should start showing the data from your weather station.
:* If it does, congratulations, you have successfully started recording your weather data
:* If it doesn't, then check back over this process carefully for any mistakes or omissions you may have made.
:* If you cannot resolve the problem, then ask for [https://cumulus.hosiene.co.uk/ help on the forum]

== Additional Steps ==
''To be expanded''
* Configuring WiFi from SSH
* Stopping Cumulus MX starting up when the Pi boots
* Give your Pi a fixed IP address
:* Add a DHCP reservation
:* Assign a static IP address
:If you need to use a fixed ip address for your Raspberry Pi, you have to edit this file: « '''/etc/network/interfaces''' »
:For Ethernet connexion a line specefying port '''eth0''' is needed to describe your ethernet configuration, as this sample:
allow-hotplug eth0
iface eth0 inet static
address 192.168.11.100
netmask 255.255.255.0
gateway 192.168.11.1
dns-domain example.com
dns-nameservers 192.168.11.1
''The line "dns-domain example.com" is optional''

:You could have also to edit an other file, for dns configuration.
:see file «'''/etc/resolv.conf'''» to insert these lines:
nameserver 192.168.11.1
domain example.com
''Again, the line "domain example.com" is optional''

== Information ==
=== Install location ===
In this image Cumulus MX is installed into '''/opt/CumulusMX'''

=== Image Customisations ===
* Full install of Mono
* Update of all packages
* Install of Cumulus MX
* Set Cumulus MX to auto-start
* Enable SSH service
* Disable IPv6
* Set hostname to "cumulusmx"

=== systemctl commands ===
You can use the following commands to control Cumulus MX...
: To start Cumulus:
sudo systemctl start cumulusmx
: To stop Cumulus:
sudo systemctl stop cumulusmx
: To check if Cumulus is running:
sudo systemctl status cumulusmx
: To restart Cumulus:
sudo systemctl restart cumulusmx
: To make Cumulus start at system boot time:
sudo systemctl enable cumulusmx
: To stop Cumulus starting at boot time:
sudp systemctl disable cumulusmx

=== Starting Cumulus MX from the command line ===
You may want to start Cumulus from the command line for diagnostic purposes, you can still do this...

First make sure the Cumulus MX service is stopped
sudo systemctl stop cumulusmx

Then path to the Cumulus folder and start it
cd /opt/cumulusmx
sudo mono CumulusMx.exe

=== Symbolic Links ===
The image contains a number of precreated symbolic links for Cumulus MX files such as realtime.txt and the standard website tmp files. These links divert these files to a memory disk to reduce wear on your SD card.

== Build Creation Notes ==
* Installed Raspberry Pi Buster Lite (August 2020)
* Enabled SSH
* Installed latest updates - apt update/upgrade
* Installed latest Mono complete stable version (6.12)
* Clean up apt - apt autoremove
* Changed hostname to "cumulusmx"
* Edited cumulusmx.service and copied to /etc/systemd/system
* Disabled mono-xsp4 service - update-rc.d mono-xsp4 disable
* Copied CMX to /opt/CumulusMX folder
* Created symbolic links for temp files to /run/cumulusmx

The following commands are useful in creating the image file (created on Debian).

Create image file from SD card - sdb, may be sdc etc.
dd if=/dev/sdb of=/home/<username>/rpi.img bs=1M

Shrink the image file. 
Download pishrink from:
wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
Then run it...
pishrink.sh /home/<username>/rpi.img /home/<username>/rpi2.img

Disable IPv6 
Edit /etc/systctl.conf 
Add line...
net.ipv6.conf.all.disable_ipv6 = 1

MX on Linux

2021-01-07T11:09:16Z

Cortmalaw: /* Which Raspberry Pi to buy */

=Using MX on UNIX-derived Operating Systems=

MX runs on various UNIX-derived operating systems (OS), including those found on Apple Mac computers, and those found on devices running Linux.

==This article focuses on a computer called the Raspberry Pi==

Although the article focusses on one computer type, the Raspberry Pi, the idea is that this article will complement another article [[Moving from Cumulus 1 to MX|Running Cumulus MX on Windows]], so feel free to add more to this article to explain how it can be applied to another Unix-derived devices.

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" MX difficult.

The same forum reveals few posts from people struggling with setting up the Raspberry Pi, and several posts reporting success with using MX on this small computer.

==Précis==

{{TOCright}}
*The Raspberry Pi is a simple computer that is far easier to learn than a complicated machine like a Personal Computer (PC) running Windows.
*You can choose either to install the Windows operating system on your Raspberry Pi or to install the simpler Raspberry Pi operating system (based on debian Linux).
**This article focusses on the latter as another article covers Windows.
**You don't need to learn much Linux, but this article does cover some commands.
*The Raspberry Pi is ideal to run Cumulus MX
**The Raspberry Pi is a computer that is better for the environment, unlike a PC manufactured with lot of components, and a PC wastes a lot of electricity if left running.
**Downloading the release distribution, and unzipping the files, is the same on any device
**On Linux you need to (simply) manually install one extra component (Mono-complete), while the equivalent component (.NET) is automatically installed on Windows.
**Running MX is same on any device (precise command syntax to start it varies, but what MX does when running does not depend on device)
*It is simplest to connect keyboard and monitor to the Raspberry Pi so all actions are done directly on it.
*Some optional topics are also covered.
**One option covered is adding a web server and a database server
**Another option discussed is using a PC to control a "headless" Raspberry Pi (i.e. one without keyboard and without monitor).

==Introduction==

It is a small board of electronics that can actually run Windows, Mac OS, Chrome OS, various Linux distributions, or the Raspberry Pi OS (based on Ubantu Linux).

In this article, the focus is on the last OS, because that is easiest to install, so look elsewhere on the web for details of installing alternatives. The notes here will generally apply to any version of Linux, although the configuration editor described is only on the Pi.

The Apple Mac runs its own version of Unix, and while standard Unix uses Line_Feed to terminate lines in files, the Mac uses Carriage_Return. Hopefully someone will write an article about the Mac in this Wiki, but in meantime this is closest you can get.

The article will give you some guidance on:
*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 optional extras!

=Which Raspberry Pi to buy=

A standard desktop computer consumes at least 200 Watts of power (that is when it is idle, it will increase depending on peripherals attached and 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 Watt when running tasks or connected to peripherals. A Pi model 4 B (the latest model at time of writing) consumes 2.85 to 80 Watt depending on whether it is idle or working hard. Although Cumulus MX does not need to run 24/7, derived values like highest, lowest, average, and so on, will be more accurately calculated if MX is left running. Although the Pi is not the only small computer model available, it is probably the most popular and the easiest one to use if you do want to run MX all the time and not wreck the planet!

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 sections contain just suggestions on how to decide, there is no intention to force any single decision. This article focusses on those who buy a Raspberry Pi as a small computer, who might want to use it for other tasks like word processing, and for novices who feel happier to connect a screen and keyboard. This article is less useful if you want to own 2 computers and run your Pi headless by sending commands from your other computer, see [[Raspberry Pi Image]] article instead.

==First make a list of what you need==

*Do you want to use a mouse and key board so that you can use your Raspberry Pi as a computer for tasks like browsing the web and word processing, not just for Cumulus MX?
** If so, a model with multiple USB sockets is advisable (like 3B+)
** This also applies if you want to be able to plug in a USB stick (perhaps for holding/transferring files between devices, e.g. Cumulus configuration and data folder files; this will save wear on 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+)
** 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 pi in headless mode, a wired or wireless connection to your LAN is needed for your other device to communicate with the Pi
*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 Zero will have to do each task in turn, and you will see some delay in information updates, plus you will need to use a larger time between updates
** If so, a model Three (or Four) 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 choose between the model 0W with one USB socket, and the model 3B+ with 4 USB sockets depending on whether you might want to use another USB socket ever
** 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. Here, I won't describe all the different models, but concentrate on just 2 for simplicity.

The model Zero W is appealing as it has 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 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 interfaces built in, such as 4 USB 2 ports (useful if you want to connect a weather station using USB and connect a keyboard).

While both models support wireless links 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 you want to install a web server, on your Pi). Having an Ethernet connection, as explained later, makes it possible to easily install the Windows Operating System on your Raspberry Pi on first boot.

* Raspberry Pi Zero W
** Pi Zero W has WiFi and one micro-USB port which is all that is needed for headless running.
** 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, so the connectivity and speed of the actual Pi are less important
* Raspberry Pi Three B Plus
** 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 Three B Plus 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 a monitor and 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 Four has more capabilities, but may be less appealing as it also consumes more power.

== What else to buy ==

You can buy just the Pi, which is just a circuit board, or a kit that includes other components.

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 that you can fit the board into to protect it.

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.

You may need a power supply.
*This could be an official Raspberry Pi power supply.
*Alternatively, any power supply unit that has a micro USB connector will do, the power consumption of a Pi (whichever model) is fairly small, but it will be powered on 24/7, so a low power consumption ‘switched mode’ type is preferred – i.e. one that does not become warm when plugged in with nothing attached.
**You may have a suitable one left over from an earlier mobile phone.

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 to connect to your weather station (the Pi model Zero requires a micro USB, the Pi model 3 requires a standard A end USB) and your station probably has a USB A end connection.
*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.

If you do choose a model 3 (or later), consider whether you do want to buy a USB mouse and USB keyboard to use with it.

Finally, you may wish to buy a second micro-SD unit as a spare, or some other USB connected (or network connected) storage for back-ups and extra storage needs.

= Setting up your Pi =

== Image alternative ==

If you are never going to use a keyboard nor Tv (or other monitor) with your Raspberry Pi, there is now an alternative to installing operating system, mono, and MX separately, a single '''image''' that contains all elements needed can be downloaded from the [[Software#Current_Release|Software page Current_Release section]], read about using it in [[Raspberry_Pi_Image]] article. I will just stress here, that following this alternative option, provided by developer, installs the '''Raspberry Pi Lite Operating System''' and does not give you the freedom to add a web site as described below. Also with this option you still need to add [[Cumulus.ini]], [[strings.ini]], all files in [[:Category:Log Files|data folder]], and any files in the Reports folder by file transfer from some other device to the Pi with this image.

== Doing it 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 [https://www.raspberrypi.org/documentation/setup/ the manufacturer's web site], the manufacturer actually also publishes the same documentation on [https://github.com/raspberrypi/documentation/blob/master/setup/README.md their github page].
*If you have brought your Pi from a distributor, their web site (e.g. [http://www.okdo.com/gettingstarted '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 this article, each step in installation is covered, in the sections that follow. Obviously, this article is trying to balance the needs of a novice with the needs of someone who wants to plug holes in their existing knowledge, that need to be comprehensive means it might not seemed to be aimed exactly at what you need. ''Anyone who feels able to improve this article is welcome to edit it''.

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

#A Pi will work with either a class 4 (only 4 times faster), or a class 10, micro-SD card.
#Just for the standard install you need a card with a '''minimum of 8 GB'''.
#Given we are going to add Mono and Cumulus MX to the card, I advise you buy a card with at least 16 GB (as 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 [https://github.com/raspberrypi/documentation/blob/master/installation/noobs.md NOOBS (Novel Out of Box Software)],
* or pre-installed with the Raspberry Pi operating system.

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 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) and that will make your life simpler than buying a blank micro-SD card and having to down load and add the operating system 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.

=== The Operating System ===

As said before, a number of operating systems can be installed on your Pi, even Windows.

To keep this article simple, I will assume you have bought a micro-SD card either pre-installed with an operating system (OS) so you are ready to go, or you used NOOBS (as described earlier) to install your chosen OS.

If you do need to install any operating system you choose, normally the instructions will be found from where you download the system you have selected. If you have brought a card without NOOBS, you can download/install the Raspberry Operating System Buster yourself, following either instructions on the [https://www.raspberrypi.org/downloads/ Raspberry Pi download page], those at [https://thepihut.com/blogs/raspberry-pi-tutorials/the-raspberry-pi-tutorial-beginners-guide this supplier's tutorial guide], or [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 those in Cumulus support forum]. To save you looking any of those up, the next sub-section summarises what you need to do.

==== How to add Raspberry Operating System to a card yourself ====

*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)
*Download the latest version of the Raspberry Pi operating system you have selected from https://www.raspberrypi.org/downloads.
*That imager is run on any device, say your pc, 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).
*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, the larger Linux partition is invisible to Windows, the optional third partition uses up any space left on a larger micro-SD card and appears as "data" under "media" in the Linux file structure).

==== 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 card that determines which Raspberry Pi Operating System version is set up:
*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

Be aware that many such 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).

=== Wireless Network ===

How this is set up depends on your Pi model, and the operating system that is loaded on it,
*it may on first boot ask you to enter your wireless network details,
*it may list the wireless networks it finds and ask you to choose from the listed SSID,
*it might not prompt you so you need to use the configuration tool (see next sub-section),
*or you might need to click on an icon with two red crosses.

Note that there is also a Wi-Fi network country which must be set.

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

=== Other configuration ===

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),
*or by running a command <tt>sudo raspi-config</tt> in Terminal.

==== Mandatory configurations ====

Within the Raspberian configuration utility, you will see an option to change password. You will want to do this so nobody can hack into your Raspberry Pi computer. You will need to enter the new password twice before it replaces the old one.

The default network (host) name for your Pi is '''raspberrypi''', obviously we need to replace that as well with a name that personalises it to you and does not make it easy for a hacker to know what device is represented by that network name.
*The name can most easily be changed within the Raspberian configuration utility, you will see a '''Network Options''' option, it is there that you change the network name.
*but it can also be edited by opening the file where it is stored using <tt>sudo nano /etc/hostname</tt>.

Network options can also be configured by clicking an icon on the Pi (this icon might be two red crosses if network settings are missing, two parallel arrows if the network settings are not correctly set, or the wireless symbol if your wireless network is working).

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

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

====To leave configuration====

Select ‘Finish’.

== 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. Before we can install Mono, there are other packages required and these vary depending upon the Raspberry operating system version we have installed, see [https://www.mono-project.com/download/stable/#download-lin-raspbian 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):
<pre>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
</pre>

For Raspberry Operating System 10 (buster):
<pre>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</pre>

=== Checking all packages are up to date ===

'''Either''' type:
<pre>sudo apt-get update
sudo apt-get upgrade</pre>
'''or''' to insert in single line type instead <tt>sudo apt-get update && sudo apt-get upgrade</tt>.

=== Installing instruction ===

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

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

The "sudo" part of this gives us rights, "apt-get" is one of the ways to search the Raspberry repository for applications, "install" is the action we want to do, and "mono-complete" is the package we want.

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

== Downloading and Unzipping MX Distribution ==

For simplicity, MX is installed into standard Pi user's home directory here. You might instead choose to install it on an external drive which has two significant advantages:
#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 are less likely to lose your operating system off your micro-SD card
#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 data

Both the optional "data" directory created by NOOBS and any external drive appear within "/media/" in the file structure, but the exact path depends on your set-up and can't be predicted here.

The procedure is exactly same on your Raspberry Pi, as it would be on a Windows PC:
# It is recommended, you type <tt>sudo mkdir ~/CumulusMX</tt> first, so you already have folder ready for MX, but the file can be created by unzipping the distribution.
#Run the browser you have available on your Raspberry Pi (the installed browser depends on what Operating System you installed)
#To find the link to latest release distribution zip in the Cumulus Wiki, open the [[Software#Current_Release|Software article in the Current_Release section]].
#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 [https://github.com/cumulusmx/CumulusMX/releases CumulusMX/releases].

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

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

'''If you have not used Cumulus before''', there is useful guidance in various other articles that is not repeated here (it may seem a lot to read, but reading these instructions my save you from days of issues, just look at the support forum for examples of people struggling because they did not read up first and so missed key settings):
*To learn about what MX can do, please see [[About Cumulus]] article
*To learn about configuration, please see [[MX Administrative Interface]] and [[Cumulus.ini]] articles.
** It is important to see that whilst most settings can be done in the former, a few are read-only and must be done in latter
**Also 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 upload option; these are just the 2 most common errors)
*For general advice relating to [[Cumulus MX]], follow that link
*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
**The cumulus 1 [[FAQ]] might help (e.g. how to upload past data), but use with caution as Cumulus 1 and MX are very different in how they do many actions

'''If you have used Cumulus before''', but this is first installation on Pi, then you need to copy some files from old installation to your Pi, here are a couple but you may have further configuration files to copy across:
*Cumulus.ini
*strings.ini

The two examples above are in same folder as Cumulus.exe or CumulusMX.exe. You also may have configuration files in a '''mqtt''' folder, or elsewhere (for example I store some batch files that Cumulus runs for me in a batch folder). Be aware that the characters terminating each line may need editing (see next sub-section).

Remember as mentioned earlier, the configuration file [[Cumulus.ini]] may need editing to update port names, any command locations, and to update file locations. Whilst you will find using the admin interface is easiest because it (in many cases) limits the selections to those that are valid; editing the Cumulus.ini file directly might be easier if you have moved from Windows and want to do repeat edits (e.g. changing multiple paths for files is easier using a repeat edit, than wading through all extra web file options in the interface).
*There is advice about port names at [[Cumulus.ini#Swapping_from_Cumulus_1_to_MX]].
*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 <tt>sudo chmod -R ugo+rw /var/www/html</tt> 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. If you have been using the Windows Operating System each line in each file will be terminated by two control characters (carriage_return and Line_feed). That is fine if you have installed Windows on your Raspberry Pi. Assuming you have installed the Raspberry Pi Operating System or another Linux distribution, then ideally all your files should be edited so they simply use Line_feed to terminate all lines. This can be easily done in an editor like Notepad++ that is designed for computer files.

The novice does not need to worry about changing end of line characters, it is advisable but not essential (as the Pi will treat the CR as a character it does not display)

To get the entire content of your existing '''data''' and '''Reports''' folder onto your Pi:
*you could copy them onto the micro-SD card (and move that between PC and Pi)
*you can transfer files across the wireless or Ethernet network using FileZilla Client (or an alternative file transfer tool).

First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
**If your Raspberry Pi has both Wireless and Ethernet connections, you will have two possible IPv4 addresses, choose either, the Ethernet one is likely to be quicker.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).

== Running Cumulus MX ==

(When these notes were written, there were topics in the support forum about ways to use scripts for starting/stopping MX, but the distribution did not include any such controlling scripts. The latest MX version includes a script allowing MX to be run as a service, and perhaps someone would be kind enough to expand the first sub-section).

=== Running as a service ===

(awaiting someone to explain this)

=== Running with a terminal session left open ===

Whichever operating system you are using, to run MX requires an instruction that changes to the directory where it is installed (the instruction below is assuming it is in the standard Pi user home directory, the change directory command will be different if you have installed it elsewhere), and then starting the executable (using mono in the instruction below that applies to any non-Windows operating system). You may wish to add [[Cumulus_MX#Optional_parameters_to_add_to_the_instruction_to_run_the_MX_engine|Optional_parameters]].

The simplest instruction to run Cumulus MX is <tt>cd CumulusMX && sudo mono CumulusMx.exe</tt>. 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 so that terminal session continues running.

== 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 access to many features including shutdown options.

=== sudo ===

Almost all instructions, given in this article, start with a "sudo", it basically gives administrative rights to whatever follows, and therefore allows a standard Pi user to do tasks that otherwise only work for the root user. You use it as a prefix to almost every command you type in terminal mode. There 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 '''/'''.

To see what files and folders are in the current directory, type <tt>dir</tt> for just names or <tt>ls</tt> for details.

To make a new folder in the current directory, type <tt>sudo mkdir folder_name</tt>.

=== chmod ===

When you are attempting any of the actions listed in this article that involve reading, creating, editing, or moving, files; you might see an error message generally because of a lack of write permissions on an existing file or folder. Whilst <tt>rm filename</tt> will remove a file even if it is write protected, for nano you need to change the file permissions with <tt>sudo chmod -R ugo+rw ~/CumulusMX</tt> for full access to all files in your Cumulus installation (see the syntax below if you want to restrict access).

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

=== nano ===

There are various text editors available on a Pi, '''nano''' is a simple one.

Like other text editors this can create a file when a file does not exist and edit (subject to file permissions) an existing file.

Use prefix of 'sudo' to give you access to any file, '''sudo''' does not change the actual file permissions, so you might find you can read a file, but not save it after you have done your edit.

When in nano you select to write out to a file, it allows you to change the file name shown. If you choose to save as another file, you will be asked if the new name is correct (again type '''Y''' to continue saving).

Do remember that file names are case sensitive, and when you open an existing file for editing look in case "new file" message appears because you have made a typo in the path/file name.

The full syntax is <tt>sudo nano -B Path_file_name</tt> where the '''-B''' means it will create a backup of how the file was before (this can be enabled while in the editor by pressing the control key down and typing B). Alternatively use '''-C''' which stores each version in a back-up directory. If you want to edit from a particular line and column you can use '''+line.column''', and also optionally use '''-l''' (lower-case "L") to display line numbers which might be useful when trying to correct a problem with a log file like [[dayfile.txt]]. If you don't specify a file name, then nano will create a new file and you will need to specify where to save it before exit.

You will probably find it useful to type <tt>sudo nano /etc/nanorc</tt> as this puts you into the configuration file for nano where you can set back-up, line-numbering, and other options

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 <tt>sudo nano /var/www/html/index.php</tt>. 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.
*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.

=== 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 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 article simple, I accept the Operating System that is installed by NOOBS, even if it is not the latest available from the Raspberian web site, I 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 I use 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 article is aimed at, then you should know how to install the latest version from the appropriate web sites.

=== removing an unwanted file ===

You can remove a file or a folder with various commands, including <tt>sudo rm filename</tt>.

=== 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 [https://raspberrytips.com/raspberry-pi-commands/ this web page] or [https://www.ubuntupit.com/useful-raspberry-pi-commands/ 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 [https://github.com/magimat/rpi-cumulusmx rpi-cumulusmx] and a very old one at [https://github.com/Apollorion/CumulusMX-Docker 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 <tt>sudo apt update && sudo apt upgrade -y</tt> to ensure all packages are up to date before we attempt to add another package.
*I remind you here that this does not update everything on your computer to the latest versions available for a Pi, that requires a different (more risky) command not taught here.
*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;
#The first database was added by Steve Loft, but he never documented what it is used for (see [[Cumulusmx.db]]) and in the support forum when someone asked, nobody was able to answer.
#*If you do find out what the first database is used for, please update the Wiki article on it!
#The second database is the Weather Diary [[Weather Diary|documented here]] added by Mark Crossley. Also see [https://cumulus.hosiene.co.uk/viewtopic.php?f=37&t=17919 in the support forum] for a topic comparing the differences between Cumulus 1 and Cumulus MX weather diaries.
#* The [[MX Administrative Interface|Admin Interface]] provides a page to view, or edit, 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 <tt>sudo apt install phpliteadmin</tt>. 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.

I find the admin interface is not reliable for updating the weather diary; it often fails to store an update, without giving any error either on the editing screen or in the MXDiags file. So, I prefer to use phpliteadmin for making changes to the Weather Diary database now. I can use it 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:
#You might choose '''Apache 2''' as it is probably the most comprehensive, so if you have enough space on your Pi, install it using <tt>sudo apt install apache2 -y</tt>.
#*You might want to add Fast CGI (if you don't know what that is, skip this) and therefore add <tt>sudo apt-get install libapache2-mod-fcgid</tt>.
#You might choose '''nginx''', as it is quite popular for small computers like the Pi, install that web server with <tt>sudo apt-get install nginx -y</tt>.
#You might choose '''lighttpd''', as it is designed to use as little space on your Pi as possible, install it with <tt>sudo apt-get install lighttpd -y</tt>.

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

*PHP is not the only script language available, but it is quite comprehensive
**being able to be used either in a fairly simple way by non-technical people
**or in an object-oriented way for those more technical to achieve success with more complex scripts.
*The simplest instruction to install it is <tt>sudo apt install php -y</tt>, which version you get depends on your Pi and its operating system.
*To check which PHP modules have been installed by the above command, type <tt>php -m</tt>.
*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 <tt>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</tt>. 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 <tt>php -v</tt> 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 <tt>php - f <file_name></tt>. 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'):
<pre>#!/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
</pre>

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

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 <tt>sudo mysql_secure_installation</tt>. That brings up a screen:
# where we are asked to type current password for the root (as no password has yet been set, simply press Enter),
# next type '''Y''' to signify we are going to set a new password for '''root''',
# next type in a new password that you will not forget,
# 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''
# 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,
# 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,
# 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)

#Start the install with <tt>sudo apt install phpmyadmin -y</tt>.
#The PhpMyAdmin installer will ask some questions.
#Use your tab key to select <Yes> when it asks whether you want to configure with '''dbconfig-common'''.
#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 <tt>sudo apt install adminer</tt> (I leave you to work out the commands needed after that).

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

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 [[MX_Administrative_Interface#MySQL_settings|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.

<pre>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;</pre>

As I type this, Cumulus MX has no exception handling if the username and password defined in the settings do not exist in the database, therefore in this situation it will crash out (with message press Enter to close).

=== Commands to ensure PhpMyAdmin will work ===

The following sequence of commands will
* add the mysqli module to our php install,
*will restart apache,
*will create a symbolic link for the phpadmin installation to the server web root so it can be seen (and used) in our browser,
*will give the standard user (pi) ownership of the database files and the web pages:

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

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

You can view any index.php or PHPMyAdmin web page in your browser by prefixing the address with your Pi 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:
#real-time
#standard interval
#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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe monthly</tt> to run the executable. The first parameter is "monthly" even if the table has a different name.
#if the table name is defined in the admin interface, and the table already exists in the database with the correct columns defined, then the executable will use that table.
#There is an optional second parameter that specifies the log file name to read.
#*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"),
# 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 <tt>cd CumulusMX && sudo mono ExportMySQL.exe dayfile</tt>.

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 <tt>sudo service apache2 restart</tt> or (if we just want the Apache configuration reloaded) by typing <tt>sudo systemctl reload apache2</tt>. Similar commands apply for other web servers.

We will need to restart Apache (or whichever web server we installed) any time we change our php.ini files, database passwords, and anything else that is checked when the web server starts.

== 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 Pi====

On your Pi, there are various applications that you can run with graphical interfaces, these let you achieve what you want by on screen selections, without having to learn what Linux commands to type in. You might wish to use these when you are operating your Pi in a headless state (without keyboard or monitor), so you want to see these graphical interfaces on your PC. See [https://thepihut.com/blogs/raspberry-pi-tutorials/remotely-accessing-the-raspberry-pi-via-rdp-gui-mode this tutorial] for one way to do this. Although this article does not cover such options that let you see graphical user interfaces, these let your other device see selection screens, browsing screens, and similar, just as you would see them if you had a monitor connected to your Pi.

An alternative way to work on your Pi is its its terminal mode. This lets you use '''sudo''' to overcome the fact that the default user does not have '''root''' rights, and can therefore allow you to achieve tasks where a graphical interface fails because of the ownership of the part of the file structure where your action is taking place. The commands you type into a terminal screen on a Pi can also be typed into a terminal screen on your PC, and you will see the same responses. For this to work, you need to switch Secure Shell Home (SSH) on as that is what controls access over a network. This article explains most aspects of SSH in the next few sub-sections.

==== 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 <tt>touch ssh</tt>, 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 <tt>ssh pi@raspberrypi</tt> to get access to default user in your Pi.

(As an alternative for Windows operating system, you can install PuTTY, this has the advantage that you can enter the connection settings into it, and configure various other options, and these are remembered, so might make it easier to use. '''PuTTY''' software (an SSH client for Windows) can be downloaded from <tt>https://www.putty.org/</tt>).

When you are using a terminal, it is a sequential device, each line is either something you type in or something sent back in reply. The action that result from any key combinations depend on your terminal application, not just whatever you are running on your Pi. Your mouse can't affect cursor location, but the mouse might be needed to select text, the left click might copy what is selected, and the right click might paste (what is in your PC's clipboard) at current cursor position.

You can use SSH access from your PC:
* when you need to edit a file on your Pi,
*or do a file transfer between Pi and PC or vice versa.

=== Running MX from your PC ===

If you choose to use the simple <tt>sudo mono CumulusMX.exe</tt> command in a terminal (or command window or Powershell) session on your PC, remember MX will detect if that session is ended and will shut down MX. This means if you want to keep MX running you need to keep your session on your PC running and you loose the advantage of saving electricity by running MX on a PI because your PC remains on.

As I type this a new release 3.8.0 is to allow MX to run as a service, and a future release is planned to change the associated script, so anything I write here might become obsolete, and the next sub-section gives you some links to the support forum about alternatives to the new feature. Hopefully, someone will edit this article, when instructions have settled down and won't change on next release. Basically, the ability to run MX as a service, means that MX actually runs independent of the session that starts or stops the service; and therefore implies you can shut down your PC without stopping MX.

Hopefully someone will add notes to this article about the running as service option. I have not tried it, so I cannot add such notes.

=== Older information about using a PC and a PI ===

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

===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:
<pre>ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=GB

network={
ssid="YourNetwork"
psk="YourNetworkPassword"
key_mgmt=WPA-PSK
}</pre>

*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 [https://cumulus.hosiene.co.uk/viewtopic.php?p=139422#p139422 Notes by ExperiMentor] (a contributor, in Switzerland, to the Cumulus support forum).

===Downloading MX distribution on PC===

If you download MX on your PC, then you will probably unzip the distribution there, and use a tool like FileZilla to copy the installation to your Pi.
First of all you need to configure FileZilla Client, unless you have done that previously and saved the configuration:
*The quickest way is to fill out the "quick connect boxes".
* Host - this is the IPv4 address of your Pi, I can't tell you what it is, but it is likely to be '''192.168.z.xy''' where the z is probably "1", but it could be another single figure like 0, and the xy is two (or perhaps three) figures you can find out by looking for "pi" (or whatever host username you have set on your Pi) in the admin interface for your hub or router. (It can also be found out by typing <tt>hostname -I</tt>). Most networks are setup in a way that the subnet range is from 192.168.1.0 to 192.168.1.255.
* Username - the default for this is '''raspberrypi''' (although on older Pi it might be '''Pi'''), but you can may have changed this (as described earlier). (It can be found by typing <tt>hostname</tt>) or by looking at the contents of the file '''/etc/hostname'''.
* Password - again the default for this is '''raspberry''' but we changed it as one of the mandatory configurations earlier.
* Port - 22 is the default, and I have not said how you can change this!

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

If you are going to continue using Filezilla, there are options to save the current configuration and to set up a number of alternative configurations (specifying in advanced tab different locations on your PC and different locations on your Pi).