Repository navigation
Prepping the Raspberry PI
This is a very high level overview of how to prepare a Raspberry Pi to run the PikaReader4Pi system. It assumes basic knowledge of a Linux based environment. Thankfully there are a lot of tutorials available on the internet if you need help.
We recommend that you use a Raspberry Pi 4b with 1G of ram or a newer Raspberry Pi 5 based system. Note that the PikaReader system does not require a lot of ram, so a 1G or 2G system is more than adequate. The system does not also require a lot of CPU. At full load with around 1000 raw reads/s the system will use one of the four cores on a Raspberry Pi 4b.
For the purposes of this project, we are assuming that the operating system is installed on a standard SD flash card. This will result in a system that takes about 30 seconds to boot but is generally a lot simpler to setup than a "faster" SSD based Pi 5 with an NVMe based SSD on a hat.
Start by downloading the official Rasbperry Pi Imager to your system.
Insert a 32G or larger SD card into your system. We highly recommend that you purchase a "high endurance" card from a reputable source to avoid (e.g. NOT any vendor that co-mingles inventory. B&H is usually a good source.) Note that a 32G card will hold over a million chip reads.
Choose the Trixie Lite OS under the "Raspberry Pi OS (other)" section. It is usually listed as "Raspberry Pi OS (64-bit) Lite (Debian 13 Trixie)" or something similar.
Before clicking the Write option, the imager will prompt you to apply OS customization settings. This is where you can set things like the hostname, username / password, timezone, and optionally configure the wireless lan if you are not using ethernet.
Full walkthroughs are available on the internet. See https://raspberrytips.com/install-raspbian-raspberry-pi/ for an example.
This unit is battery operated and the system has no "nice" off button. The typical way to power off the system is the computer equivalent of a a rug pull. The default Raspberry Pi operating system uses the EXT4 filesystem and enabling data journaling will effectively mitigate any risk of critical data loss in the event of a sudden power off of the system. Once you have the system up and running, it is highly recommended that you enable filesystem journaling as follows:
- Add "noatime,data=journal,commit=1" to root partition for /etc/fstab
- Add "rootflags=data=journal" to end of config line of /boot/firmware/cmdline.txt
Note that there are several UPS Hats available for the Raspberry Pi, and you are welcome to install one if you wish. Just be careful about how you power the unit and ensure that the UPS will auto-restart the system once power is restored.
Setup of the Adafruit Ultimate GPS hat is best covered in this article: https://austinsnerdythings.com/2025/02/14/revisiting-microsecond-accurate-ntp-for-raspberry-pi-with-gps-pps-in-2025/
Note that you will need to pay attention to the fact that the GPS hat uses GPIO pin #4 for the PPS signal. also make sure you disable the serial console with the "sudo raspi-config noinit do_serial_cons 1" command and reboot before proceeding.
The LCD, INA237 voltage meter, and PiRTC real time clock make use of the I2C system. Enable the system and install the needed software with the following commands:
sudo raspi-config nonint do_i2c 0
sudo apt install i2c-tools
Prepare for the installation of PikaReader and PikaReader4Pi by installing the required system packages
sudo apt-get install openjdk-25-jdk
sudo apt-get install python3-websockets python3-tomlkit python3-smbus2 python3-rpi-lgpio
Ensuring an accurate time source is critical to the functioning of the system. While the GPS based sync can provide a very accurate timesource, and the NTP setup also provides a very good reference, there are times where GPS will not work (indoors) and you do not have a working internet connection to make use of NTP. In those cases, having a local RTC that is accurate to within a second or two per month will save the day.
The recommended PiRTC is based on the DS3231 chip which makes use of a temperature controlled oscillator (aka a TCOX). Unlike a normal non-temperature controlled clock that is accurate to within 5 or so minutes per month, this one will ensure that the local clock is within a second or so even if it is powered off for a week or two. Follow the setup guide at https://learn.adafruit.com/adding-a-real-time-clock-to-raspberry-pi We highly recommend that you purchase the one designed to go on top of the GPIO header at https://www.adafruit.com/product/4282 to save yourself some headaches. Don't forget the CR1220 coin cell battery.
Note to Raspberry Pi 5 users: The Pi 5 comes with a built in RTC, but the battery is not included. If you want to use the higher precision DS3231 based RTC, don't forget to first disable the built in RTC.
It is highly recommended to use a dedicated USB Network Adapter to connect to the reader and place any readers on this dedicated connection. This way all of the readers can be configured with the exact same IP address and not interfere with any other PikaReader units on your network.
WARNING: A USB-3 connected network adapter will jam the GPS signal! Do not connect a USB network adapter to one of the two USB-3 ports (the blue ones) on your raspberry pi. USB-3 has a nasty habit of spewing rf interference in the key frequencies that gps operates on and will quickly drown out any legitimate gps signal. Purchase an adapter that will work with the lower power provided by USB-2 and connect the adapter to the USB 2 interface instead.
Upon adding a USB network adapter, the system will create a "Wired connection 2" network profile. Configure this network with a static IP address and disable ipv6 as follows:
sudo nmcli con mod 'Wired connection 2' ipv4.address 192.0.2.1/24
sudo nmcli con modify "Wired connection 2" ipv6.method disabled
This will setup the network to use the 192.0.2.1 "TEST-NET-1 " address range. This range is almost never used for any internal uses; network admins almost always pick one of the more common RFC1918 ranges (10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16) so this should help avoid any routing issues.
Configure your first reader with an IP address of 192.0.2.10 with the same class-c subnet (a "/24" or 255.255.255.0) and a default router of "192.0.2.1". You can increment this IP as needed if you have more than one reader (.11, .12, and so on).
If you have multiple readers, you will need to install a small switch to place between the dedicated NIC and the readers. Optionally, you can connect the main NIC to a managed switch and setup a dedicated and isolated vlan for the readers. This is a bit beyond the scope of this guide, but google or ChatGPT / Claude should be your friends.
If you want to boot the system when it is not connected to a network, disable the system startup stript that waits for the network with the following two commands:
sudo service NetworkManager-wait-online disable
sudo systemctl mask NetworkManager-wait-online.service
While the wired network connection is easy, a wireless network makes race day setup a bit faster and easier. If you want to
sudo raspi-config nonint do_wifi_country US
Run the following command as root:
nmcli connection add \
type wifi \
ifname wlan0 \
con-name "<Network Name>" \
ssid "<Network Name>" \
wifi-sec.key-mgmt wpa-psk \
wifi-sec.psk "Password"
nmcli connection modify "<Network Name>" connection.autoconnect yes
Step 3: Setup the system to disable the wireless network if you connect an ethernet cable to the system:
As root, create a file at /etc/NetworkManager/dispatcher.d/99-wifi-exclusive.sh with the following script:
# The system device name for your primary interface
PRIMARY_INTERFACE="eth0"
INTERFACE="$1"
ACTION="$2"
if [ "$INTERFACE" = "$PRIMARY_INTERFACE" ]; then
case "$ACTION" in
up)
# Primary wired connection is active -> Kill all Wi-Fi radio
nmcli radio wifi off
;;
down)
# Primary wired connection went down -> Turn Wi-Fi radio back on
nmcli radio wifi on
;;
esac
fi
Run the following two commands as root:
chown root:root /etc/NetworkManager/dispatcher.d/99-wifi-exclusive.sh
chmod 744 /etc/NetworkManager/dispatcher.d/99-wifi-exclusive.sh