Home

avr-ds18b20

This is detailed description of avr-ds18b20 library. If you have any questions feel free to email me.

1-Wire

1-Wire library consists of three functions:

• onewireInit( ... ) - initiates 1-Wire bus (sends reset inpulse)
• onewireRead( ... ) - reads single byte from 1-Wire bus
• onewireWrite( ... ) - writes single byte to 1-Wire bus

Each of those functions takes arguments such as:

• port output register address (e.g. &PORTA or &PORTC)
• port direction register address (e.g. &DDRC or &DDRD)
• port input register address (e.g. &PINC or &PINB)
• a bit mask (e.g. ( 1 << 5 ) when sensors is connected to the pin 5)

and in case of onewireWrite an uint8_t value to be sent.

Additionally, onewireInit function returns an error code, which can be one of those values:

Value	Macro	Description
0	ONEWIRE_ERROR_OK	No error occurred
1	ONEWIRE_ERROR_COMM	Communication error occurred

Functions described above disable global interrupts when they are called, but SREG value is restored before they exit.

DS18B20

avr-ds18b20 library contains following functions:

• ds18b20convert( ... ) - requests temperature conversion on selected sensor
• ds18b20read( ... ) - reads temperature from sensors (obtained during last conversion)
• ds18b20rom( ... ) - reads ROM address of the sensor
• ds18b20rsp( ... ) - reads sensor's scratchpad contents
• ds18b20wsp( ... ) - writes configuration bytes in sensor's scratchpad
• ds18b20csp( ... ) - copies sensor's configuration into its EEPROM

---

ds18b20convert

Description: requests temperature conversion on selected sensor. Conversion duration may vary, depending on sensor's precision. Please take look at datasheet.

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address (NULL if you want to skip matching)

---

ds18b20read

Description: reads temperature data from sensor into an int16_t variable. Returned value is actual temperature multiplied by 16 (DS18B20_MUL value)

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address (NULL if you want to skip matching)
int16_t *temperature	Temperature data is going to be stored in the variable under this address

---

ds18b20rom

Description: reads rom address into array.

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address is going to be stored here (8b)

---

ds18b20rsp

Description: reads sensor's scratchpad content into array.

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address (NULL if you want to skip matching)
uint8_t *sp	Scratchpad content is going to be stored here (9b)

---

ds18b20wsp

Description: writes configuration bytes in sensor's scratchpad. Sensor's precision can be set this way.

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address (NULL if you want to skip matching)
uint8_t tl	Thermostat low temperature
uint8_t th	Thermostat hight temperature
uint8_t conf	Configuration data

To set precision, pass those macros as the last argument:

• DS18B20_RES09 - 9 bits
• DS18B20_RES10 - 10 bits
• DS18B20_RES11 - 11 bits
• DS18B20_RES12 - 12 bits

---

ds18b20csp

Description: copies sensor's configuration into its EEPROM in order to make it persistent between power-up cycles. This is rather long process and it takes around 10ms.

Argument	Description
volatile uint8_t *port	Port output register address
volatile uint8_t *direction	Port direction register address
volatile uint8_t *portin	Port input register address
uint8_t mask	Bit mask (describes on which pin sensor is connected)
uint8_t *rom	ROM address (NULL if you want to skip matching)

---

Every function described above also returns an error code. Those are possible values:

Value	Macro	Description
0	DS18B20_ERROR_OK	No error occurred
1	DS18B20_ERROR_COMM	Communication error occurred
2	DS18B20_ERROR_CRC	Received data is invalid
3	DS18B20_ERROR_PULL	Only zero's were received. This is most likely an issue with pull-up resistor on 1-Wire bus
4	DS18B20_ERROR_OTHER	Some other error occurred. For example, user tried to read ROM with ds18b20rom into NULL pointer