-
Notifications
You must be signed in to change notification settings - Fork 1
Installation
Topics
- a Raspberry Pi board (all models are supported, but generations 3 and 4 are recommended)
- a micro SD card (the minimum required capacity is 2GB)
- a power supply unit capable of delivering enough current for your Pi and connected peripherals
- a laptop or desktop machine equipped with an SD card reader (running the OS of your preference)
- a properly configured local network
- a case for your Pi
- WiFi and/or Bluetooth USB adapters, if your Pi board does not come with WiFi/Bluetooth on-board adapter
- an Ethernet cable, if you plan to connect the Pi to your wired network
- an HDMI monitor and a keyboard, in case you must do some troubleshooting in the absence of a network connection
- various peripherals, such as sensors and GPIO expansion boards, that you may wish to use
All versions and variants of the OS images are available for download on the Releases page.
Choose the Latest release, unless you know what you're doing. At the end of the release notes, you'll find download links corresponding to all Raspberry Pi generations, of the following format:
qtoggleos-raspberrypi<generation>-<version>.img.xz
The missing generation refers to the first generation. It is important to choose the correct image for your board, otherwise it won't boot. The following table indicates model - generation correspondence:
| Model | Generation |
|---|---|
| Raspberry Pi Model A | Generation 1 |
| Raspberry Pi Model B | Generation 1 |
| Raspberry Pi Model A+ | Generation 1 |
| Raspberry Pi Model B+ | Generation 1 |
| Raspberry Pi Compute Module | Generation 1 |
| Raspberry Pi Zero | Generation 1 |
| Raspberry Pi Zero W | Generation 1 |
| Raspberry Pi 2 B | Generation 2 |
| Raspberry Pi 3 B | Generation 3 |
| Raspberry Pi 3 B+ | Generation 3 |
| Raspberry Pi 3 A | Generation 3 |
| Raspberry Pi Compute Module 3 | Generation 3 |
| Raspberry Pi 4 | Generation 4 |
If you're running Windows on your laptop, follow these instructions to write the image, but make sure to extract the compressed image file first.
If you use Linux or macOS, there's a writeimage.sh script that will do everything for you, including the optional setup of a wireless network connection and setting a static IP address.
First, download the script on your laptop:
$ curl https://raw.githubusercontent.com/qtoggle/qtoggleos/master/writeimage.sh -o writeimage.sh
Then run the script as follows (replacing the arguments with appropriate values):
$ sudo ./writeimage.sh -d /dev/mmcblk0 -i /path/to/qtoggleos-raspberrypi<gen>-<version>.img.xz
note 1: specify the device path to the disk and not to some partition (e.g. /dev/mmcblk0 instead of /dev/mmcblk0p1)
note 2: the writeimage.sh script will decompress the downloaded OS image for you
You can preconfigure a wireless network connection, when using the writeimage.sh script:
$ sudo ./writeimage.sh -d /dev/mmcblk0 -i /path/to/qtoggleos-raspberrypi<gen>-<version>.img.xz -n 'yournet:yourkey'
If you prefer a static IP instead of DHCP, just run the script as follows (replacing the values with your own):
$ sudo ./writeimage.sh -d /dev/mmcblk0 -i /path/to/qtoggleos-raspberrypi<gen>-<version>.img.xz -s '192.168.1.101/24:192.168.1.1:8.8.8.8'
In fact, any other image writing method should work, including using the Unix dd command. You can even use Etcher which is available for Linux and macOS, if you prefer a friendly user interface.
When booting qToggleOS for the first time, it will perform a few setup tasks before being ready for use, which may take up to 2 minutes (further boots will take no more than 20 - 30 seconds). These tasks include:
- creating and formatting the data partition on the entire remaining SD card space
- generating SSH host keys
- preparing the configuration for various services
To access the qToggleServer web app, you'll have to point your browser to the IP address of your Raspberry Pi board. You can find your board's IP address by:
- scanning your local network using smart phone apps such as Fing
- looking through your router's DHCP leases for a hostname of the form
qtos-XXXXXXXX - using a static IP address at SD Card Preparation step
- connecting an HDMI display to your board and looking for the IP address in the displayed boot log
Use admin and empty password when prompted for login. You can use any recent version of mobile or desktop based browsers to access the web app.
After making sure that you can access and log into the web app, you should proceed with configuring your qToggleOS system.