Generic firmware for a Raspberry Pi based SimpleAQ device.
If you want a more detailed overview of the design, see our design document here.
First, you will have to select the image you want. You can find an image by selecting Actions in this repository, then selecting a successful Build Image run. Then, at the bottom of the page you will see Artifacts. Click the artifact to download it.
You can unzip your image with
unzip your_downloaded_image_file.zip
Once you have the contained .img
file, you can write it to your MicroSD card.
First, you will need to find the device corresponding to your MicroSD card.
sudo fdisk -l | grep MicroSD -B 1 -A 5
Now you will have a list of all MicroSD cards attached to your system, whether mounted or not.
The device name will look like /dev/sdx
, where x is some letter.
It is critical that you select the correct device name, or you will cause unwanted data loss on your host system.
Next, we must ensure that the device is not mounted.
df -h | grep /dev/sdx
where /dev/sdx/
is the device name for your MicroSD card will show whether your device is mounted.
For each mounted partition listed, unmount it with
sudo umount /dev/sdxy
where x
is your device's letter that you found with fdisk
and y
may be a number.
It may be the case that your drive wasn't mounted at all. In any event, if your device is mounted, the following step will not work.
Now we will write your image with
sudo dd bs=4M of=/dev/sdx if=your_image_file.img
where x
is your device's letter that you found with fdisk
above.
This step may take a while.
You should now be able to mount the ext4
Linux partition of your written image to inspect the written files.
You can install needed dependencies in virtualenv
with:
virtualenv venv -p python3
source venv/bin/activate
pip install -r requirements.txt
When you return to your work later, you can simply use:
source venv/bin/activate
You can run this locally to test it out.
cp example.env .env
source .env
flask run
You can configure Wifi on your device without using ssh
.
First, insert the imaged MicroSD card into a standard card reader, then edit /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
in the root filesystem "rootfs".
At the end of the file, add:
network={
ssid="Your Wireless Network ID Here!"
psk="Your Wireless Network Password Here!"
}
Note that if you are concerned about the security of storing your key in plain-text, you can run:
wpa_passphrase YourWirelessNetworkID YourWirelessNetworkPassword
and get a hash that you can use in the PSK field instead.
Our build process automatically creates Raspbian images appropriate for both a production environment and for development.
In order to SSH into your SimpleAQ device, you will need to select a development image labeled INSECURE-DEBUG.
These devices use the default username pi
and the default password simpleaq
and would be compromised immediately if placed on the public internet.
Note that since our transition to systemd-networkd
based networking, link-local connections through your device's data/peripherals USB port are no longer supported.
You have two options to connect to your device.
simpleaq
device's IP address on your network, then connect with e.g., ssh pi@192.168.1.xxx
.hostap
network by connecting to wireless at SimpleAQ-xxxx
. Then, connect with ssh pi@192.168.4.1
.Our devices automatically switch between hostap
and wlan
modes based on whether wlan
is working.
Therefore, if you have a correctly configured and working wlan
connection, ssh
into your hostap
connection will not work.
A service will periodically retry the wlan
connection, but in doing so it will briefly take down the hostap
.
First, you'll need an instance of InfluxDB to write into! If you already have one, you can skip this step.
If you need a temporary instance for testing purposes, you can create one using:
docker run -p 8086:8086 \
-e DOCKER_INFLUXDB_INIT_USERNAME=influx_dev_user \
-e DOCKER_INFLUXDB_INIT_PASSWORD=influx_not_secure \
-e DOCKER_INFLUXDB_INIT_ORG=my_org \
-e DOCKER_INFLUXDB_INIT_BUCKET=my_bucket \
-e DOCKER_INFLUXDB_INIT_MODE=setup \
-e DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=not_secure_admin_token \
--network host \
influxdb:latest
The InfluxDB instance will now be running on port 8086 on the host machine.
You will also need to find the IP address of the host machine so that the device can write into it.
One way to find the local IP address is using ifconfig
.
It may be helpful to confirm that you can connect to http://HOST.IP.ADDRESS.HERE:8086 from a web browser on a machine on the same network as your device.
If InfluxDB is set up properly and accessible, you will see a login page for InfluxDB.
When you boot your SimpleAQ image, it should start a HostAP network with a name like SimpleAQ-xxxx, and a default password of SimpleAQ. If you connect to the HostAP network with any device, navigate to http://192.168.4.1 or http://simpleaq.setup in a web browser. On this page, you will be able to change relevant settings. When the device is reporting data to a backend server expected, this HostAP network will not appear.
In order to connect the device to the backend, you will need a valid org, bucket and token. If you used the example above, you can use "my_org", "my_bucket" and "not_secure_admin_token".
You do not need ssh
to configure your device.
First, put your imaged MicroSD card into a card reader.
Edit /etc/environment
in the root filesystem "rootfs".
If you're following the example above, the relevant fields would then be:
influx_org=my_org
influx_bucket=my_bucket
influx_token=not_secure_admin_token
influx_server=http://HOST.IP.ADDRESS.HERE:8086
If everything is configured correctly and the device has network connectivity, your device should be auto-configured on boot and automatically start sending readings to InfluxDB.
bootlogd
is installed in our images.
Therefore, if booting fails for any reason, you can insert the MicroSD card into a standard reader, then check the root file system "rootfs" for boot errors using
sed 's/\^\[/\o33/g;s/\[1G\[/\[27G\[/' var/log/boot
If there is an issue with the service, you can ssh
into the device using the instructions above, then run
sudo service simpleaq status
to explore the issue.