Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update DS18x20 docs #1103

Merged
merged 3 commits into from
Nov 16, 2022
Merged

Update DS18x20 docs #1103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
50ee0b8
Update DS18x20 docs
krystof-k Nov 5, 2022
c18db8f
Mention alias removal
krystof-k Nov 5, 2022
549b643
Fix missing spaces
krystof-k Nov 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/Commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,7 @@ CounterDebounce<a class="cmnd" id="counterdebounce"></a>|`0` = turn off counter
CounterDebounceLow<a class="cmnd" id="counterdebouncelow"></a>|`0` = turn off counter debounce low<BR> `1..32000` = set counter debounce low time in milliseconds. Allow individual debounce times for low pulse widths to discard non valid falling edges. These are checked before legacy CounterDebounce checks distance between two valid falling edges. When unequal zero tasmota will check falling and rising edges on the counter's GPIO. For CounterDebounceLow any GPIO change from low to high hat happens after the GPIO was not low for at least CounterDebounceLow will be ignored. As an example you can set `CounterDebounceLow 50` to allow a valid minimum distance between a falling and rising edge equal to 50ms while having a final CounterDebounce 500 check between to successive valid falling edges equal to 500ms.
CounterDebounceHigh<a class="cmnd" id="counterdebouncehigh"></a>|`0` = turn off counter debounce high<BR> `1..32000` = set counter debounce high time in milliseconds. Allow individual debounce times for high pulse widths to discard non valid falling edges. These are checked before legacy CounterDebounce checks distance between two valid falling edges. When unequal zero tasmota will check falling and rising edges on the counter's GPIO. For CounterDebounceHigh any GPIO change from high to low hat happens after the GPIO was not high for at least CounterDebounceHigh will be ignored. As an example you can set `CounterDebounceHigh 100` to allow a valid minimum distance between a rising and falling edge equal to 100ms while having a final CounterDebounce 500 check between to successive valid falling edges equal to 500ms.
CounterType<x\><a class="cmnd" id="countertype"></a>|`0` = set Counter<x\> as pulse Counter<BR>`1` = set Counter<x\> as pulse Timer
DS18Alias<a class="cmnd" id="ds18alias"></a>|List [DS18x20](DS18x20.md) sensors with full IDs<BR>`<sensor ID>,<n>` = set sensor alias (number)<BR>`<sensor ID>,0` = remove alias
GlobalHum<a class="cmnd" id="globalhum"></a>|`0.0..100.0` = Set global Humidity for some Sensors that uses global Humidity.
GlobalHum2<a class="cmnd" id="globalhum2"></a>|`1..250` = select Global Humidity source indexed from teleperiod occurrence data.
GlobalPress2<a class="cmnd" id="globalpress2"></a>|`1..250` = select Global Pressure source indexed from teleperiod occurrence data.
Expand Down
32 changes: 28 additions & 4 deletions docs/DS18x20.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,10 @@ Shelly dual pin mode is supported by an additional pin assignment:
[`TempOffset`](Commands.md#tempoffset) can be used to add/sub an offset to the measured temperature. This setting affects **all** temperature sensors on the device.

### Multiple Sensors
Tasmota supports multiple DS18x20 sensors connected to a single ESP8266 chip using a single GPIO (multiple DS18x20 GPIO are not supported). The default maximum is set to 8 ([driver code](https://github.com/arendst/Tasmota/blob/development/tasmota/xsns_05_ds18x20.ino#L42)). It is possible to override this number in `user_config_override.h` by adding a line with `#define DS18X20_MAX_SENSORS <new-value>` (ESP8266 only). However one should take into account that:
Tasmota supports multiple DS18x20 sensors connected to a single ESP8266/ESP32 chip using a single or multiple (up to 4) GPIOs. The default maximum is set to 8 sensors ([driver code](https://github.com/arendst/Tasmota/blob/master/tasmota/tasmota_xsns_sensor/xsns_05_ds18x20.ino#L49)). It is possible to override this number in `user_config_override.h` by adding a line with `#define DS18X20_MAX_SENSORS <new-value>` (ESP8266/ESP32 only). However one should take into account that:

* Display on the console is limited and SENSOR log will be truncated above 11 DS18x20.
* MQTT buffer length is limited and SENSOR message will be truncated above 18 DS18x20.
* MQTT buffer length is limited and SENSOR message will be truncated above 18 DS18x20.
* Even less if other sensors are attached to the ESP device and present in the SENSOR message.
* 1-wire has been designed to be a board-bus, not to run through long distances across a whole house. At minimum, use a shielded cable.

Expand All @@ -65,12 +65,36 @@ Every sensors will get a unique ID used in webUI and MQTT telemetry.
{"Time":"2021-01-02T09:09:44","DS18B20-1":{"Id":"00000566CC39","Temperature":13.3},"DS18B20-2":{"Id":"0000059352D4","Temperature":1.2},"DS18B20-3":{"Id":"000005937C90","Temperature":22.5},"TempUnit":"C"}
```

#### Sensor Aliases
By default, sensors are named using the `<sensor model>-<n>` scheme (e.g. `DS18B20-1`), where the number is practically random (based on the sensor's address). This means when you add or remove a sensor, the numbers of the sensors change.

To assign static alias to a certain ID, you can use `DS18Alias` command which can be enabled by setting `#define DS18x20_USE_ID_ALIAS` in `user_config_override.h` and [compiling your own](Compile-your-build.md) binary.

Then you can run `DS18Alias`, which returns full IDs of all the connected sensors and set a static index by using `DS18Alias <sensor ID>,<n>` command, for example `DS18Alias 113C01F096174528,2`. This will rename the sensors to the `DS18Sens-<n>` scheme, leading to the following output of the `DS18Alias` command:

```json
{"DS18Sens-2":{"Id":"113C01F096174528"},"DS18Sens-1":{"Id":"783C01F096F2BB28"},"DS18Sens-3":{"Id":"8B0316C310F3FF28"}}
```

This is not persistent across reboots, therefore you should add a `System#Boot` [rule](Rules.md) (or [`autoexec.bat`](UFS.md#autoexecbat)) so that your aliases are set again after each boot. For example:

```
Rule1 ON System#Boot DO
Backlog DS18Alias 783C01F096F2BB28,1;
DS18Alias 113C01F096174528,2;
DS18Alias 8B0316C310F3FF28,3
ENDON
```

To remove the alias and revert to the default naming, use 0 as the number index `DS18Alias <sensor ID>,0`, for example `DS18Alias 113C01F096174528,0`.

### Compile Options

There are some compile options ([driver code](https://github.com/arendst/Tasmota/blob/development/tasmota/xsns_05_ds18x20.ino#L28)):

`USE_DS18x20_RECONFIGURE`: When sensor is lost keep retrying or re-configure
`DS18x20_USE_ID_AS_NAME`: Use last 3 bytes for naming of sensors
`USE_DS18x20_RECONFIGURE`: When sensor is lost keep retrying or re-configure
`DS18x20_USE_ID_AS_NAME`: Use last 3 bytes for naming of sensors
`DS18x20_USE_ID_ALIAS`: Enable `DS18Alias` command (see [above](#sensor-aliases))

## Sensor Versions
![Sensor variations](https://user-images.githubusercontent.com/5904370/68093451-dba33800-fe95-11e9-95f5-33b7f2c234cd.png)
Expand Down