From 3474a10ef5c97a0c47b67e411edeb90d4d1eb359 Mon Sep 17 00:00:00 2001 From: Dmitriy Shilin Date: Tue, 12 Nov 2024 09:09:43 +0100 Subject: [PATCH] Rework documentation for DS18B20 sensor --- docs/httpserver.md | 197 +-------------------------------------- docs/sensors/ds18b20.md | 199 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 201 insertions(+), 195 deletions(-) diff --git a/docs/httpserver.md b/docs/httpserver.md index 82c1aed..ce81392 100644 --- a/docs/httpserver.md +++ b/docs/httpserver.md @@ -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 number to which sensor is connected. - -```bash -http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=&sensor_id=" -``` - -- `` - GPIO number to which sensor is connected. -- `` - unique sensor identifier, used internally by firmware, see the description below. - -```bash -http "bonsai-firmware.local/sensor/ds18b20/write_configuration?gpio=&sensor_id=&seria -l_number=&resolution=" -``` - -- `` - GPIO number to which sensor is connected -- `` - unique sensor identifier, defined internally by firmware -- `` can be obtained with the `scan` API, mentioned previously -- `` - how precise the temperature would be measured - -`` 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": "", - "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 diff --git a/docs/sensors/ds18b20.md b/docs/sensors/ds18b20.md index a264612..949306f 100644 --- a/docs/sensors/ds18b20.md +++ b/docs/sensors/ds18b20.md @@ -1,3 +1,202 @@ +## Introduction + +[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. + +## HTTP API + +DS18B20 sensor has the following APIs: + +```bash +http "bonsai-firmware.local/sensor/ds18b20/scan?gpio=" +``` + +- `` - GPIO number to which sensor is connected. + +```bash +http "bonsai-firmware.local/sensor/ds18b20/read_configuration?gpio=&sensor_id=" +``` + +- `` - GPIO number to which sensor is connected. +- `` - unique sensor identifier, used internally by firmware, see the description below. + +```bash +http "bonsai-firmware.local/sensor/ds18b20/write_configuration?gpio=&sensor_id=&seria +l_number=&resolution=" +``` + +- `` - GPIO number to which sensor is connected +- `` - unique sensor identifier, defined internally by firmware +- `` can be obtained with the `scan` API, mentioned previously +- `` - how precise the temperature would be measured + +`` 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": "", + "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. + ## Firmware Configuration Options - CONFIG_BONSAI_FIRMWARE_SENSOR_DS18B20_DATA_GPIO