-
Notifications
You must be signed in to change notification settings - Fork 2
Installation
- a Raspberry Pi board (all models are supported, but generations 3 and 4 are recommended) or one of the alternative supported boards (e.g. NanoPi R1)
- 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
- Wi-Fi and/or Bluetooth USB adapters, if your Pi board does not come with Wi-Fi/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 USB adapters, 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 Zero 2 W | 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
If the system doesn't sense a network connection at boot (if you haven't plugged in a wired network cable), it will automatically start its internal Wi-Fi AP with a SSID of the format qtos-XXXXXXXX and a password set to 12345678.
Once connected with your mobile phone or laptop, it will behave like a captive portal, asking for login. Use admin and empty password when prompted for login. It will redirect you to the settings page where you can configure your system, including a local Wi-Fi connection.
The unit will automatically reboot if no connection to the internal AP is being made within 2 minutes.
To access the qToggleServer web app, you'll have to point your browser to the IP address of your Raspberry Pi board (on default HTTP port 80). 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.
Most booting issues can be identified by attaching a display to the Raspberry Pi board and reading the boot log. When the display is not an option, you can insert the SD card into your laptop and inspect the /log/boot.log file on your data partition (you'll need Linux to read that, though).
Make sure:
- you have downloaded the correct OS image for your board (double check your board model and the table above)
- you have decompressed the image file, if you're not using
writeimage.sh(the file should have.imgextension) - the SD card you're using actually works and is compatible with your Raspberry Pi (see if Raspbian boots from it)
The system will reboot whenever something goes wrong (i.e. disconnected from network, software hangs or kernel crashes). This is accomplished using the hardware watchdog as well as software watch scripts.
The majority of reboot loops are caused by improperly configured network connections. Double check your:
- Wi-Fi network name and password, if you're using Wi-Fi
- wired network connection, if you're connected to your wired network
- DHCP service (usually on your router)
- static IP configuration, if you're using one
If you're using smartphone apps like Fing to identify devices on your network, make sure the phone is actually connected to your Wi-Fi network.
Connecting a display to your Pi will show the boot log, which prints the IP address(es) of your board.
When using DHCP, your DHCP service (usually your router) will show leases (IP addresses) allocated to various devices on your network. Look for a device named something like qtos-XXXXXXXX.
If your board has internal eMMC, see the eMMC Internal Memory article to run the OS from eMMC.