MuonPi-Wiki - User contributions [en-gb]

Setup Mail Client

2021-08-29T20:12:25Z

Dtreffenstaedt:

If you want to setup your mail client to use the Mail address issued by MuonPi.org, use the below settings for setup.

Do not use your full E-Mail address as username.

{| class="wikitable"
|+ Settings
| || '''IMAP''' || '''SMTP'''
|-
| Address || mail.muonpi.org || mail.muonpi.org
|-
| Security || TLS || STARTTLS
|-
| Authentication Method || Normal password || Normal password
|-
| Port || 993 || 587
|-
| Username || <username> || <username>
|-
| Password || <password> || <password>
|}

Raspberry Pi Setup

2021-08-21T13:37:37Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-linux Linux] [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-mac-os MacOS] [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-windows Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/computers/configuration.html#setting-up-a-headless-raspberry-pi headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
* Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
* Update your system:
sudo apt update && sudo apt upgrade
* Change the default password of the user <code>pi</code>:
passwd
* (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
sudo raspi-config
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART:
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
* Enable I2C Interface:
3 Interface Options -> P5 I2C -> Yes (enable)
* (Optional) '''Enable SSH''':
3 Interface Options -> P2 SSH -> Yes (enable)

=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
* Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
* edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-08-21T13:36:38Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-linux Linux] [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-mac-os MacOS] [https://www.raspberrypi.org/documentation/computers/getting-started.html#installing-images-on-windows Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
* Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
* Update your system:
sudo apt update && sudo apt upgrade
* Change the default password of the user <code>pi</code>:
passwd
* (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
sudo raspi-config
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART:
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
* Enable I2C Interface:
3 Interface Options -> P5 I2C -> Yes (enable)
* (Optional) '''Enable SSH''':
3 Interface Options -> P2 SSH -> Yes (enable)

=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
* Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
* edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Detector Status

2021-07-30T11:19:44Z

Dtreffenstaedt: /* Possible detector status */

= Real-Time Analysis =
The incoming data from all detectors is analysed in real-time before being written to the database.

This analysis consists of the calculation of coincidences between all possible detector pairs. Additionally each individual and total coincidence detection rate is determined.

In order to ensure the validity of the data at all times, each detectors reliability is judged.

=== Reliability ===

Determining factors include e.g. quality of GNSS signal, effective [https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) DOP] or the steadieness of detection rate.

For a detailed view, you can check out the relevant code at [https://github.com/MuonPi/muondetector-cluster/blob/3797637b2c475c91296d52ffc5f9debdd865369f/src/analysis/detectorstation.cpp#L148-L166 our github].

Additionally to the standard requirements, individual events can cause an instant unreliability mark due to exceptionally bad time resolution or no valid GNSS fix. Those events are automatically rejected.

Compare [https://github.com/MuonPi/muondetector-cluster/blob/3797637b2c475c91296d52ffc5f9debdd865369f/src/analysis/detectorstation.cpp#L116-L120 the code] to see the detailed requirements.

=== Possible detector status ===

{| class="wikitable"
|-
! Status !! Data is processed !! Description
|-
| deleted || no || The detector has not sent data for over 48 hours
|-
| offline || no || The detector is not connected or experiences network problems
|-
| online || no || The detector is recently connected
|-
| reliable || yes || The detector is connected and all parameters are deemed good
|-
| unreliable || no || The detector is connected but experiences network problems or has sub-optimal runtime parameters
|}

=== Possible reasons ===

{| class="wikitable"
|-
! reason !! Description
|-
| miscellaneous || No reason has been specified
|-
| time_accuracy || The mean time accuracy of the detector was outside the specifications
|-
| time_accuracy_extreme || The time accuracy of a single event reached an extreme value
|-
| location_precision || The mean location precision of the detector was outside the specifications
|-
| rate_unstable || The standard deviation of the event rate was too large compared to the mean
|-
| missed_log_interval || The detector missed a log interval (One for unreliable, Three intervals for offline)
|}

Raspberry Pi Setup

2021-07-29T21:10:03Z

Dtreffenstaedt: /* Manual Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
* Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
* Update your system:
sudo apt update && sudo apt upgrade
* Change the default password of the user <code>pi</code>:
passwd
* (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
sudo raspi-config
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART:
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
* Enable I2C Interface:
3 Interface Options -> P5 I2C -> Yes (enable)
* (Optional) '''Enable SSH''':
3 Interface Options -> P2 SSH -> Yes (enable)

=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
* Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
* edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T21:09:25Z

Dtreffenstaedt: /* Interfaces */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system:
sudo apt update && sudo apt upgrade
# Change the default password of the user <code>pi</code>:
passwd
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
sudo raspi-config
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART:
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
* Enable I2C Interface:
3 Interface Options -> P5 I2C -> Yes (enable)
* (Optional) '''Enable SSH''':
3 Interface Options -> P2 SSH -> Yes (enable)

=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T21:09:01Z

Dtreffenstaedt: /* Interfaces */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system:
sudo apt update && sudo apt upgrade
# Change the default password of the user <code>pi</code>:
passwd
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
sudo raspi-config
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART:
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
# Enable I2C Interface:
3 Interface Options -> P5 I2C -> Yes (enable)
# (Optional) '''Enable SSH''':
3 Interface Options -> P2 SSH -> Yes (enable)

=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T21:07:44Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system:
sudo apt update && sudo apt upgrade
# Change the default password of the user <code>pi</code>:
passwd
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code>
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code>
3 Interface Options -> P5 I2C -> Yes (enable)
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code>
3 Interface Options -> P2 SSH -> Yes (enable)
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T21:06:44Z

Dtreffenstaedt: /* Manual Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system:
sudo apt update && sudo apt upgrade
# Change the default password of the user <code>pi</code>:
passwd
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code>
3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code>
3 Interface Options -> P5 I2C -> Yes (enable)
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code>
3 Interface Options -> P2 SSH -> Yes (enable)
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:
sudo apt install wpasupplicant
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:
sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:59:19Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
# Update your system
sudo apt update && sudo apt upgrade
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:59:00Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]
# Update your system
sudo apt update && sudo apt upgrade

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:52:04Z

Dtreffenstaedt: /* Configuration and Start */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration =

Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:46:38Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:45:37Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version. If you prefer to build your own version of the image, check out the [https://github.com/MuonPi/muondetector-image repository].
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]
# Enjoy your detector

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:43:35Z

Dtreffenstaedt: /* Manual Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version.
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]
# Enjoy your detector

= Manual Setup =
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

=== MuonPi software installation ===
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

=== Login with your user credentials (only once) ===

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

=== Start the Daemon ===
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:37:33Z

Dtreffenstaedt:

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version.
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|center]]
# Enjoy your detector

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:36:38Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version.
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frame|left]]
# Enjoy your detector

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:36:21Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version.
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless] network. SSH is already enabled per default in the provided images.
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|frameless|left]]
# Enjoy your detector

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:33:38Z

Dtreffenstaedt: /* Guided Setup */

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =
This is the recommended way of setting up the muondetector software.

# Download the latest muondetector [https://archive.muonpi.org/image/latest/ image]. If you want to use the detector headless or without graphical user interface, select the -lite version, otherwise select the -gui version.
# Install the image onto an SD-Card: [https://www.raspberrypi.org/documentation/installation/installing-images/linux.md Linux] [https://www.raspberrypi.org/documentation/installation/installing-images/mac.md MacOS] [https://www.raspberrypi.org/documentation/installation/installing-images/windows.md Windows]
# (Optional) Setup [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md headless]
# Boot your RaspberryPi
# Open a login console
## Per SSH, or
## Open a terminal on the RaspberryPi
# Follow the Prompts in the terminal
[[File:Screenshot 2021-07-29 22-32-37.png|thumb]]

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

File:Screenshot 2021-07-29 22-32-37.png

2021-07-29T20:33:28Z

Dtreffenstaedt:

MuonPi setup script

Raspberry Pi Setup

2021-07-29T20:06:06Z

Dtreffenstaedt:

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

Raspberry Pi Setup

2021-07-29T20:04:40Z

Dtreffenstaedt:

(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-07-29T20:04:15Z

Dtreffenstaedt: /* Prerequisities */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =

= Manual Setup =
== Prerequisities ==
You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-07-29T20:03:47Z

Dtreffenstaedt:

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__
= Guided Setup =

= Manual Setup =
== Prerequisities ==
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
=== Basic ===
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
=== Interfaces ===
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
=== Network ===
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

== MuonPi software installation ==
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-07-29T20:01:07Z

Dtreffenstaedt: /* Initial Setup */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )

You should have a fully configured RaspberryPi OS system and are ready-to-go to set up the MuonPi after following these steps:
== Basic ==
# Create a fresh install of RaspberryPi OS according to the [https://www.raspberrypi.org/documentation/installation/installing-images/ tutorial]
# Update your system: <code>sudo apt update && sudo apt upgrade</code>
# Change the default password of the user <code>pi</code>: <code>passwd</code>
# (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
== Interfaces ==
# '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P6 Serial Port -> No (login shell over serial) -> Yes (serial port)</code>
# Enable I2C Interface: In terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P5 I2C -> Yes (enable)</code>
# (Optional) '''Enable SSH''': In a terminal: <code>sudo raspi-config</code> <code> 3 Interface Options -> P2 SSH -> Yes (enable) </code>
== Network ==
By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
# Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
# edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code> the configuration should look like this (non-relevant lines not shown):
update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-07-29T19:52:14Z

Dtreffenstaedt:

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )
# Create a fresh install of Raspbian Buster operating system e.g. from [https://www.raspberrypi.org/downloads/raspberry-pi-os/ here] on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
* Change the default password of the user "pi". This is strongly recommended, since connections through ssh will be enabled in the next step which should always have a strong authentication metric. Change it with <code>sudo raspi-config</code> >> Change User Password or on the command line with <code>passwd</code>
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
* Enable I2C Interface: In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> I2C >> Enable: Yes >> Reboot optional
* Enable SSH: The SSH protocol is needed if you want to remotely configure your headless Raspberry Pi. In a terminal: <code>sudo raspi-config</code> >> Interfacing Options >> SSH >> Enable: Yes >> Reboot
* Configure the network connection: By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
* If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
* If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
** Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
** edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code>
the configuration should look like this (non-relevant lines not shown):

update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.
Optionally, update your system by:
sudo apt update && sudo apt upgrade

You should have a fully configured Raspbian system by now and are ready-to-go to set up the MuonPi in the next step.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Detector Status

2021-04-11T07:34:08Z

Dtreffenstaedt: /* Reliability */

= Real-Time Analysis =
The incoming data from all detectors is analysed in real-time before being written to the database.

This analysis consists of the calculation of coincidences between all possible detector pairs. Additionally each individual and total coincidence detection rate is determined.

In order to ensure the validity of the data at all times, each detectors reliability is judged.

=== Reliability ===

Determining factors include e.g. quality of GNSS signal, effective [https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) DOP] or the steadieness of detection rate.

For a detailed view, you can check out the relevant code at [https://github.com/MuonPi/muondetector-cluster/blob/3797637b2c475c91296d52ffc5f9debdd865369f/src/analysis/detectorstation.cpp#L148-L166 our github].

Additionally to the standard requirements, individual events can cause an instant unreliability mark due to exceptionally bad time resolution or no valid GNSS fix. Those events are automatically rejected.

Compare [https://github.com/MuonPi/muondetector-cluster/blob/3797637b2c475c91296d52ffc5f9debdd865369f/src/analysis/detectorstation.cpp#L116-L120 the code] to see the detailed requirements.

=== Possible detector status ===

{| class="wikitable"
|-
! Status !! Data is processed !! Description
|-
| offline || no || The detector is not connected or experiences network problems
|-
| online || no || The detector is recently connected
|-
| reliable || yes || The detector is connected and all parameters are deemed good
|-
| unreliable || no || The detector is connected but experiences network problems or has sub-optimal runtime parameters
|}

=== Possible reasons ===

{| class="wikitable"
|-
! reason !! Description
|-
| miscellaneous || No reason has been specified
|-
| time_accuracy || The mean time accuracy of the detector was outside the specifications
|-
| time_accuracy_extreme || The time accuracy of a single event reached an extreme value
|-
| location_precision || The mean location precision of the detector was outside the specifications
|-
| rate_unstable || The standard deviation of the event rate was too large compared to the mean
|-
| missed_log_interval || The detector missed a log interval (One for unreliable, Three intervals for offline)
|}

Detector Status

2021-04-11T07:32:30Z

Dtreffenstaedt: /* Possible reasons */

= Real-Time Analysis =
The incoming data from all detectors is analysed in real-time before being written to the database.

This analysis consists of the calculation of coincidences between all possible detector pairs. Additionally each individual and total coincidence detection rate is determined.

In order to ensure the validity of the data at all times, each detectors reliability is judged.

=== Reliability ===

Determining factors include e.g. quality of GNSS signal, effective [https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) DOP] or the steadieness of detection rate.

For a detailed view, you can check out the relevant code at [https://github.com/MuonPi/muondetector-cluster/blob/929145e792dc84eb80b28bf62f8d37236fb681cf/src/detector.cpp#L139-L147 our github].

Additionally to the standard requirements, individual events can cause an instant unreliability mark due to exceptionally bad time resolution or no valid GNSS fix. Those events are automatically rejected.

Compare [https://github.com/MuonPi/muondetector-cluster/blob/929145e792dc84eb80b28bf62f8d37236fb681cf/src/detector.cpp#L107-L111 the code] to see the detailed requirements.

=== Possible detector status ===

{| class="wikitable"
|-
! Status !! Data is processed !! Description
|-
| offline || no || The detector is not connected or experiences network problems
|-
| online || no || The detector is recently connected
|-
| reliable || yes || The detector is connected and all parameters are deemed good
|-
| unreliable || no || The detector is connected but experiences network problems or has sub-optimal runtime parameters
|}

=== Possible reasons ===

{| class="wikitable"
|-
! reason !! Description
|-
| miscellaneous || No reason has been specified
|-
| time_accuracy || The mean time accuracy of the detector was outside the specifications
|-
| time_accuracy_extreme || The time accuracy of a single event reached an extreme value
|-
| location_precision || The mean location precision of the detector was outside the specifications
|-
| rate_unstable || The standard deviation of the event rate was too large compared to the mean
|-
| missed_log_interval || The detector missed a log interval (One for unreliable, Three intervals for offline)
|}

Detector Status

2021-04-11T07:08:47Z

Dtreffenstaedt: /* Real-Time Analysis */

= Real-Time Analysis =
The incoming data from all detectors is analysed in real-time before being written to the database.

This analysis consists of the calculation of coincidences between all possible detector pairs. Additionally each individual and total coincidence detection rate is determined.

In order to ensure the validity of the data at all times, each detectors reliability is judged.

=== Reliability ===

Determining factors include e.g. quality of GNSS signal, effective [https://en.wikipedia.org/wiki/Dilution_of_precision_(navigation) DOP] or the steadieness of detection rate.

For a detailed view, you can check out the relevant code at [https://github.com/MuonPi/muondetector-cluster/blob/929145e792dc84eb80b28bf62f8d37236fb681cf/src/detector.cpp#L139-L147 our github].

Additionally to the standard requirements, individual events can cause an instant unreliability mark due to exceptionally bad time resolution or no valid GNSS fix. Those events are automatically rejected.

Compare [https://github.com/MuonPi/muondetector-cluster/blob/929145e792dc84eb80b28bf62f8d37236fb681cf/src/detector.cpp#L107-L111 the code] to see the detailed requirements.

=== Possible detector status ===

{| class="wikitable"
|-
! Status !! Data is processed !! Description
|-
| offline || no || The detector is not connected or experiences network problems
|-
| online || no || The detector is recently connected
|-
| reliable || yes || The detector is connected and all parameters are deemed good
|-
| unreliable || no || The detector is connected but experiences network problems or has sub-optimal runtime parameters
|}

=== Possible reasons ===

{| class="wikitable"
|-
! reason !! Description
|-
| miscellaneous || No reason has been specified
|-
| time_accuracy || The mean time accuracy of the detector was outside the specifications
|-
| time_accuracy_extreme || The time accuracy of a single event reached an extreme value
|-
| location_precision || The mean location precision of the detector was outside the specifications
|-
| rate_unstable || The standard deviation of the event rate was too large compared to the mean
|-
| missed_log_interval || The detector missed a log interval (for unreliable. Three intervals for offline)
|}

Detector Status

2021-04-01T15:15:45Z

Dtreffenstaedt: /* Reliability */

Detector Status

2021-04-01T15:15:23Z

Dtreffenstaedt: Created page with "= Real-Time Analysis = The incoming data from all detectors is analysed in real-time before being written to the database. This analysis consists of the calculation of coinci..."

Raspberry Pi Setup

2021-01-30T08:14:48Z

Dtreffenstaedt: /* MuonPi Setup */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )
* Create a fresh install of Raspbian Buster operating system e.g. from [https://www.raspberrypi.org/downloads/raspberry-pi-os/ here] on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
* Change the default password of the user "pi". This is strongly recommended, since connections through ssh will be enabled in the next step which should always have a strong authentication metric. Change it with <code>sudo raspi-config</code> >> Change User Password or on the command line with <code>passwd</code>
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
* Enable I2C Interface: In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> I2C >> Enable: Yes >> Reboot optional
* Enable SSH: The SSH protocol is needed if you want to remotely configure your headless Raspberry Pi. In a terminal: <code>sudo raspi-config</code> >> Interfacing Options >> SSH >> Enable: Yes >> Reboot
* Configure the network connection: By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
* If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
* If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
** Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
** edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code>
the configuration should look like this (non-relevant lines not shown):

update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.
Optionally, update your system by:
sudo apt update && sudo apt upgrade

You should have a fully configured Raspbian system by now and are ready-to-go to set up the MuonPi in the next step.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally.
sudo apt install muondetector-gui
{{Note|Note that if you want to use the gui on the raspberrypi, it is recommended to use the Raspberrypi OS with Desktop preinstalled.|reminder}}

* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-01-30T08:04:22Z

Dtreffenstaedt: /* MuonPi Setup */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )
* Create a fresh install of Raspbian Buster operating system e.g. from [https://www.raspberrypi.org/downloads/raspberry-pi-os/ here] on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
* Change the default password of the user "pi". This is strongly recommended, since connections through ssh will be enabled in the next step which should always have a strong authentication metric. Change it with <code>sudo raspi-config</code> >> Change User Password or on the command line with <code>passwd</code>
* '''Enable the serial interface''' (UART) and '''disable the login shell''' via the UART. In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
* Enable I2C Interface: In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> I2C >> Enable: Yes >> Reboot optional
* Enable SSH: The SSH protocol is needed if you want to remotely configure your headless Raspberry Pi. In a terminal: <code>sudo raspi-config</code> >> Interfacing Options >> SSH >> Enable: Yes >> Reboot
* Configure the network connection: By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
* If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
* If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
** Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
** edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code>
the configuration should look like this (non-relevant lines not shown):

update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.
Optionally, update your system by:
sudo apt update && sudo apt upgrade

You should have a fully configured Raspbian system by now and are ready-to-go to set up the MuonPi in the next step.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
sudo sh -c "curl https://archive.muonpi.org/muondetector.public.key | gpg --dearmor > /etc/apt/trusted.gpg.d/muondetector.gpg"

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally
sudo apt install muondetector-gui
* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-01-29T13:46:54Z

Dtreffenstaedt: /* The Recommended Method */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )
* Create a fresh install of Raspbian Buster operating system e.g. from [https://www.raspberrypi.org/downloads/raspberry-pi-os/ here] on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
* Change the default password of the user "pi". This is strongly recommended, since connections through ssh will be enabled in the next step which should always have a strong authentication metric. Change it with <code>sudo raspi-config</code> >> Change User Password or on the command line with <code>passwd</code>
* Enable the serial interface (UART) and disable the login shell via the UART. In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
* Enable I2C Interface: In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> I2C >> Enable: Yes >> Reboot optional
* Enable SSH: The SSH protocol is needed if you want to remotely configure your headless Raspberry Pi. In a terminal: <code>sudo raspi-config</code> >> Interfacing Options >> SSH >> Enable: Yes >> Reboot
* Configure the network connection: By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
* If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
* If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
** Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
** edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code>
the configuration should look like this (non-relevant lines not shown):

update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.
Optionally, update your system by:
sudo apt update && sudo apt upgrade

You should have a fully configured Raspbian system by now and are ready-to-go to set up the MuonPi in the next step.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
wget -qO - <nowiki>https://archive.muonpi.org/muondetector.public.key</nowiki> | sudo apt-key add -

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally
sudo apt install muondetector-gui
* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.

'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''

When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service

Raspberry Pi Setup

2021-01-29T13:45:50Z

Dtreffenstaedt: /* The Recommended Method */

This article will introduce to you, how to set up a Raspberry Pi from scratch with all software needed to run the detector hardware.

DISCLAIMER: If not stated otherwise, this tutorial is developed on Raspian 10 Buster.

__TOC__

= Initial Setup =
(Requirements: Raspberry Pi Versions 0, 2, 3, 4 (with 40-pin GPIO connector) )
* Create a fresh install of Raspbian Buster operating system e.g. from [https://www.raspberrypi.org/downloads/raspberry-pi-os/ here] on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this [https://www.raspberrypi.org/documentation/configuration/wireless/headless.md guide].
* Change the default password of the user "pi". This is strongly recommended, since connections through ssh will be enabled in the next step which should always have a strong authentication metric. Change it with <code>sudo raspi-config</code> >> Change User Password or on the command line with <code>passwd</code>
* Enable the serial interface (UART) and disable the login shell via the UART. In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
* Enable I2C Interface: In terminal: <code>sudo raspi-config</code> >> Interfacing Options >> I2C >> Enable: Yes >> Reboot optional
* Enable SSH: The SSH protocol is needed if you want to remotely configure your headless Raspberry Pi. In a terminal: <code>sudo raspi-config</code> >> Interfacing Options >> SSH >> Enable: Yes >> Reboot
* Configure the network connection: By default, the RPi is configured to automatically obtain an IP address when a connection is available and DHCP in your local network is active (this should be the case for most local/home networks).
* If you prefer a fixed IP address in a local network: edit the file /etc/dhcpcd.conf. Use the template and uncomment the "Example Static IP Configuration" section with your desired IP address.
* If network access should be established via WiFi, either configure it via the network configuration wizard in the graphical desktop environment (usually network icon in the system bar), or manually following these steps (either method is fine):
** Make sure that the wpa_supplicant package is installed:<code>sudo apt install wpasupplicant</code>
** edit the file /etc/wpa_supplicant/wpa_supplicant.conf:<code>sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</code>
the configuration should look like this (non-relevant lines not shown):

update_config=1
country=DE
network={
ssid="<your network ssid>"
psk="<your wifi password>"
key_mgmt=WPA-PSK
}
Enter your WiFi's SSID and password in the indicated fields.
Finally, restart the system that the changes take effect.
Optionally, update your system by:
sudo apt update && sudo apt upgrade

You should have a fully configured Raspbian system by now and are ready-to-go to set up the MuonPi in the next step.

= MuonPi Setup =
(Requirements: a MuonPi board plugged onto the GPIO connector of the RPi)
* First, add the MuonPi apt repository to your system:
wget -qO - <nowiki>https://archive.muonpi.org/muondetector.public.key</nowiki> | sudo apt-key add -

sudo sh -c "echo deb <nowiki>https://archive.muonpi.org/raspbian buster main</nowiki> > /etc/apt/sources.list.d/muondetector.list"
* Update the repositories:
sudo apt update
* Install the muondetector-daemon package and it's dependencies:
sudo apt install muondetector-daemon
* Optional: install the Graphical User Interface (GUI) program to monitor and control the MuonPi locally
sudo apt install muondetector-gui
* The GUI can connect to the MuonPi over network as well, so it can be installed on other computers in the local network. Currently, binary packages for Raspbian, Ubuntu and Windows are available. The Linux-based versions can be installed from the package repositories (execute steps 1,2 and 4 from this list). The Windows program can be downloaded directly from https://archive.muonpi.org and installed by simply unpacking the zip-archive.

= Configuration and Start =

Now the installation of the muondetector-daemon should be adapted to your setup:

== Configuration ==
Edit the configuration file /etc/muondetector/muondetector.conf: <code>nano /etc/muondetector/muondetector.conf</code>.
Change the settings according to your needs or leave them untouched, if unsure. The comments in the config file should guide you through any required modifications. One option, however, describes the placement of your detector. If you like, choose a stationID descriptor, eg.:
(file: <code>/etc/muondetector/muondetector.conf</code>)
<nowiki>#</nowiki> A unique identifier of the user's station
<nowiki>#</nowiki> leave on default when the user operates a single station
<nowiki>#</nowiki> all detectors of the user are distinguishable on the basis of this id
stationID = "HomeOffice"

(anything which best describes the location of your detector like e.g. "GarageSW", "Bldg16Lab105", "AtticNE"). If you operate only one stationary detector, it may as well be left on the default ID which is "0" (zero).

'''Important''': When operating multiple detectors (under the same user account, see below) the stationID descriptor '''must''' be unique for each detector.

== Login with your user credentials (only once) ==

Before taking the MuonPi detector into operation, you have to set your credentials for publishing data messages to the server via [http://mqtt.org/ MQTT] protocol on first start. This can be managed in two ways, one secure and one where your credentials appear as plain text in the config file:
==== The Recommended Method ====
In a bash shell on the MuonPi, run the command <code>muondetector-login</code>.
'''Note that for the software version 2.0.0 the command to run is <code>sudo runuser -u muonuser -- muondetector-login</code> instead.'''
When asked for sudo access, enter the password of your raspberry pi user.
When asked for your user name and password, enter the credentials supplied to you by a MounPi.org official. The credentials are stored (not in clear text) for all further telemetry connections.

==== Alternative Method ====
Uncomment the <code>mqtt_user</code> and <code>mqtt_password</code> options in <code>/etc/muondetector/muondetector.conf</code> and type your personal username and password into these fields between the quotation marks. Be aware, that these credentials are written in plain text into this file and can be retrieved by malware attacks. However, if you operate a station inside a home network and set up a strong ssh authentication (see above), you should be relatively safe.

== Start the Daemon ==
The daemon should be enabled and started automatically after installation and on every reboot. However, when changing items in the config file, the changes have to be made effective by a daemon restart:
sudo systemctl restart muondetector-daemon.service

To see the current status of the daemon service use following command:
systemctl status muondetector-daemon.service

It can happen that the status shows 'failed' in red, usually a restart of the daemon service resolves this.

If the service should not enable itself by default the status shows a grey 'not loaded'. To enable the service use:
sudo systemctl enable muondetector-daemon.service