nodemcu-firmware/docs/modules/ow.md

1-Wire Module

Since	Origin / Contributor	Maintainer	Source
2014-12-22	Zeroday	Zeroday	ow.c

This module provides functions to work with the 1-Wire device communications bus system.

ow.check_crc16()

Computes the 1-Wire CRC16 and compare it against the received CRC.

Syntax

ow.check_crc16(buf, inverted_crc0, inverted_crc1[, crc])

Parameters

• buf string value, data to be calculated check sum in string
• inverted_crc0 LSB of received CRC
• inverted_crc1 MSB of received CRC
• crc CRC starting value (optional)

Returns

true if the CRC matches, false otherwise

ow.crc16()

Computes a Dallas Semiconductor 16 bit CRC. This is required to check the integrity of data received from many 1-Wire devices. Note that the CRC computed here is not what you'll get from the 1-Wire network, for two reasons:

1. The CRC is transmitted bitwise inverted.
2. Depending on the endian-ness of your processor, the binary representation of the two-byte return value may have a different byte order than the two bytes you get from 1-Wire.

Syntax

ow.crc16(buf[, crc])

Parameters

• buf string value, data to be calculated check sum in string
• crc CRC starting value (optional)

Returns

the CRC16 as defined by Dallas Semiconductor

ow.crc8()

Computes a Dallas Semiconductor 8 bit CRC, these are used in the ROM and scratchpad registers.

Syntax

ow.crc8(buf)

Parameters

buf string value, data to be calculated check sum in string

Returns

CRC result as byte

ow.depower()

Stops forcing power onto the bus. You only need to do this if you used the 'power' flag to ow.write() or used a ow.write_bytes() and aren't about to do another read or write.

Syntax

ow.depower(pin)

Parameters

pin 1~12, I/O index

Returns

nil

See also

• ow.write()
• ow.write_bytes()

ow.read()

Reads a byte.

Syntax

ow.read(pin)

Parameters

pin 1~12, I/O index

Returns

byte read from slave device

ow.read_bytes()

Reads multi bytes.

Syntax

ow.read_bytes(pin, size)

Parameters

• pin 1~12, I/O index
• size number of bytes to be read from slave device (up to 256)

Returns

string bytes read from slave device

ow.reset()

Performs a 1-Wire reset cycle.

Syntax

ow.reset(pin)

Parameters

pin 1~12, I/O index

Returns

• 1 if a device responds with a presence pulse
• 0 if there is no device or the bus is shorted or otherwise held low for more than 250 µS

ow.reset_search()

Clears the search state so that it will start from the beginning again.

Syntax

ow.reset_search(pin)

Parameters

pin 1~12, I/O index

Returns

nil

ow.search()

Looks for the next device.

Syntax

ow.search(pin, [alarm_search])

Parameters

• pin 1~12, I/O index
• alarm_search 1 / 0, if 0 a regular 0xF0 search is performed (default if parameter is absent), if 1 a 0xEC ALARM SEARCH is performed.

Returns

rom_code string with length of 8 upon success. It contains the rom code of slave device. Returns nil if search was unsuccessful.

See also

ow.target_search()

ow.select()

Issues a 1-Wire rom select command. Make sure you do the ow.reset(pin) first.

Syntax

ow.select(pin, rom)

Parameters

• pin 1~12, I/O index
• rom string value, len 8, rom code of the slave device

Returns

nil

Example

-- 18b20 Example
-- 18b20 Example
pin = 3
ow.setup(pin)
addr = ow.reset_search(pin)
addr = ow.search(pin)

if addr == nil then
  print("No device detected.")
else
  print(addr:byte(1,8))
  local crc = ow.crc8(string.sub(addr,1,7))
  if crc == addr:byte(8) then
    if (addr:byte(1) == 0x10) or (addr:byte(1) == 0x28) then
      print("Device is a DS18S20 family device.")
      tmr.create():alarm(1000, tmr.ALARM_AUTO, function()
          ow.reset(pin)
          ow.select(pin, addr)
          ow.write(pin, 0x44, 1) -- convert T command
          tmr.create():alarm(750, tmr.ALARM_SINGLE, function()
              ow.reset(pin)
              ow.select(pin, addr)
              ow.write(pin,0xBE,1) -- read scratchpad command
              local data = ow.read_bytes(pin, 9)
              print(data:byte(1,9))
              local crc = ow.crc8(string.sub(data,1,8))
              print("CRC="..crc)
              if crc == data:byte(9) then
                 local t = (data:byte(1) + data:byte(2) * 256) * 625
                 local sgn = t<0 and -1 or 1
                 local tA = sgn*t
                 local t1 = math.floor(tA / 10000)
                 local t2 = tA % 10000
                 print("Temperature="..(sgn<0 and "-" or "")..t1.."."..t2.." Centigrade")
              end
          end)
      end)
    else
      print("Device family is not recognized.")
    end
  else
    print("CRC is not valid!")
  end
end

See also

ow.reset()

ow.setup()

Sets a pin in onewire mode.

Syntax

ow.setup(pin)

Parameters

pin 1~12, I/O index

Returns

nil

ow.skip()

Issues a 1-Wire rom skip command, to address all on bus.

Syntax

ow.skip(pin)

Parameters

pin 1~12, I/O index

Returns

nil

ow.target_search()

Sets up the search to find the device type family_code. The search itself has to be initiated with a subsequent call to ow.search().

Syntax

ow.target_search(pin, family_code)

Parameters

• pin 1~12, I/O index
• family_code byte for family code

Returns

nil

See also

ow.search()

ow.write()

Writes a byte. If power is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling ow.depower() or doing another read or write.

Syntax

ow.write(pin, v, power)

Parameters

• pin 1~12, I/O index
• v byte to be written to slave device
• power 1 for wire being held high for parasitically powered devices

Returns

nil

See also

ow.depower()

ow.write_bytes()

Writes multi bytes. If power is 1 then the wire is held high at the end for parasitically powered devices. You are responsible for eventually depowering it by calling ow.depower() or doing another read or write.

Syntax

ow.write_bytes(pin, buf, power)

Parameters

• pin 1~12, IO index
• buf string to be written to slave device
• power 1 for wire being held high for parasitically powered devices

Returns

nil

See also

ow.depower()

ow.set_timings()

Tweak different bit timing parameters. Some slow custom devices might not work perfectly well with NodeMCU as 1-wire master. Since NodeMCU ow module is bit-banging the 1-wire protocol, it is possible to adjust the timings a bit.

Note that you can break the protocol totally if you tweak some numbers too much. This should never be needed with normal devices.

Syntax

ow.set_timings(reset_tx, reset_wait, reset_rx, w1_low, w1_high, w0_low, w0_high, r_low, r_wait, r_delay)

Parameters

Each parameter specifies number of microseconds to delay at different stages in the 1-wire bit-banging process. A nil value will leave the value unmodified.

• reset_tx pull bus low during reset (default 480)
• reset_wait wait for presence pulse after reset (default 70)
• reset_rx delay after presence pulse have been checked (default 410)
• w1_low pull bus low during write 1 slot (default 5)
• w1_high leave bus high during write 1 slot (default 52)
• w0_low pull bus low during write 1 slot (default 65)
• w0_high leave bus high during write 1 slot (default 5)
• r_low pull bus low during read slot (default 5)
• r_wait wait before reading bus level during read slot (default 8)
• r_delay delay after reading bus level (default 52)

Returns

nil

Example

-- Give 300uS longer read/write slots for slow MCU based 1-wire slave
ow.set_timings(
	nil, -- reset_tx
	nil, -- reset_wait
	nil, -- reset_rx
	nil, -- w1_low
	352, -- w1_high
	nil, -- w0_low
	305, -- w0_high
	nil, -- r_low
	nil, -- r_wait
	352  -- r_delay
)