Kit software setup
This page describes how to set up the software services with an official AstroPlant image.
Last updated
This page describes how to set up the software services with an official AstroPlant image.
Last updated
The software is being beta-tested. There might be bugs or stability issues. Bug reports are appreciated!
The AstroPlant operating system image has all AstroPlant prerequisites installed and configures the Raspberry Pi as an IOT device. To complete the setup, you will need to set up networking and create the kit configuration file. Some knowledge of Linux and the terminal (Bash) is required.
Note: we used to provide a hotspot image alongside this bare image. We've removed the hotspot image for now, as it was proving troublesome after the upgrade to Raspberry OS Buster. The hotspot image created a Wi-Fi hotspot on the Raspberry Pi with which you could connect in order to configure the kit with a web browser, rather than through a terminal. We're looking into ways of bringing this functionality back in the future. Download the operating system image here:
image_2022-09-09-AstroPlant-1.0.0b8.1-bare.zip (548MB)
Make sure all your peripherals are connected before continuing.
Follow these steps to register and configure a kit if you haven't already done so:
Take special note of the kit's serial and password shown when you create the kit on the website. The kit's password can be regenerated if needed (the password will be shown only once; if lost, a new password needs to be generated).
To flash the image to an SD card, make sure the SD card is inserted in your computer. An easy way to flash the image is to use a program called Etcher.
1. Start Etcher. 2. Select the downloaded image. 3. Select the SD card as drive (ensure you have the correct SD card selected). 4. Flash to the SD card.
Skip this step if you are setting up your Raspberry Pi with wired networking.
You have two options to configure wireless networking: you can either connect a monitor and keyboard to the Raspberry Pi (Step 3a) or you can configure the networking headlessly (Step 3b).
Connect the monitor to the Mini HDMI port on the Raspberry Pi. Connect the keyboard to the Micro USB port labeled "USB".
Insert the SD card into the Raspberry Pi and turn on the power. The first boot of a fresh Raspberry Pi install will take some time. On a Raspberry Pi Zero W it may take a few minutes.
The monitor should display a terminal asking for login details. Log in using username pi and password raspberry.
Wi-Fi is configured using the operating system's raspi-config utility. Start the utility by running the following command
You should now be presented a menu of system configuration options.
Choose the first option, "System Options," by pressing Enter.
Now choose, "Wireless LAN," again the first option, by pressing Enter.
You are now asked to select your country from a list. You can scroll using the arrow keys. Confirm your choice by pressing the Enter key. Setting the correct country is important for regulatory requirements regarding radio frequencies.
You should now see a message confirming your choice, press Enter to continue.
The utility now asks for the "SSID", this is the name of your Wi-Fi. Please enter the name precisely. Wi-Fi names are case-sensitive. Press Enter to confirm.
You should now be asked for the Wireless network's passphrase (this is the Wi-Fi password). Type it and press Enter to confirm.
You are now done setting up the Wi-Fi details, and are back at the main menu of the utility. Press tab or the right arrow key to select "Finish", and hit Enter.
You can rerun this utility to update Wi-Fi details and to add more wireless networks.
Reboot the kit by running
After a moment you'll be presented with the login screen again. Enter your details. You can now confirm your kit's internet is working by trying to ping, for example, Google. Run the following command
If your kit is connected successfully to the internet, you should see messages appearing stating something like 64 bytes from .... This will go on forever; exit the process by pressing Ctrl+C (both keys at the same time). If you do not see these messages, or see other messages, your internet is likely not working. Please follow the previous steps again to make sure you did not accidentally make a typo when entering the Wi-Fi details.
Go to Step 4.
Mount the SD card's boot partition filesystem on your computer. The details on how to do this depend on your operating system. On Windows the boot partition will be the only filesystem visible. On Linux or Mac you will see both a boot and a rootfs partition on the SD card. Make sure you use the filesystem on the boot partition.
At the top-level of the boot filesystem create a new file wpa_supplicant.conf using your favorite plain text editor and ensure it reads the following, replace the country code NL with the two-letter ISO 3166-1 alpha-2 code of the country in which you're using the kit. You can find a list of country codes here.
Also replace YOUR NETWORK with the name of the wireless network that the Raspberry Pi should connect to and YOUR NETWORK PASSWORD with the network's password. These details are case-sensitive.
Eject/unmount the SD card from your computer. Insert the SD card into the Raspberry Pi and turn on the power. The first boot of a fresh Raspberry Pi install will take some time. On a Raspberry Pi Zero W it may take a few minutes.
Once you've given the Raspberry Pi a few minutes to perform its first boot, connect to the Raspberry Pi over the network using SSH (the Windows Terminal includes an SSH client in Windows 10 and 11). By default you can log in using username pi and password raspberry.
If your Raspberry Pi cannot be found, use a tool like Angry IP scanner to figure out the IP address of your Raspberry Pi. Alternatively, check your router's DHCP lease table. Then you can connect via ssh pi@<ip_address>.
Next we'll configure the kit's connection to the AstroPlant cloud. Create a file named kit_config.toml in the home directory (/home/pi), by running
Edit the file to read the following, replacing YOUR KIT SERIAL HERE and YOUR KIT PASSWORD HERE with your kit's serial and password generated in Step 2.
Save the file by pressing Ctrl+O and hitting enter. Close the file by pressing Ctrl+X.
Restart the AstroPlant software on the kit by running
On the next boot, the AstroPlant's software service will start automatically.
Visit your kit's dashboard at https://app.astroplant.io. You should start seeing measurements being made.
If the kit does not seem to work, you can look at logs that may help debug the issue. Run
If your LCD display does not work, your LCD display module may use a different I²C address than we've just configured in kit_config.toml. The configured address of 0x27 is the most common; the next one to try is 0x3f. If this doesn't work either, you can use the I2C-detect tool on the command line to find the address of the LCD screen. Bare in mind that the LUX sensor also uses I²C at address 0x23.
See the Setup FAQ for more info.
See the following GitHub pages for our software:
