Home
This is detailed description of avr-ds18b20 library. If you have any questions feel free to email me.
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.
&PORTAor&PORTC) - port direction register address (e.g.
&DDRCor&DDRD) - port input register address (e.g.
&PINCor&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.
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
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) |
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 |
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) |
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) |
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
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) |
Description: searches for any DS18B20 sensors connected to the given pin and returns concatenated ROMs of connected sensors in roms array. Subsequent ROMs consist of 8 byte portions of the array: roms[0-7], roms[8-15] and so on. The array should be allocated by user beforehand and it's length (in bytes) should be passed as buflen argument. Number of detected senors is written to variable pointed by romcnt pointer.
Note: In order to use this function, romsearch module has to be activated during the compilation. This can be achieved by adding MODULE_ROMSEARCH=1 argument to the make invocation. In case you are using some IDE, adding romsearch.c file to the project should be sufficient. Also, please be aware that ds18b20/romsearch.h header file has to be included in your code.
Code sample:
int16_t temperature; //Temperature value; Needs to be divided by 16 to get the actual temperature
uint8_t roms[8 * 8]; //ROM buffer - we're expecting 8 sensors max and each ROM is 8 bytes long
uint8_t count; //The number of actually connected sensors
ds18b20search( &PORTA, &DDRA, &PINA, ( 1 << 0 ), &count, roms, sizeof( roms ) );
//At this points, if everything succeeds, we should have ROM codes loaded into roms array and number of connected sensors stored in the count variable
//The first ROM is stored at roms[0-7], the second roms[8-15] and so on...
//For instance, to read the data from second sensor:
ds18b20read( &PORTA, &DDRA, &PINA, ( 1 << 0 ), &roms[8], &temperature );| 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 *romcnt |
ROM count is returned through this pointer |
uint8_t *roms |
ROMs are returned in this array |
uint16_t buflen |
roms array size in bytes |
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 |