DS18B20 Module

Since Origin / Contributor Maintainer Source
2017-06-11 fetchbot fetchbot ds18b20.c

This module provides access to the DS18B20 1-Wire digital thermometer. Note that NodeMCU offers both a C module (this one) and a Lua module for this sensor. See #2003 for a discussion on the respective merits of them.

ds18b20.read()

Issues a temperature conversion of all connected sensors on the onewire bus and returns the measurment results after a conversion delay in a callback function. The returned measurements can be filtered through the ROM addresses passed as a table or by the family type. The callback function gets invoked for every specified sensor.

Syntax

ds18b20.read(CALLBACK, ROM[, FAMILY_ADDRESS])

Parameters

  • CALLBACK callback function executed for each sensor
    • e.g. function(INDEX, ROM, RES, TEMP, TEMP_DEC, PAR) print(INDEX, ROM, RES, TEMP, TEMP_DEC, PAR) end
  • ROM table which contains the addresses for the specified sensors, or left empty to perform a onewire bus search for all sensors
    • e.g. {"28:FF:FF:FF:FF:FF:FF:FF","28:FF:FF:FF:FF:FF:FF:FF"}, {}
  • FAMILY_ADDRESS optional to limit the search for devices to a specific family type
    • e.g 0x28

Returns

nil

Callback function parameters

  • INDEX index of the sensor on the bus
  • ROM sensors 64-bit lasered rom code
    • 28:FF:FF:FF:FF:FF:FF:FF LSB, 8-bit family code, 48-bit serial number, MSB 8-bit crc
  • RES temperature resolution
  • TEMP temperature
  • TEMP_DEC temperature decimals for integer firmware
  • PAR sensor parasitic flag

Note

If using float firmware then temp is a floating point number. On an integer firmware, the final value has to be concatenated from temp and temp_dec.

Example

local ow_pin = 3
ds18b20.setup(ow_pin)

-- read all sensors and print all measurement results
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
    end,{});

-- read only sensors with family type 0x28 and print all measurement results
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
    end,{},0x28);

-- save device roms in a variable
local addr = {}
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        addr[ind] = {string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)"))}
    end,{});

-- read only sensors listed in the variable addr
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
    end,addr);

-- print only parasitic sensors
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        if (par == 1) then
            print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
        end
    end,{});

-- print if temperature is greater or less than a defined value
ds18b20.read(
    function(ind,rom,res,temp,tdec,par)
        if (t > 25) then
            print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
        end
        if (t < 20) then
            print(ind,string.format("%02X:%02X:%02X:%02X:%02X:%02X:%02X:%02X",string.match(rom,"(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+):(%d+)")),res,temp,tdec,par)
        end
    end,{});

ds18b20.setting()

Configuration of the temperature resolution settings.

Syntax

ds18b20.setting(ROM, RES)

Parameters

  • ROM table which contains the addresses for the specified sensors, or empty for all sensors
    • e.g. {"28:FF:FF:FF:FF:FF:FF:FF","28:FF:FF:FF:FF:FF:FF:FF"}, {}
  • RES temperature bit resolution
    • 9 - 12

Returns

nil

Example

local ow_pin = 3
ds18b20.setup(ow_pin)

ds18b20.setting({"28:FF:FF:FF:FF:FF:FF:FF","28:FF:FF:FF:FF:FF:FF:FF"}, 9)

ds18b20.setup()

Initializes the onewire bus on the selected pin.

Syntax

ds18b20.setup(OW_BUS_PIN)

Parameters

  • OW_BUS_PIN
    • 1 - 12

Returns

nil

Example

local ow_pin = 3
ds18b20.setup(ow_pin)