One Wire Master Driver

One Wire Master Driver API Reference. More...

Functions list
err_t	one_wire_open (one_wire_t *obj)
	Opens One Wire Driver object. More...
void	one_wire_configure_default (one_wire_t *obj)
	Configures One Wire Driver configuration structure. More...
err_t	one_wire_reset (one_wire_t *obj)
	Resets One Wire bus. More...
err_t	one_wire_read_rom (one_wire_t *obj, one_wire_rom_address_t *device_rom_address)
	Reads device's ROM information. More...
err_t	one_wire_skip_rom (one_wire_t *obj)
	Access device's level functions without transmitting ROM information. More...
err_t	one_wire_match_rom (one_wire_t *obj, one_wire_rom_address_t *device_rom_address)
	Select a specific One Wire capable device on bus. More...
err_t	one_wire_search_first_device (one_wire_t *obj, one_wire_rom_address_t *one_wire_device_list)
	Search One Wire capable device on bus. More...
err_t	one_wire_search_next_device (one_wire_t *obj, one_wire_rom_address_t *one_wire_device_list)
	Search One Wire capable devices on bus. More...
err_t	one_wire_write_byte (one_wire_t *obj, uint8_t *write_data_buffer, size_t write_data_length)
	Writes byte to One Wire bus. More...
err_t	one_wire_read_byte (one_wire_t *obj, uint8_t *read_data_buffer, size_t read_data_length)
	Reads byte from One Wire bus. More...

Detailed Description

One Wire Master Driver API header. Contains all enums, structures and function declarations available for One Wire Master module.

Function Documentation

one_wire_open()

err_t one_wire_open

(

one_wire_t *

obj

)

Opens One Wire driver object on selected pin. Enables appropriate PORT clock, configures pin to have digital output functionality, makes sure that HIGH voltage state is applied on pin before any One Wire actions.

Parameters

[in,out]

*obj

One Wire driver object. See one_wire_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Precondition

Make sure that driver structure has been adequately populated beforehand.

Note

It is recommended to check return value for error.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_configure_default()

void one_wire_configure_default

(

one_wire_t *

obj

)

Configures One Wire configuration structure to default initialization values. Take into consideration that this is just structure variable initial values setting. User must redefine only one value - data_pin.

Parameters

[in,out]

*obj

One Wire driver object. See one_wire_t structure definition for detailed explanation.

Default values:

Function	Default value
Data pin	0xFFFFFFFF (invalid pin)
state	Pin state, do not alter.

Returns

Nothing.

Precondition

The user is expected to call this function before one_wire_open.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_reset()

err_t one_wire_reset

(

one_wire_t *

obj

)

Host shall send reset sequence and devices shall go into reset state.

Parameters

[in,out]

*obj

One Wire driver object. See one_wire_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Send reset sequence on One Wire bus.
if ( ONE_WIRE_SUCCESS != one_wire_reset( &one_wire ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_read_rom()

err_t one_wire_read_rom	(	one_wire_t *	obj,
		one_wire_rom_address_t *	device_rom_address
	)

Allows the host to read eight-bit family code, 48-bit serial number, and eight-bit CRC.

IMPORTANT - THIS FUNCTION IS TO BE ISSUED ONLY IF WE ARE DEALING WITH ONE DEVICE ONLY. THIS FUNCTION AUTOMATICALLY RESETS ONE WIRE BUS.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[out]	*device_rom_address	Buffer for One Wire device ROM information.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Read "Family Code" (1 byte), serial number (6 bytes) and CRC (1 byte).
if ( ONE_WIRE_SUCCESS != one_wire_read_rom( &one_wire_object_1, &one_wire_device_list ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_skip_rom()

err_t one_wire_skip_rom

(

one_wire_t *

obj

)

Allows the host to access device functions without providing the 64-bit ROM identification number.

IMPORTANT - THIS FUNCTION IS TO BE ISSUED ONLY IF WE ARE DEALING WITH ONE DEVICE ONLY. THIS FUNCTION AUTOMATICALLY RESETS ONE WIRE BUS.

Parameters

[in]

*obj

One Wire driver object. See one_wire_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Convert temperature command sequence for Thermo 19 Click.
uint8_t cmd_convert_temperature = 0x44;
 
// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variable.
one_wire_rom_address_t one_wire_device_list;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
one_wire_skip_rom( &one_wire_object_1 );
 
// Start temperature conversion of a device.
if ( ONE_WIRE_SUCCESS != one_wire_write_byte( &one_wire_object_1, &cmd_convert_temperature, 1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_match_rom()

err_t one_wire_match_rom	(	one_wire_t *	obj,
		one_wire_rom_address_t *	device_rom_address
	)

Select a One Wire device with specific ID.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[in]	device_rom_address	Buffer for One Wire device ROM information.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// Convert temperature command sequence for Thermo 19 Click.
uint8_t cmd_convert_temperature = 0x44;
 
// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variable.
one_wire_rom_address_t one_wire_device_list;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Try to match potential device on bus.
one_wire_match( &one_wire, &one_wire_device_list );
 
// Start temperature conversion of a device.
if ( ONE_WIRE_SUCCESS != one_wire_write_byte( &one_wire_object_1, &cmd_convert_temperature, 1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_search_first_device()

err_t one_wire_search_first_device	(	one_wire_t *	obj,
		one_wire_rom_address_t *	one_wire_device_list
	)

Search and list 1st device that is One Wire capable.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[out]	*one_wire_device_list	Buffer for One Wire device ROM information.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variable.
one_wire_rom_address_t one_wire_device_1;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Find 1st device on One Wire bus.
if ( ONE_WIRE_SUCCESS != one_wire_search_first_device( &one_wire_object_1, &one_wire_device_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_search_next_device()

err_t one_wire_search_next_device	(	one_wire_t *	obj,
		one_wire_rom_address_t *	one_wire_device_list
	)

Search devices that are One Wire capable.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[out]	*one_wire_device_list	Buffer for One Wire device ROM information.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Warning

The following example describes how the function is used. Take into consideration that different hardware might not have the same pins. Make sure to accommodate pin name based on your hardware specifics.

Example

// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variables.
one_wire_rom_address_t one_wire_device_1;
one_wire_rom_address_t one_wire_device_2;
one_wire_rom_address_t one_wire_device_3;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Find 1st device on One Wire bus.
one_wire_search_first_device( &one_wire_object_1, &one_wire_device_1 );
 
// Find 2nd device on One Wire bus.
one_wire_search_next_device( &one_wire_object_1, &one_wire_device_2 );
 
// Find 3rd device on One Wire bus.
if ( ONE_WIRE_SUCCESS != one_wire_search_next_device( &one_wire_object_1, &one_wire_device_3 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_write_byte()

err_t one_wire_write_byte	(	one_wire_t *	obj,
		uint8_t *	write_data_buffer,
		size_t	write_data_length
	)

Writes byte to One Wire bus.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[in]	*write_data_buffer	Data transmit buffer.
[in]	write_data_length	Number of bytes to write from data transmit buffer.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Example

// Command to write on bus.
uint8_t cmd_write_command = 0x44;
 
// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variable.
one_wire_rom_address_t one_wire_device_list;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
one_wire_skip_rom( &one_wire_object_1 );
 
// Start temperature conversion of a device.
if ( ONE_WIRE_SUCCESS != one_wire_write_byte( &one_wire_object_1, &cmd_write_command, 1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}

one_wire_read_byte()

err_t one_wire_read_byte	(	one_wire_t *	obj,
		uint8_t *	read_data_buffer,
		size_t	read_data_length
	)

Reads byte from One Wire bus.

Parameters

[in]	*obj	One Wire driver object. See one_wire_t structure definition for detailed explanation.
[out]	*read_data_buffer	Data receive buffer.
[in]	read_data_length	Number of bytes to be read.

Returns

The function can return one of the values defined by one_wire_error_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call one_wire_open function.

Example

// Command to write on bus.
uint8_t cmd_write_command = 0x44;
 
// Variable for storing temperature conversion status.
uint8_t conversion_status = 0;
 
// One Wire driver initialization configuration structure.
static one_wire_t one_wire_object_1;
 
// One Wire ROM address variable.
one_wire_rom_address_t one_wire_device_list;
 
// Configure default One Wire properties.
one_wire_configure_default( &one_wire_object_1 );
 
// Specify desired One Wire pin.
one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( ONE_WIRE_SUCCESS != one_wire_open( &one_wire_object_1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
one_wire_skip_rom( &one_wire_object_1 );
 
// Start temperature conversion of a device.
one_wire_write_byte( &one_wire_object_1, &cmd_write_command, 1 );
 
// Check temperature conversion status.
if ( ONE_WIRE_SUCCESS != one_wire_read_byte( &one_wire_pin_1, &conversion_status, 1 ) ) {
 // Error handling strategy.
 return ONE_WIRE_ERROR; // To give an example...
}