# ds18b20

1 wire library for DS18b20

Author | Jean Marchaudon, Copyright © 2010..2010, all rights reserved.
Adapted-by | And-Tech.pl, Bert van Dam, Jean Marchaudon, Olivier Seit,
Compiler | >=2.4m

Description

    1 wire routines for the DS18b20 temperature probe
       Read sensor temperature DS18b20 from a specific device using the
       drive's ID

    use _s_ procedures when there is only one device on the bus.
    use _m_ procedures when there is more than one device on the bus.

Sources

    ds18b20 datasheet (http://datasheets.maxim-ic.com/en/ds/DS18B20.pdf)

Notes

    requires 1_wire.jal

Dependencies

No dependency found

## Summary

### Global variables/contants

- `var byte scratchpad[9]`

### Procedures

- `ds18b20_m_convert(byte in id[])`
- `ds18b20_convert()`
- `ds18b20_setup(sbyte in th, sbyte in tl, byte in resolution)`

Private

- `_ds18b20_skip_rom()`
- `_ds18b20_match_rom(byte in id[])`

### Functions

- `ds18b20_m_temp(byte in id[], sword out temperature) return bit`
- `ds18b20_s_read_rom() return bit`
- `ds18b20_s_temp(sword out temperature) return bit`

Private

- `_ds18b20_read( byte in nbre_byte ) return bit`

## API details

### Global variables/contants

- `var byte scratchpad[9]`

  No documentation found

### Procedures

- `ds18b20_m_convert(byte in id[])`

      ds18b20_m_convert - start conversion of a specific devices on the bus.

      Parameter: 8-byte ID of device to operate on

- `ds18b20_convert()`

      ds18b20_convert - start conversion of all devices on the bus.

      This is actually like an _s_ procedure. When it is executed on a bus with
      multiple ds18b20 devices, all will start conversion.

- `ds18b20_setup(sbyte in th, sbyte in tl, byte in resolution)`

      ds18b20_setup -- !!! UNTESTED !!!

      ***** YOU DON'T NEED THIS FUNCTION FOR TEMPERATURE *****
      *****   READING WITH 12 BIT (DEFAULT) RESOLUTION   *****
      *** PLEASE REPORT IF YOU TESTED THIS FUNCTION (PARTLY OR FULL) ***
      resolution can be 9, 10, 11, 12
      TL = minimum -55
      TH = maximum 124

Private

- `_ds18b20_skip_rom()`

      _ds18b20_skip_rom - activate all devices on the bus

      Note: not sure if 'all devices' means all ds18b20 devices or all one_wire
      devices. I guess this is beyond the scope of this library though ;)

- `_ds18b20_match_rom(byte in id[])`

      _ds18b20_match_rom - activate specified device

      Parameter: 8-byte ID of device to operate on

### Functions

- `ds18b20_m_temp(byte in id[], sword out temperature) return bit`

      ds18b20_m_temp - read temperature from single device on bus

      Use this procedure when there is more than one device on the one_wire bus.
      behavior of this procedure (retry, converions) is influenced by
      constants, see lib header.
      return:  true if success (crc okay).

- `ds18b20_s_read_rom() return bit`

      ds18b20_s_read_rom - read ID from single device on bus

      Only use this procedure when there is only one device on the one_wire bus.
      result is 8-byte ID in the scratchpad area
      return:  true if success (crc okay).

- `ds18b20_s_temp(sword out temperature) return bit`

      ds18b20_s_temp - read temperature from single device on bus

      Only use this procedure when there is only one device on the one_wire bus.
      behavior of this procedure (retry, converions) is influenced by
      constants, see lib header.
      return:  true if success (crc okay).

Private

- `_ds18b20_read( byte in nbre_byte ) return bit`

      _ds18b20_read - read the requested number of bytes

      The result is stored in scratchpad for further processiong.
      crc of received data is calculated.

      parameter: nbre_byte:   8 when you read rom ID
      9 when you read the scratchpad

      return:  true if success (crc okay).

## Related samples

Here are the list of samples which use this library:

16f648a | 16f648a_ds18b20_single.jal
16f877 | 16f877_ds18b20_single.jal
16f877a | 16f877a_ds18b20_single.jal
16f88 | 16f88_ds18b20_single.jal
18f2450 | 18f2450_ds18b20_single.jal
18f2585 | 18f2585_1wire_ds1820.jal
18f452 | 18f452_ds18b20_single.jal
18f4550 | 18f4550_ds18b20_single.jal