-
Notifications
You must be signed in to change notification settings - Fork 2
FAQ
-
General
- What is qToggle?
- Where does the name come from?
- What can I do with qToggle?
- What hardware do I need to use qToggle?
- How is qToggle different from other similar solutions?
- Does qToggle require Internet access?
- Can I access my qToggle devices from the Internet?
- Is my data safe? Is it transmitted to a cloud server?
- Is there a qToggle smartphone app?
- There seem to be many qToggle subprojects/components; what is their role? Do I need to install all of them?
- I want to try out qToggle; what's the easiest way to do that?
- Support & Documentation
- Devices & Firmware
- The Hub
- The App
- Licensing
- Development
qToggle proposes a standard way of interconnecting devices. It is built around a flexible, yet powerful API, allowing various types of devices to work together.
Nothing in particular.
Here's a non-exhaustive list of possible use cases:
- home automation
- small industrial automation
- building management system
- remote control of actuators
- remote reading of sensors
- Internet of Things
- smart control of hobby projects
It is recommended that you use a Raspberry Pi board, but you can run the software on virtually any decent computer you may have at your disposal.
Then you'll probably need some devices to control. Here's a list of supported devices. Keep in mind that you can also use a Raspberry Pi board equipped with peripherals.
A regular Ethernet and/or Wi-Fi local network is usually enough for a working qToggle setup.
While other similar solutions try to accommodate a very large range of devices, along with various many technologies, qToggle works with a selected list of devices, imposing a unitary API, firmware and so on. There is, of course, an obvious disadvantage to this approach: many of your favorite devices probably aren't supported. However, here are the reasons why we decided to go this way:
- We provide the opensource firmware; this means that no hacks and no 3rd party hubs or clouds are required.
- All devices speak the same language (API) and are controlled the same way.
- The supported devices are tested thoroughly, with a well documented installation procedure.
This doesn't mean that other devices can't be added to qToggle: there are add-ons that provide bridges and adaptation layers to different peripherals, networks and technologies.
No. There's no requirement for Internet access, but it is highly recommended, as firmware updates and system time synchronization are normally done via Internet.
The answer is technically, yes. However you'll need to ensure that:
- you have a public (routable) IP address,
- you have configured your router to forward required port(s) to your qToggle hub,
- you have set up a dynamic DNS service (see Dynamic DNS if running qToggleOS), and
- you have set up HTTPS (see Dynamic DNS if running qToggleOS)
Your qToggle data is definitely safe, as it never leaves your local network. And no, there's no cloud involved.
However, you must ensure your network meets the required security standards, by keeping your router/access point's firmware up to date and by ensuring your devices have complex-enough passwords.
Yes and no. Yes, there's a progressive web app that works on virtually all existing smartphones and tables, but you won't find it on Google Play or App Store, since it's practically a web application. It feels like a real app, so you don't have to worry about that.
There seem to be many qToggle subprojects/components; what is their role? Do I need to install all of them?
Things may look complicated but in fact they aren't. The qToggle ecosystem is composed of:
- qToggleServer - the main component that acts as a hub and that also provides the friendly web app
- qToggleOS - an OS ready to be used with Raspberry Pi boards and which basically runs qToggleServer
- espQToggle - the firmware that powers the ESP-based devices
- add-ons - optional pieces of software that enhance the functionality of qToggleServer
- other tools and packages that are specific to certain setups and use cases
You'll have to choose between qToggleServer and qToggleOS, depending on whether you want to run it on a Raspberry Pi or not. Then, if you're dealing with ESP devices, you'll have to flash them with corresponding firmware, as their installation pages indicate. The rest is optional.
If you own a spare Raspberry Pi, just download qToggleOS and install it on an SD card.
Otherwise, you could run qToggleServer in Docker, on your laptop.
Well, since you're reading this, you've probably already found the qToggle Docs wiki. This repository provides common documentation that is not specific to any device or component.
For each qToggle component there's a wiki that offers specific documentation. Feel free to browse them:
You can start or join a discussion on our Facebook Group.
Or, if you'd rather not use Facebook, there's a Google Group for qToggle users.
Yes, sure: join us on Gitter.
Also make sure to join our Facebook Group.
Sure: https://www.facebook.com/qtoggle.
If you think you found a bug, please try to determine to which project it belongs and open an issue:
If you're unsure where the issue should be posted, just use qToggleServer's issue tracker and we'll do the triage ourselves.
However, before opening the issue, please do a quick search for similar issues, just to make sure the issue hasn't already been reported by someone else.
When you fill out the issue form, please use the template; it offers context that helps us better understand and possibly reproduce your bug.
First, please try to determine to which project it belongs and open an issue:
If you're unsure where the issue should be posted, just use qToggleServer's issue tracker and we'll do the triage ourselves.
However, before opening the issue, please do a quick search for similar issues, just to make sure the issue hasn't already been proposed by someone else.
When you fill out the issue form, please use the template; it offers context that helps us better understand your proposal.
If you're looking for devices from the Raspberry Pi family, all of them are supported. See this page for a list of models and generations.
As for the ESP8266/ESP8285-based devices, here is a comprehensive list of supported devices.
In qToggle terminology, a port is anything that can be set a value or get a value from. It can be a hardware port, such as a GPIO or an ADC, or it can be something as abstract as the armed state of an alarm. Ports are the elementary pieces of the qToggle automation.
From a programming point of view, you can think of ports as variables of boolean or numeric types: you read values from and write values to them. Some of them are read-only. Some of them have a side effect when receiving certain values.
Normally, the qToggle firmware cannot harm your device (at least not physically). However you may lose some of the original device's functions that may not be supported by the qToggle-provided firmware. If you're concerned about that, you should backup the original firmware and keep it in case you'll change your mind and need to restore it.
The warranty will most likely be lost if you attempt to return it a different firmware than the original one.
Open the web app and access the Devices section. In the add device form, you have the following options:
- use the discover button to discover devices that are around your hub
- enter the URL of your device (simply use its IP address after
http://), if the device is already on your network
If you can't find the Devices section, make sure the slaves.enabled option is true in your configuration file.
You'll need to put your device into setup mode. Devices are normally equipped with a setup button. It's either a dedicated (often hidden) button or is one of the buttons that are used during normal device functioning. Just press and hold this button for at least 5 seconds, until the Wi-Fi LED (if present) will start blinking fast. Your device is now in setup mode.
A device in setup mode will require no password to be operated. At this point, you have the following options:
- adopt it in your hub (see How do I add a new device to my system?)
- configure the device via its web interface, accessed using its temporary access point, with e.g. a mobile phone
A hub, in qToggle terminology, is a special master device that controls other slave devices. Any device that runs qToggleServer can play the role of a hub. In complex setups, a hub can itself be a slave device for another higher hub.
Hubs usually provide a user interface in the form of a web app which allows management of the hub itself and its controlled slave devices.
Setting up a hub is as simple as starting as installing & running qToggleServer in one of the available methods. See Getting Started for details.
Use admin with empty password. Please make sure though to set a strong password for your device(s) as soon as you log in.
Yes, you can backup and restore the configuration of any of your devices using the Backup and Restore buttons on the device's setting page, in the web app. For more technical details regarding the backup/restore procedure and format, see Backup & Restore.
Yes, you can use a qToggle device without a hub. If, however, you're thinking of using an ESP-based device without a hub, keep in mind that you won't get a user interface to configure and control it.
The app is a progressive web app that works on virtually all existing smartphones and tables, but you won't find it on Google Play or App Store, since it's practically a web application. It feels like a real app, so you don't have to worry about that.
It comes by default with (any flavor) of qToggleServer and will prompt to be installed on your smartphone as soon as you visit the web frontend of the server using your browser. Once installed (also known as being added to home screen in the context of a PWA), you can find it along with the rest of the apps and access it as a regular app.
Being bundled with qToggleServer, you'll receive updates for the web app whenever you update your qToggleServer installation. Just make sure to use pull-to-refresh inside the app and you should be running the latest version.
Yes, the app is a responsive web application that adapts to the layout of the device that it runs on. Therefore it works and looks well on practically any kind of device with any screen size.
There are multiple licenses that need to be taken into account, as the qToggle ecosystem is made of multiple components and each component relies on many other libraries and programs authored by the opensource community, each one distributed under a specific license.
Nevertheless, the source code that has been written by the qToggle team for the community is released under the Apache License 2.0.
Most certainly. This is one of the reasons why we released the software to the community. However, keep in mind that you are doing so at your own risk and the qToggle team assumes no responsibility for any damage that occurs as a result of using qToggle.
Yes, you can, but under the terms of the Apache license.
Of course you can. And you are not required to publish them. If however you think other users could benefit from your work, contributing back to the community would be appreciated.
See also http://www.apache.org/foundation/license-faq.html#Must-Contribute and http://www.apache.org/foundation/license-faq.html#Distribute-changes for more details.
qToggleServer has a backend and a frontend. The backend is written in Python and makes intensive use of the asyncio facility that comes with Python. The frontend is written in Javascript using an ECMAScript 2018 compatible syntax. The app comes as a progressive web app.
espQToggle is written in plain C and is based on Espressif's ESP8266 non-OS SDK.
qToggleOS is a Linux lightweight OS based on thingOS, which in turn is based on BuildRoot.
qToggle API follows the RESTful recommendations. It uses JSON as message format and various standard HTTP headers to transmit requests and responses.
While MQTT seems to be the de facto standard these days for the IoT & friends, here are the reasons why we thought HTTP would be a better choice for qToggle:
- HTTP is more accessible than MQTT. You can easily check out if a device works or what it has to say, using a web browser or a command line tool such as
curl. HTTP is by nature a text protocol with usually a textual payload, which makes it more human readable and debuggable. - HTTP passes through proxies and virtually any kind of local network there is today. It's also probably the most used protocol ever. You can't say that about MQTT.
- While both HTTP and MQTT are transport protocols, HTTP comes with some goodies that can be used out-of-the-box, such as URLs, methods, status codes and headers. Aside from topics, you don't get much of that from MQTT.
- MQTT's topology requires a central server which becomes a single point of failure and represents yet another service that needs to be installed and maintained. In the topology proposed by qToggle, hubs can go offline without affecting more than the branch of the hierarchy tree that they control.
- Admitting it's pretty cool for every device to be able to directly talk to any other device in the network, this isn't really a requirement for qToggle nor for automation systems, in general.
- MQTT usually offers a high scalability factor when it comes to the number of devices connected to the MQTT network. At the same time, the qToggle hierarchical model offers the possibility of connecting thousands of devices in a single setup, before probably saturating the network.
- MQTT is often deemed lightweight, when compared to HTTP. This is definitely true, but remember that on top of MQTT you'll have to use a protocol that offers what HTTP already offers (e.g. methods, headers and statuses). If you really need lightweight communication, there's CoAP and on top of it you can transmit CBOR messages. And these two are closer to the HTTP world than to MQTT.
Overall, we're not saying MQTT is bad, it's just that it gives a false impression of solving all problems that people encounter in the IoT world. It does provide solutions for some of them, but it's definitely not what people expect from it.