Links

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!

Get the image

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:

Installing the operating system image

Make sure all your peripherals are connected before continuing.

Step 1. Create your account

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).

Step 2. Flash the image

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.

Step 3. Set up wireless networking on your Raspberry Pi

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).

Step 3a. Set up wireless networking using a monitor and keyboard

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 wpa_supplicant. Open the wpa_supplicant configuration file in a text editor by running the following command
$ nano /etc/wpa_supplicant/wpa_supplicant.conf
By default the file will read
/etc/wpa_supplicant/wpa_supplicant.conf
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
Edit the file so it reads the following, but 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.
/etc/wpa_supplicant/wpa_supplicant.conf
country=NL
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="YOUR NETWORK"
psk="YOUR NETWORK PASSWORD"
}
Save the file by pressing Ctrl+O and hitting enter. Close the file by pressing Ctrl+X.
Reboot the kit by running
$ sudo reboot
Go to Step 4.

Step 3b. Set up wireless networking headlessly

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.
wpa_supplicant.conf
country=NL
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
ssid="YOUR NETWORK"
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 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 [email protected]<ip_address>.

Step 4. Configure the kit details on the Raspberry Pi

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
$ nano /home/pi/kit_config.toml
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.
/home/pi/kit_config.toml
[message_broker]
host = "mqtt.astroplant.io"
port = 1883
[message_broker.auth]
serial = "YOUR KIT SERIAL HERE"
secret = "YOUR KIT PASSWORD HERE"
[debug]
level = "INFO"
[debug.peripheral_display]
module_name = "astroplant_peripheral_device_library.lcd"
class_name = "LCD"
[debug.peripheral_display.configuration]
i2cAddress = "0x27"
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
$ sudo systemctl restart astroplant.service
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
$ 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 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.

Reference

See the following GitHub pages for our software: