Kit software setup
This page describes how to set up the software services with an official AstroPlant image.
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:
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).
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.
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
Wi-Fi is configured using the operating system's
raspi-configutility. Start the utility by running the following command
$ sudo raspi-config
You should now be presented a menu of system configuration options.
- 1.Choose the first option, "System Options," by pressing Enter.
- 2.Now choose, "Wireless LAN," again the first option, by pressing Enter.
- 3.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.
- 4.You should now see a message confirming your choice, press Enter to continue.
- 5.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.
- 6.You should now be asked for the Wireless network's passphrase (this is the Wi-Fi password). Type it and press Enter to confirm.
- 7.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
$ sudo reboot
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
$ ping google.com
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.
Mount the SD card's
bootpartition filesystem on your computer. The details on how to do this depend on your operating system. On Windows the
bootpartition will be the only filesystem visible. On Linux or Mac you will see both a
rootfspartition on the SD card. Make sure you use the filesystem on the
At the top-level of the
bootfilesystem create a new file
wpa_supplicant.confusing your favorite plain text editor and ensure it reads the following, replace the country code
NLwith 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.
YOUR NETWORKwith the name of the wireless network that the Raspberry Pi should connect to and
YOUR NETWORK PASSWORDwith the network's password. These details are case-sensitive.
psk="YOUR NETWORK PASSWORD"
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
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
Next we'll configure the kit's connection to the AstroPlant cloud. Create a file named
kit_config.tomlin the home directory (
/home/pi), by running
$ nano /home/pi/kit_config.toml
host = "mqtt.astroplant.io"
port = 1883
serial = "YOUR KIT SERIAL HERE"
secret = "YOUR KIT PASSWORD HERE"
level = "INFO"
module_name = "astroplant_peripheral_device_library.lcd"
class_name = "LCD"
i2cAddress = "0x27"
Save the file by pressing
Ctrl+Oand hitting enter. Close the file by pressing
Restart the AstroPlant software on the kit by running
$ sudo systemctl restart astroplant.service
On the next boot, the AstroPlant's software service will start automatically.
If the kit does not seem to work, you can look at logs that may help debug the issue. Run
$ journalctl -u astroplant.service -n 100 --no-pager
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
0x27is 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
See the following GitHub pages for our software: