Basic Notions

Introduction

qToggle is a way of interconnecting sensors, actuators and other data sources. qToggle works by leveraging the power of a flexible API, which lays the groundwork of a simple, common communication scheme.

qToggle attempts to impose a standard that allows managing, provisioning and talking to devices. Rather than reinventing the wheel, qToggle makes use of existing, widely used, technologies, such as RESTful APIs on top of HTTP, passing over data encoded as JSON.

Terminology

!!! diagram !!!

Devices

Devices are usually sensors or actuators with an upstream network connection. In a qToggle setup, devices implement (parts of the) qToggle API. Most qToggle devices are based on ESP8266/ESP8285 chips or on Raspberry Pi boards, but this by no means a constraint.

Consumers

While devices act as API servers, being capable of responding to requests, consumers are API clients, issuing API requests and thus consuming the API. In the context of qToggle, any HTTP client that emits an API request to a device is considered a consumer.

Consumers can be represented by complex user interfaces that allow managing a qToggle server or can be simple scripts that do small automation jobs.

Hubs

In real-world setups, it's difficult to individually manage many devices. A hub allows centralized administration of many qToggle devices.

Hubs act as consumers when talking to other devices, but they also expose an API interface that allows other consumers to see them as devices. This allows creating complex hierarchies of devices and hubs that are in a master-slave relationship.

For more details, see the Master-Slave Operation API specifications.

Ports

To actually be useful, a device must expose ports. A port is a way of transmitting a meaningful value out of or into the device. Ports usually represent GPIOs or ADC peripherals that are physically attached to the device.

Virtual ports are a special kind of ports, in that they don't represent a peripheral, but they are rather used for value storage, similarly to registers.

For more details, see the Ports section of the API specifications.

Attributes

Devices and ports need to be configured before being used. Attributes allow reading and/or supplying configuration for ports and devices. Each device and each port exposes their own attributes.

There is a set of standard attributes whose meaning is well defined by the API specifications. Among these standard attributes, there is a subset of common attributes that must be exposed by each device. The same applies to ports.

Non-standard, additional attributes are often exposed by ports and devices. Their meanings are described by definitions that are supplied by the device.

For more details, see the Attributes section of the API specifications.

The Power Of qToggle

• usage via API (complex, but many things optional)

• what can qToggle do:

  • self-describing
  • implement logic between ports using expressions
  • hierarchical (tree) topology using master-slave
  • real-time notifications
  • firmware updates
  • links to API docs

API Usage Examples

• authentication
• example
  • list ports
  • change port value

Playground Setup

- docker

API Request In Browser

- browser

API Request With cURL

- curl