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

Guided Setup

This is the recommended way of setting up the muondetector software.

1. Download the latest muondetector 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 repository.
2. Install the image onto an SD-Card:
   Linux
   MacOS
   Windows
3. (Optional) Setup headless network. SSH is already enabled per default in the provided images.
4. Boot your RaspberryPi
5. Open a login console
   1. Per SSH, or
   2. Open a terminal on the RaspberryPi
6. Follow the Prompts in the terminal
7. Update your system

sudo apt update && sudo apt upgrade

Manual Setup

Basic

• Create a fresh install of RaspberryPi OS according to the tutorial
• Update your system:

sudo apt update && sudo apt upgrade

• Change the default password of the user pi:

passwd

• (Optional) For an headless install (without monitor and mouse/keyboard), we recommend following this 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, update your system to make sure, certificates and dependencies are up to date. This might take a while depending on how regularly the system is being updated.

sudo apt update && sudo apt upgrade

• Then, 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 https://archive.muonpi.org/raspbian buster main > /etc/apt/sources.list.d/muondetector.list"

• Update the repositories again:

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.

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

Note that for the software version 2.0.0 the command to run is sudo runuser -u muonuser -- muondetector-login 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 mqtt_user and mqtt_password options in /etc/muondetector/muondetector.conf 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: nano /etc/muondetector/muondetector.conf. 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: /etc/muondetector/muondetector.conf)

# A unique identifier of the user's station
# leave on default when the user operates a single station
# 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.