# Bricks API

## IOT endpoint

<mark style="color:blue;">`GET`</mark> `https://brewbricks.comapi/iot/v1?apikey=apikey&type=:type&brand=:brand&version=:version&chipid=:chipid[sakey=:savalue]`

This method is the main endpoint for connecting various IOT devices to BierBot Bricks.

#### Query Parameters

| Name    | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| apikey  | string | The \`apikey\` of your brewery.                                                                                                                                                                                                                                                                                                                                                                              |
| type    | string | A hardware descriptor, e.g. `sonoff_th16`, `wemos_d1`, `rapsberry_3b` (logic: `manufacturer_board`).                                                                                                                                                                                                                                                                                                         |
| brand   | string | Who produced your device. For own / opensource projects please use `oss`.                                                                                                                                                                                                                                                                                                                                    |
| version | string | Firmware version of your hardware. E.g. `0.4.2`.                                                                                                                                                                                                                                                                                                                                                             |
| chipid  | string | The chipid / similar of your device. This has to be **unique** among all devices of one brewery.                                                                                                                                                                                                                                                                                                             |
| sakey   | string | <p>For how `sakey` has to be shaped, please see below. `savalue` can be anything of the following:<br>- <code>0/1</code>: indicating the current state of an relay.<br>- <code>0-1023</code> indicating the current state of an PWM signal.<br>- <code>0-105</code> indicating a temperature reading in degree celsius.<br>- <code>0-20</code> indicating the specific graviy (SG) in degree plato (°P).</p> |

{% tabs %}
{% tab title="200 Important OBEY the next\_request\_ms defining when the IOT should call the backend the next time. Repeated violation will cause your device to be blocked and in extreme cases your account to be locked. The first request will not hold and target values for actors (see the epower\_0\_state: 0). After your Brick has been activated, the backend returns the new target state for each actor of your request." %}

```
{
    "error": 0,
    "error_text": "",
    "warning": 0,
    "warning_text": "",
    "next_request_ms": 15000,
    "epower_0_state": 0
}
```

{% endtab %}
{% endtabs %}

The sensor / actory key ( `sakey` ) has follow the following schema (`$x_$y_$z_$i`):

* `$x` all fields are prefixed with `a` (actor) or `s` (sensor)
* `$y` datatype of the sensor / actor. currently supported are `bool` and `number`
* `$z` the physical meaning, e.g. `temp`, `wort` for sensors. or `epower`, `pressure` for actors.
* `$i` index on the device, starts with 0. This allows enumeration if multiple interfaces are of the same type. The index needs to be incremented for all groups of `$x` and `$z` (the datatype is not relevant).

Return value is a JSON map

```
{
    "error": 0,
    "error_text": "",
    "warning": 0,
    "warning_text": "",
    "next_request_ms": 15000
}
```

Attention: Pay respect to the `next_request_ms` field. Especially if you contact the backend repetitively too early your Brick might get banned permanently.

Examples:

* Device 1:
  * `s_number_temp_0`: first sensor sending a temperature number.
  * `s_number_temp_1`: second sensor sending a temperature number.
  * `s_number_temp_id_0`: ID of the first temperature sensor, i.e. `0x00003ffc3664`.
  * `a_number_epower_0`: This a PWM actor.
  * `a_bool_epower_1`:  note, how index is incremented, despite the change of `$z`.

### Sample request and implementations

Example request by the BierBot Brick would look like

```
https://brewbricks.com/api/iot/v1?type=sonoff_th16&brand=bierbot&version=0.9.4&s_number_temp_0=42&a_bool_epower_0=0&chipid=142424242_5C:CF:FF:20:CC:A5&apikey=YOUR_API_KEY
```

Sample implementations are available in

* [C/C++](https://github.com/BernhardSchlegel/BierBot-Bricks/blob/main/ESP8266/src/main.cpp#L479) for a Brick, [C/C++](https://github.com/universam1/iSpindel/blob/master/pio/src/iSpindel.cpp#L792) for a Hydrometer
* [Python](https://github.com/BernhardSchlegel/BierBot-Bricks-RaspberryPi/blob/main/main.py#L75)