-
Notifications
You must be signed in to change notification settings - Fork 2
Peripherals
espQToggle is a firmware that runs on many ESP8266/ESP8285-based devices. Each device type has its particular functions and specific pin (GPIO) allocations connected to its physically attached peripherals, such as relays, LEDs, buttons or even external, additional integrated circuits.
To be able to run on all these device types, espQToggle uses the notion of peripheral to deal with configurations that are dedicated to each device type. A list of one or more peripherals is configured on the device before it can be comissioned and function properly. While these peripherals are fetched automatically by the device as soon as its config_name attribute is set to a well-known device type configuration, this page tries to cover internal aspects of these peripherals as well as creating new device configurations.
A peripheral configured on a device will determine the exposal of one or more qToggle ports, allowing reading values from the peripheral or writing values to it.
In addition to peripherals, see System Configuration for details on how to configure system-level device parameters.
Each peripheral has the following properties:
-
type: a number indicating the peripheral type (see Available Peripheral Types) -
flags: a 32-bit integer used as bit flags, whose meaning are specific to each peripheral type -
params: 56 bytes worth of data that is to be interpreted as indicated by each peripheral type (see below) -
port_ids: a list of identifiers to be given to qToggle ports exposed by peripheral
While the way parameters are interpreted is left to the implementation of each peripheral, the following recommendations will allow dealing with parameters of various data types in a common way:
- the first 8 bytes should be used as 8 x 8-bit integers
- the next 8 bytes should be used as 4 x 16-bit integers
- the next 16 bytes should be used as 4 x 32-bit integers
- the next 24 bytes should be used as 3 x 64-bit integers or doubles
The maximum number of configured peripherals is 16. The maximum number of ports exposed by a peripheral is 16.
The /peripherals endpoint is exposed by devices running espQToggle; keep in mind though that it is not a standard qToggle API endpoint.
This API function requires admin access level.
Returns the configured peripherals with all their details.
Response has the following body:
[
{
"type": number,
"flags": number|string,
"int8_params": number[]|string[],
"int16_params": number[]|string[],
"int32_params": number[]|string[],
"int64_params": number[]|string[],
"double_params": number[],
"port_ids": string[]
},
...
]
Each dictionary in the returned list represents a configured peripheral.
-
typeis the identifier of the peripheral type (see Available Peripheral Types) -
flagsis a 32-bit integer given either as a base 10 number or a string representing a base 2 number (made of0and1) -
int8_paramsis a list of 8-bit integers or strings representing base 16 numbers; up to 8 non-overlapping values and up to 56 values overlapping with other data types are supported -
int16_paramsis a list of 16-bit integers or strings representing base 16 numbers; up to 4 non-overlapping values and up to 24 values overlapping with other data types are supported -
int32_paramsis a list of 32-bit integers or strings representing base 16 numbers; up to 4 non-overlapping values and up to 10 values overlapping with other data types are supported -
int64_paramsis a list of 64-bit integers or strings representing base 16 numbers; up to 3 values are supported (will overlap with double params) -
double_paramsis a list of doubles; up to 3 values are supported (will overlap with int64 params) -
port_idsis a list of port ids whose length is normally the same as the number of ports exposed by the peripheral
Example:
Consumer's request:
GET /peripherals HTTP/1.1
Host: device.example.com
Connection: close
Cache-Control: no-cache
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3IiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTAyMn0.l2uO5g3viMWLQu2s7KJ0zZI5Cn-Cpk5i7am9vv2JcJ0
Device's response:
HTTP/1.1 200 OK
Connection: close
Cache-Control: no-cache
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c3IiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTAyM30.If1_Cu-WRZ3qzICahiA5flU7o4lR1RGMhF9HYeBHpKM
Content-Type: application/json; charset=utf-8
Content-Length: n
[
{
"type": 1,
"flags": "0000000000000010",
"int8_params": [0],
"port_ids": ["push_button1"]
},
{
"type": 1,
"flags": "0000000000000001",
"int8_params": ["0C"],
"port_ids": ["relay1"]
},
{
"type": 5,
"int8_params": [14, 1],
"port_ids": ["temperature", "humidity"]
}
]
Updates the peripheral configuration of a device.
This API function requires admin access level.
Request has the same body format and meaning as GET /peripherals. Only the type field of each peripheral is actually required.
Response has no body.
Each peripheral type is uniquely represented by an identifier, which is a 16-bit number starting at 1. Following is an actively maintained list of available peripherals along with their flags, parameters and exposed ports.
Controls the available inputs and outputs (GPIO).
| Position | Description |
|---|---|
| 0 | make pin an output |
| 1 | enable pull-up |
| 2 | enable pull-down |
| 3 | default value |
| 4 | ignore default value |
| Offset | Type | Description | Range/Unit | Remarks |
|---|---|---|---|---|
| 0 | unsigned 8-bit | pin number | 0..16 |
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | boolean | depends on flag 0 | GPIO pin value |
Reads the value of the ADC.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | ADC value | 0..1000 mV |
Outputs PWM signal on a GPIO pin.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|---|---|---|---|
| 0 | unsigned 8-bit | pin number | 0..15 |
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | yes | PWM frequency | 1..50000 Hz | only added by first peripheral of this type |
| 1 | number | yes | PWM duty cycle | 0..100 % |
DS18X20 Dallas (1-wire) temperature sensor.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|---|---|---|---|
| 0 | unsigned 8-bit | pin number | 0..15 |
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | temperature | -55..125 °C |
DHT11/DHT22 temperature and humidity sensor.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|---|---|---|---|
| 0 | unsigned 8-bit | pin number | 0..15 | |
| 1 | unsigned 8-bit | model (0: DHT11, 1: DHT22) | 0..1 |
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | temperature | -40..80 °C | |
| 0 | number | no | humidity | 0..100 % |
BL0937 powermeter chip.
| Position | Description |
|---|---|
| 0 | SEL pin value for current mode |
| Offset | Type | Description | Range/Unit | Remarks |
|---|---|---|---|---|
| 0 | signed 8-bit | CF pin number | -1..15 | -1: disabled |
| 1 | signed 8-bit | CF1 pin number | -1..15 | -1: disabled |
| 2 | signed 8-bit | SEL pin number | -1..15 | -1: disabled |
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | active power | needs calibration factor | |
| 1 | number | no | energy | needs calibration factor | |
| 2 | number | no | current | needs calibration factor | |
| 3 | number | no | voltage | needs calibration factor |
BL0940 powermeter chip.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | active power | W | |
| 1 | number | no | energy | Wh | |
| 2 | number | no | current | A | |
| 3 | number | no | voltage | V | |
| 4 | number | no | temperature | °C |
Peripheral specific to Shelly H&T device.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | temperature | -40..60 °C | |
| 0 | number | no | humidity | 0..100 % |
V9821 powermeter chip.
| Position | Description |
|---|
| Offset | Type | Description | Range/Unit | Remarks |
|---|
| Index | Type | Writable | Description | Range/Unit | Remarks |
|---|---|---|---|---|---|
| 0 | number | no | active power | W | |
| 1 | number | no | reactive power | VAR | |
| 2 | number | no | apparent power | VA | |
| 3 | number | no | power_factor | 0..100 % | |
| 4 | number | no | energy | Wh | |
| 5 | number | no | current | A | |
| 6 | number | no | voltage | V | |
| 7 | number | no | frequency | Hz |
Tuya MCU serial protocol, as described here.
| Position | Description |
|---|---|
| 0 | force coordinated setup |
| 1 | restore default port values when entering setup mode |
| 2 | restore default port values when exiting setup mode |
| 3 | don't restore default port values when setup mode source is internal |
| 4 | use alternate UART pins (GPIO13, GPIO15) |
First 8 bytes are organized as follows:
| Byte | Description |
|---|---|
| 0 | polling interval (seconds); 0 disables polling |
Following 48 bytes are organized as a list of DP (data point) details; for each DP, a port will be allocated, according to given details. Details are structured as follows:
| Byte | Description |
|---|---|
| 0 | DP ID |
| 1 | reserved |
| 2-3 | 16-bit DP flags (see below) |
| 4-... | depends on flags |
The list of details ends at first DP ID set to 0.
The following DP flags are defined:
| Bit | Description |
|---|---|
| 0-3 | port type (see below) |
| 4 | writable |
| 5 | has default value (extra 4 bytes indicate signed 32-bit value, for numeric ports) |
| 6 | default boolean value |
| 7 | reserved |
| 8 | map enum to boolean (extra 2 bytes indicate false and true values) |
The following DP types are defined:
| Type | Description |
|---|---|
| 0 | raw |
| 1 | boolean |
| 2 | number |
| 3 | string |
| 4 | enumeration |