Peripherals - qtoggle/espqtoggle GitHub Wiki

About

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.

Peripheral Internals

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.

API Endpoint

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.

GET /peripherals

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.

  • type is the identifier of the peripheral type (see Available Peripheral Types)
  • flags is a 32-bit integer given either as a base 10 number or a string representing a base 2 number (made of 0 and 1)
  • int8_params is 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_params is 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_params is 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_params is a list of 64-bit integers or strings representing base 16 numbers; up to 3 values are supported (will overlap with double params)
  • double_params is a list of doubles; up to 3 values are supported (will overlap with int64 params)
  • port_ids is 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"]
    }
]

PUT /peripherals

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.

Available Peripheral Types

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.

GPIO

Type: 1

Description

Controls the available inputs and outputs (GPIO).

Flags

Position Description
0 make pin an output
1 enable pull-up
2 enable pull-down
3 default value
4 ignore default value

Parameters

Offset Type Description Range/Unit Remarks
0 unsigned 8-bit pin number 0..16

Ports

Index Type Writable Description Range/Unit Remarks
0 boolean depends on flag 0 GPIO pin value

ADC

Type: 2

Description

Reads the value of the ADC.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks

Ports

Index Type Writable Description Range/Unit Remarks
0 number no ADC value 0..1000 mV

PWM

Type: 3

Description

Outputs PWM signal on a GPIO pin.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks
0 unsigned 8-bit pin number 0..15

Ports

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

Type: 4

Description

DS18X20 Dallas (1-wire) temperature sensor.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks
0 unsigned 8-bit pin number 0..15

Ports

Index Type Writable Description Range/Unit Remarks
0 number no temperature -55..125 °C

DHTXX

Type: 5

Description

DHT11/DHT22 temperature and humidity sensor.

Flags

Position Description

Parameters

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

Ports

Index Type Writable Description Range/Unit Remarks
0 number no temperature -40..80 °C
0 number no humidity 0..100 %

BL0937

Type: 6

Description

BL0937 powermeter chip.

Flags

Position Description
0 SEL pin value for current mode

Parameters

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

Ports

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

Type: 7

Description

BL0940 powermeter chip.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks

Ports

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

Shelly H&T

Type: 8

Description

Peripheral specific to Shelly H&T device.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks

Ports

Index Type Writable Description Range/Unit Remarks
0 number no temperature -40..60 °C
0 number no humidity 0..100 %

V9821

Type: 9

Description

V9821 powermeter chip.

Flags

Position Description

Parameters

Offset Type Description Range/Unit Remarks

Ports

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

Type: 10

Description

Tuya MCU serial protocol, as described here.

Flags

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)

Parameters

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