Raspberry Pi Setup

From MuonPi-Wiki
Jump to navigation Jump to search

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.

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 here on microSD card (any version with or without desktop). For an headless install (without monitor and mouse/keyboard), we recommend following this 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 sudo raspi-config >> Change User Password or on the command line with passwd
  • Enable the serial interface (UART) and disable the login shell via the UART. In terminal: sudo raspi-config >> Interfacing Options >> Serial >> Login shell over serial: No >> Enable serial hardware: Yes
  • Enable I2C Interface: In terminal: sudo raspi-config >> 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: sudo raspi-config >> 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: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):

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 https://archive.muonpi.org/raspbian buster main > /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:


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.

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