Skip to content

Commit

Permalink
Rework documentation for DS18B20 sensor
Browse files Browse the repository at this point in the history
  • Loading branch information
@dshil
dshil committed Nov 12, 2024
1 parent 7cbd733 commit 3474a10
Show file tree
Hide file tree
Showing 2 changed files with 201 additions and 195 deletions.
197 changes: 2 additions & 195 deletions docs/httpserver.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -153,202 +153,9 @@ http "bonsai-firmware.local/system/reboot"
Rebooting...
```

#### DS18B20 Sensor
**Sensors APIs**

[DS18B20](https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf) is a highly accurate 1-Wire digital thermometer provided by the Analog Devices company. Many DS18B20 sensors can be connected to the single GPIO.

DS18B20 sensor has the following APIs:

```bash
http "bonsai-firmware.local/sensor/ds18b20/scan?gpio=<GPIO_NUM>"
```

- `<GPIO_NUM>` - GPIO number to which sensor is connected.

```bash
http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=<GPIO_NUM>&sensor_id=<SENSOR_ID>"
```

- `<GPIO_NUM>` - GPIO number to which sensor is connected.
- `<SENSOR_ID>` - unique sensor identifier, used internally by firmware, see the description below.

```bash
http "bonsai-firmware.local/sensor/ds18b20/write_configuration?gpio=<GPIO_NUM>&sensor_id<SENSOR_ID>=&seria
l_number=<SERIAL_NUMBER>&resolution=<RESOLUTION>"
```

- `<GPIO_NUM>` - GPIO number to which sensor is connected
- `<SENSOR_ID>` - unique sensor identifier, defined internally by firmware
- `<SERIAL_NUMBER>` can be obtained with the `scan` API, mentioned previously
- `<RESOLUTION>` - how precise the temperature would be measured

`<RESOLUTION>` values:
- 9, single digit precision, 123.1,
- 10, two digit precision, 123.23
- 11, three digit precision, 123.335
- 12, four digit precision, 123.2034

The more accurate the measurement, the more time it takes, see the table below for more details:

Resolution | Max Measurement Time |
---------- | --------------------- |
12 | 750.0ms (tconv) |
11 | 375.0ms (tconv / 2) |
10 | 187.5ms (tconv / 4) |
9 | 93.75ms (tconv / 8) |

By default all sensors aren't configured. Let's connect all the sensors to the same GPIO (27) and see if the firmware can detect them:

```bash
http "bonsai-firmware.local/sensor/ds18b20/scan?gpio=27"
```

```json
{
"rom_codes": [
"1C:AB:87:00:00:00",
"85:BB:87:00:00:00"
],
"sensors": [
{
"configured": false,
"id": "soil_temp"
},
{
"configured": false,
"id": "outside_temp"
}
]
}
```

As we can see, none of the sensors are configured. Let's now configure them all so that we can read the the temperature values from them:

```bash
http "bonsai-firmware.local/sensor/ds18b20/write_configuration?gpio=27&sensor_id=outside_temp&serial_number=1C:AB:87:00:00:00&resolution=10"
```

```json
{
"resolution": "Bit_10",
"serial_number": "1C:AB:87:00:00:00"
}
```

```bash
http "bonsai-firmware.local/sensor/ds18b20/write_configuration?gpio=27&sensor_id=soil_temp&serial_number=85:BB:87:00:00:00&resolution=10"
```

```json
{
"resolution": "Bit_10",
"serial_number": "85:BB:87:00:00:00"
}
```

Now we can ensure that all sensors are configured:

```bash
http "bonsai-firmware.local/sensor/ds18b20/scan?gpio=27"
```

```json
{
"rom_codes": [
"1C:AB:87:00:00:00",
"85:BB:87:00:00:00"
],
"sensors": [
{
"configured": true,
"id": "soil_temp"
},
{
"configured": true,
"id": "outside_temp"
}
]
}
```

We can also read configuration for each sensor individually:

```bash
http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=27&sensor_id=outside_temp"
```

```json
{
"resolution": "Bit_10",
"serial_number": "1C:AB:87:00:00:00"
}
```

```bash
http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=27&sensor_id=soil_temp"
```

```json
{
"resolution": "Bit_10",
"serial_number": "85:BB:87:00:00:00"
}
```

If one of the sensors has broken, or you've decided for some reason to change the configuration of the sensors, you can erase the configuration for each sensor individually and then reconfigure it. Let's erase the configuration for the "outside_temp" sensor:

```bash
http "bonsai-firmware.local/sensor/ds18b20/erase_configuration?gpio=27&sensor_id=outside_temp"
```

```json
{
"resolution": "Bit_10",
"serial_number": "1C:AB:87:00:00:00"
}
```

And now read its configuration:

```bash
http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=27&sensor_id=outside_temp"
```

```json
{
"resolution": "<none>",
"serial_number": "00:00:00:00:00:00"
}
```

Also lets do the scan to ensure the sensor isn't configured:

```bash
http "bonsai-firmware.local/sensor/ds18b20/scan?gpio=27"
```

```json
{
"rom_codes": [
"1C:AB:87:00:00:00",
"85:BB:87:00:00:00"
],
"sensors": [
{
"configured": true,
"id": "soil_temp"
},
{
"configured": false,
"id": "outside_temp"
}
]
}
```

Once the sensors have been serviced, they can be reconfigured and continue to operate without problems. The configuration is persisted on the flash.

Please note that the DS18B20 uses the 1-Wire protocol which is very time sensitive. If communication with the sensor is interrupted in any way, the API call may fail. In this case simply retry the HTTP request. The firmware tries to minimise the influence of other firmware components (WiFi, mDNS) on the 1-wire protocol to ensure it is as stable as possible.
- [DS18B20](sensors/ds18b20.md#HTTP-API)

## Firmware Configuration Options

Expand Down
Loading

0 comments on commit 3474a10

Please sign in to comment.