Software Setup

Once you’ve built or otherwise obtained a PiFinder, set up a fresh SD card to run it. The recommended way is to download the current prebuilt release image, then use the Raspberry Pi imager to write it to the card and set up your WiFi. If you prefer, build an image from scratch by following the instructions below.

Prebuilt Release Image

The image files on our release pages bundle the correct Raspberry Pi OS version, the installed and configured PiFinder software, and all the deep-sky catalog images. This is the recommended way to put the PiFinder software on an SD card, whether you built or bought your PiFinder.

_images/rpi_imager_001.png _images/rpi_imager_002.png

  • To let the PiFinder connect to your network, click the gear icon at the lower left and fill in:

    • SSID: The name of your WiFi network

    • Password: The password for your WiFi network

    • Wireless LAN Country: Where you live, so WiFi follows local regulations

  • You can also set your locale and keyboard. These affect only the underlying operating system, and the PiFinder software ignores them.

_images/rpi_imager_003.png _images/rpi_imager_004.png

Important

Do not set the hostname or username/password. This image enables SSH by default.

  • Click ‘Select Storage’ and select the SD card on your computer

  • Click ‘Write’ to start

Note

If the imager reports that the image is “not a multiple of 512 bytes” (or otherwise refuses to write it), the download was incomplete or corrupted. Download the release image again and retry.

Once the imager finishes writing, insert the SD card into your PiFinder and turn it on. The first boot takes longer than usual, because the PiFinder expands the filesystem to fill the card. Be patient.

Match the Settings to Your PiFinder

Release images from v2.6.3 onward come set up for a rev4 PiFinder in the right-hand position:

  • Camera Type is v3 - imx462

  • GPS Baud Rate is 115200 (UBlox-10)

  • PiFinder Type is Rev4 Right

Note

v3 - imx462 is correct for a rev4 PiFinder. The rev4 camera uses the same sensor as a v3, so there is no separate rev4 entry.

If that describes your PiFinder, there is nothing to change. For any other PiFinder, correct these settings after the first boot. From the main menu, select Settings, scroll down to Advanced, then:

  • Select PiFinder Type and select the entry that matches your PiFinder and its position. A wrong type reverses the Push-To directions. See Configuration Setup for what each entry means.

  • On a v3 or v2.5 PiFinder, select GPS Settings, then GPS Baud Rate, and set it to 9600 (standard). These PiFinders have an older GPS receiver. At the wrong baud rate the GPS never locks.

  • On a v3 PiFinder, check the Camera Type. A v3 ships with either the v3 - imx462 or the v3 - imx296 sensor. If yours has the imx296, select v3 - imx296, then turn the PiFinder fully off and on again. A software restart alone won’t apply a camera change. If you’re not sure which sensor you have, leave the setting alone. A blank camera view means you have the other sensor, so select it and turn the PiFinder fully off and on again. See The camera view is blank or black. A v2.5 PiFinder with its original camera takes v2 - imx477.

A rev4 PiFinder rotated to the left or straight-back position needs only the PiFinder Type change. The camera and GPS settings already match.

The software is now installed. Continue to the Quick Start Guide for a night of observing.

Build From Scratch

Warning

You probably do not want to do this. These instructions are for developers who build a new image file from scratch. To just use your PiFinder, follow the instructions above to download a prebuilt image and write it to your SD card.

You can do all of this headless (no monitor or keyboard).

General Pi Setup

Important

You must use the specific Raspberry Pi OS version listed here, or the PiFinder software will not work. We design and test the software for one specific version with each release.

  • Create the image with the Raspberry Pi imager. It’s available for most platforms and makes it easy to set up WiFi and SSH.

    • Select the 64-Bit version of Pi OS (Legacy) Lite (No Desktop Environment)

      • Select the Legacy Bullseye option here

    • Set up SSH, WiFi, and the user and host name with the gear icon. The screenshot below shows the suggested settings.

      • The username must be pifinder

      • Customize the host name, password, network settings, and locale for your needs.

Raspberry Pi Imager settings

  • Once you’ve written the image to an SD card, insert it into the PiFinder and turn it on. The first boot takes a few minutes.

  • SSH into the PiFinder using pifinder@pifinder.local and the password you set up.

  • Update all packages. This isn’t strictly required, but it’s good practice.

    • sudo apt update

    • sudo apt upgrade

  • Enable SPI / I2C, which the screen and IMU use to communicate.

    • Run sudo raspi-config

    • Select 3 - Interface Options

    • Select I4 - SPI, then select Enable

    • Select I5 - I2C, then select Enable

PiFinder Software Install

You now have a fresh install of Raspberry Pi OS. The pifinder_setup.sh script in this repo handles the rest of the setup. Download and run it in one step:

wget -O - https://raw.githubusercontent.com/brickbots/PiFinder/release/pifinder_setup.sh | bash

The script will:

  • Clone this repo

  • Install the needed packages/dependencies

  • Download some required astronomy data files

  • Set up WiFi access point capabilities

  • Create a samba share for pulling images and observation logs and adding observing lists

  • Set up the PiFinder service to start on boot

Once the script finishes, restart the PiFinder: sudo shutdown -r now

Booting takes up to two minutes, but the startup screen appears before long:

Startup log

Catalog Image Download

The PiFinder can display catalog object images when they’re on your SD card. These images use about 5gb of space and can take several hours or more to download. You can cancel and resume at any time.

The Prebuilt Release Image already includes these images. It’s much quicker to download as a single file from your main computer.

To download the catalog images, put your PiFinder in WiFi client mode so it can reach the internet, then SSH into it using the password you set up initially.

Once connected, type:

cd PiFinder/python
python -m PiFinder.get_images

The PiFinder checks which images are missing and starts downloading. You can monitor progress on the status bar.

Image Download

There are 13,000+ images, so the download takes a while. You can do it across multiple sessions. The PiFinder uses whichever images you have each time you observe.