Skip to content

docs: convert the software page to the house style #588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brickbots merged 4 commits into from
Aug 10, 2026
Merged

docs: convert the software page to the house style #588

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5c8dac0
docs: convert the software page to the house style
brickbots Aug 8, 2026
0a6fd39
docs: keep "boot" for the machine's own startup sequence
brickbots Aug 8, 2026
9e90b92
docs(software): un-nest the SPI/I2C setup steps
brickbots Aug 9, 2026
40f3ee3
docs(software): the last stray "reboot" -> "boot"
brickbots Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 35 additions & 35 deletions docs/source/software.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
Software Setup
==============

Once you've built or otherwise obtained a PiFinder, here's how to set up a fresh SD card to run it. The recommended way is to download the current prebuilt release image and use the Raspberry Pi imager to burn it and configure your wifi. If you prefer, you can build an image from scratch following the instructions below.
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 get PiFinder onto an SD card, however you built or purchased the unit.
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.


* Download the latest release image from our `releases page <https://github.com/brickbots/PiFinder/releases>`_

* Install the Raspberry Pi imager: https://www.raspberrypi.com/software/

* Run the imager, click 'Choose OS', select 'Use Custom', then choose the image you downloaded
* Run the imager, click 'Choose OS', select 'Use Custom', then select the image you downloaded

.. image:: images/software/rpi_imager_001.png
:width: 47%
Expand All @@ -25,11 +25,11 @@ The image files on our release pages bundle the correct Raspberry Pi OS version,

* 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
* 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, but the PiFinder software ignores these; they only affect the underlying operating system.
* You can also set your locale and keyboard. These affect only the underlying operating system, and the PiFinder software ignores them.

.. image:: images/software/rpi_imager_003.png
:width: 47%
Expand All @@ -38,48 +38,47 @@ The image files on our release pages bundle the correct Raspberry Pi OS version,
:width: 47%

.. important::
Do not set the hostname or username/password. SSH is enabled on this image by default.
Do not set the hostname or username/password. This image enables SSH by default.

* Click 'Select Storage' and choose the SD card on your computer
* 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 writing is complete, insert the SD card into your PiFinder and power it up. The first boot takes a bit longer as it expands the filesystem to fill the card, so be patient.
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.

With the software installed, you're ready for the :doc:`Quick Start Guide<quick_start>` and a night of observing.
The software is now installed. Continue to the :doc:`Quick Start Guide<quick_start>` for a night of observing.

Build From Scratch
------------------

.. warning::

You probably do not want to do this. These instructions are primarily for developers
who are making a new image file from scratch. To just use your PiFinder you will
want to use the instructions above to download and use a pre-built image for your
sd card.
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 this completely headless (no monitor or keyboard) if you like.
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. The software is designed and tested for a specific version with each release.
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 using the Raspberry Pi imager. It's available for most platforms and makes it easy to set up wifi and SSH.
* 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)

* **Make sure you select the Legacy Bullseye option here**
* **Select the Legacy Bullseye option here**

* Set up SSH / Wifi / User and Host name using the gear icon. Below is a screengrab showing the suggested settings.
* 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.
Expand All @@ -90,23 +89,24 @@ General Pi Setup



* Once the image is burned to an SD card, insert it into the PiFinder and power it up. The first boot will probably take a few minutes.
* 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
* Then I4 - SPI and choose Enable
* Then I5 - I2C and choose Enable
* 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 rest of the setup is handled by the ``pifinder_setup.sh`` script in this repo. Download and run it in one step:
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``

Expand All @@ -116,14 +116,14 @@ The script will:
* Clone this repo
* Install the needed packages/dependencies
* Download some required astronomy data files
* Set up Wifi access point capabilities
* 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 reboot
* Set up the PiFinder service to start on boot

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

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

.. image:: ../../images/screenshots/WELCOME_001_docs.png
:alt: Startup log
Expand All @@ -132,11 +132,11 @@ Booting takes up to two minutes, but you should see the startup screen before lo
Catalog Image Download
^^^^^^^^^^^^^^^^^^^^^^

The PiFinder can display catalog object images when they're present on your SD card. These images take about 5gb of space and can take several hours or more to download, but you can cancel and resume at any time.
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 :ref:`software:prebuilt release image` already includes these images and is much quicker to download as a single file from your main computer.
The :ref:`software: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.
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:

Expand All @@ -152,4 +152,4 @@ The PiFinder checks which images are missing and starts downloading. You can mo
:alt: Image Download


There are 13,000+ images, so it takes a while, but you can do it across multiple sessions. The PiFinder uses whichever images you have on hand each time you observe.
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.
Loading