{"id":13581418,"url":"https://github.com/Gbertaz/NonBlockingDallas","last_synced_at":"2025-04-06T07:32:06.601Z","repository":{"id":42495574,"uuid":"389220543","full_name":"Gbertaz/NonBlockingDallas","owner":"Gbertaz","description":"Arduino library for the DS18B20 temperature sensor. Avoid blocking the sketch while reading the sensor.","archived":false,"fork":false,"pushed_at":"2024-03-24T12:30:23.000Z","size":38,"stargazers_count":11,"open_issues_count":3,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-05T20:47:13.332Z","etag":null,"topics":["arduino","arduino-library","ds18b20","non-blocking","temperature-sensor"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gbertaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-07-24T23:33:33.000Z","updated_at":"2024-05-05T01:51:28.000Z","dependencies_parsed_at":"2024-01-16T21:11:53.501Z","dependency_job_id":"8ec6408f-05c5-4a2a-baa4-ced8f6ef57b7","html_url":"https://github.com/Gbertaz/NonBlockingDallas","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gbertaz%2FNonBlockingDallas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gbertaz%2FNonBlockingDallas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gbertaz%2FNonBlockingDallas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gbertaz%2FNonBlockingDallas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gbertaz","download_url":"https://codeload.github.com/Gbertaz/NonBlockingDallas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247450268,"owners_count":20940889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","arduino-library","ds18b20","non-blocking","temperature-sensor"],"created_at":"2024-08-01T15:02:01.449Z","updated_at":"2025-04-06T07:32:06.387Z","avatar_url":"https://github.com/Gbertaz.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"[![arduino-library-badge](https://www.ardu-badge.com/badge/NonBlockingDallas.svg?)](https://www.ardu-badge.com/NonBlockingDallas)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/gbertaz/library/NonBlockingDallas.svg)](https://registry.platformio.org/libraries/gbertaz/NonBlockingDallas)\n\n# Non blocking temperature sensor library for Arduino\n\nThis simple library for Arduino implements a machine state for reading the **Maxim Integrated DS18B20 temperature sensor** without blocking the main loop() of the sketch. It is designed for a **continuous sensor reading** every amount of time configurable by the developer. It is also possible to request a new sensor reading on the fly by calling the *requestTemperature()* function.  \n\nWhile the conversion is in progress, the main loop() continues to run so that the sketch can execute other tasks. When the temperature reading is ready, a callback is invoked. At full resolution the conversion time takes up to 750 milliseconds, a huge amount of time, thus the importance of the library to avoid blocking the sketch execution.\n\nSupports up to 15 sensors on the same ONE WIRE bus. \n\n# Installation\n\n## Arduino\n\n### Prerequisites\n\nThis library uses OneWire and DallasTemperature libraries, so you will need to have those installed.\n\n#### Litle breaking changes for new version 1.1x :\n\n* Function `begin()` ==\u003e remove units parameters.\n* In all callback's functions ==\u003e Parameters are not the sames.\n\n### Include library\n\nThe library is available from the Arduino Library Manager: load the Arduino IDE, then use the menu at the top to select Sketch -\u003e Include Library -\u003e Manage Libraries. Type **NonBlockingDallas** in the search box.\n\nClick the following badge for a complete installation guide\n\n[![arduino-library-badge](https://www.ardu-badge.com/badge/NonBlockingDallas.svg?)](https://www.ardu-badge.com/NonBlockingDallas)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/gbertaz/library/NonBlockingDallas.svg)](https://registry.platformio.org/libraries/gbertaz/NonBlockingDallas)\n\n## PlatformIO\n\n[See install documentation](https://registry.platformio.org/libraries/gbertaz/NonBlockingDallas/installation)\n\n# Usage\n\n## Step 1\n\nInclude the required libraries:\n\n```cpp\n#include \u003cOneWire.h\u003e\n#include \u003cDallasTemperature.h\u003e\n#include \u003cNonBlockingDallas.h\u003e\n```\n\n## Step 2\n\nCreate the instance of the classes:\n\n```cpp\nOneWire oneWire(ONE_WIRE_BUS);\nDallasTemperature dallasTemp(\u0026oneWire);\nNonBlockingDallas temperatureSensors(\u0026dallasTemp);\n```\n\n## Step 3\n\nInitialize the sensor and set the callbacks.\nThe parameters of the *begin* function are the **sensor resolution**, **unit of measure** (Celsius or Fahrenheit) and **time interval** in milliseconds.\n\n```cpp\ntemperatureSensors.begin(NonBlockingDallas::resolution_12, 1500);\ntemperatureSensors.onIntervalElapsed(handleIntervalElapsed);\ntemperatureSensors.onTemperatureChange(handleTemperatureChange);\ntemperatureSensors.onDeviceDisconnected(handleDeviceDisconnected);\n```\n\n### Sensors resolution\n\nThe conversion time of the DS18B20 temperature sensor depends on its resolution, thus the **time interval** parameter passed to the *begin* function must be greater than or equal to the conversion time.\n\n|     enum      | Resolution  | Conversion time |\n| ------------- | ----------- | --------------- |\n| resolution_9  |       9 bit |           93 ms |\n| resolution_10 |      10 bit |          187 ms |\n| resolution_11 |      11 bit |          375 ms |\n| resolution_12 |      12 bit |          750 ms |\n\n\n## Step 4\n\nImplement the callbacks' functions and call the *update* function inside the main loop()  \n\n```cpp\nvoid loop()\n{\n\ttemperatureSensors.update();\n}\n\nvoid handleIntervalElapsed(int deviceIndex, int32_t temperatureRAW)\n{\n}\n\nvoid handleTemperatureChange(int deviceIndex, int32_t temperatureRAW)\n{\n\t// If needed, call on the fly conversion\n\tfloat tC = temperatureSensors.rawToCelsius(temperatureRAW);\n\tfloat tF = temperatureSensors.rawToFahrenheit(temperatureRAW);\n}\n\nvoid handleDeviceDisconnected(int deviceIndex)\n{\n}\n```\n\n### Example\n\nPlease see the [Example](https://github.com/Gbertaz/NonBlockingDallas/blob/master/examples/TemperatureReading/TemperatureReading.ino) for a complete working sketch\n\n# Debug\n\nTo get some debug information, simply remove the comment on following line in *NonBlockingDallas.h*:\n\n```cpp\n#define DEBUG_DS18B20\n```\n\nThe output will be like the following:\n\n```log\nDS18B20: 3 sensors found on the bus\nDS18B20: parasite power is OFF\nDS18B20: requested new reading\nDS18B20 (0): 29.37 °C\nDS18B20 (1): 29.12 °C\nDS18B20 (2): 29.26 °C\nDS18B20: requested new reading\nDS18B20 (0): 29.37 °C\nDS18B20 (1): 29.12 °C\nDS18B20 (2): 29.26 °C\n...\n```\n\n# Callbacks\n\nThe library is callback driven:\n- *onIntervalElapsed* invoked **every time** the timer interval is elapsed and the sensor reading is **valid**\n- *onTemperatureChange* invoked **only when the temperature value changes** between two **valid** readings of the same sensor\n- *onDeviceDisconnected* invoked when the device is disconnected\n\nIn the latest version of the library I have introduced *onDeviceDisconnected* which makes the *valid* parameter meaningless. In order to maintain retro compatibility, it will always be *true*. It will be removed in a future version.\n*deviceIndex* represents the index of the sensor on the bus, values are from 0 to 14.\n\n```cpp\nvoid onIntervalElapsed(void(*callback)(int deviceIndex, int32_t temperatureRAW)) {\n\tcb_onIntervalElapsed = callback;\n}\n\nvoid onTemperatureChange(void(*callback)(int deviceIndex, int32_t temperatureRAW)) {\n\tcb_onTemperatureChange = callback;\n}\n\nvoid onDeviceDisconnected(void(*callback)(int deviceIndex)) {\n\tcb_onDeviceDisconnected = callback;\n}\n```\n\n# Additional functions\n\n\n## By deviceIndex\n\n```cpp\nbool indexExist(uint8_t deviceIndex);\nbool getDeviceAddress(uint8_t deviceIndex, DeviceAddress deviceAddress);\nString getAddressString(uint8_t deviceIndex);\nint32_t getTemperatureRAW(uint8_t deviceIndex);\nfloat getTemperatureC(uint8_t deviceIndex);\nfloat getTemperatureF(uint8_t deviceIndex);\n```\n\n## By DeviceAddress\n\n```cpp\nint8_t getIndex(DeviceAddress deviceAddress); // can be sused to test if address exist\nint32_t getTemperatureRAW(DeviceAddress deviceAddress);\nfloat getTemperatureC(DeviceAddress deviceAddress);\nfloat getTemperatureF(DeviceAddress deviceAddress);\n```\n\n## By String address representation\n\n```cpp\nint8_t getIndex(String addressString); // can be sused to test if address exist\nint32_t getTemperatureRAW(String addressString);\nfloat getTemperatureC(String addressString);\nfloat getTemperatureF(String addressString);\n```\n\n## Helpers\n\n### Apply on real sensors\n\n```cpp\nuint8_t getSensorsCount();\nbool validateAddressesRange(DeviceAddress addressesRangeToValidate[], uint8_t numberOfAddresses, bool exclusiveListSet = true);\nbool validateAddressesRange(String addressesStrings[], uint8_t numberOfAddresses, bool exclusiveListSet = true);\nvoid mapIndexPositionOfDeviceAddressRange(DeviceAddress addressesRangeToValidate[], uint8_t numberOfAddresses, int8_t mapedPositions[]);\n```\n\n### Apply on virtual data\n\n```cpp\nbool compareTowDeviceAddresses(DeviceAddress deviceAddress1, DeviceAddress deviceAddress2);\nString convertDeviceAddressToString(DeviceAddress deviceAddress);\nbool convertDeviceAddressStringToDeviceAddress(String addressString, DeviceAddress deviceAddress);\nfloat rawToCelsius(int32_t rawTemperature);\nfloat rawToFahrenheit(int32_t rawTemperature);\nuint8_t charToHex(char c);\nbool towCharToHex(char MSB, char LSB, uint8_t *ptrValue);\n```\n\n## Complex example of usage\n\nSee file `examples/AdditionalFunctions/AdditionalFunctions.ino`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGbertaz%2FNonBlockingDallas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGbertaz%2FNonBlockingDallas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGbertaz%2FNonBlockingDallas/lists"}