One Wire HAL

One Wire Hardware Abstraction Layer API Reference. More...

Functions list
err_t	hal_one_wire_open (hal_one_wire_t *obj)
	Opens One Wire HAL object. More...
void	hal_one_wire_configure_default (hal_one_wire_t *obj)
	Configures One Wire HAL configuration structure. More...
err_t	hal_one_wire_reset (hal_one_wire_t *obj)
	Resets One Wire bus. More...
err_t	hal_one_wire_read_rom (hal_one_wire_t *obj, hal_one_wire_rom_address_t *device_rom_address)
	Reads device's ROM information. More...
err_t	hal_one_wire_skip_rom (hal_one_wire_t *obj)
	Access device's level functions without transmitting ROM information. More...
err_t	hal_one_wire_match_rom (hal_one_wire_t *obj, hal_one_wire_rom_address_t *device_rom_address)
	Select a specific One Wire capable device on bus. More...
err_t	hal_one_wire_search_first_device (hal_one_wire_t *obj, hal_one_wire_rom_address_t *one_wire_device_list)
	Search One Wire capable device on bus. More...
err_t	hal_one_wire_search_next_device (hal_one_wire_t *obj, hal_one_wire_rom_address_t *one_wire_device_list)
	Search One Wire capable devices on bus. More...
err_t	hal_one_wire_write_byte (hal_one_wire_t *obj, uint8_t *write_data_buffer, size_t write_data_length)
	Writes byte to One Wire bus. More...
err_t	hal_one_wire_read_byte (hal_one_wire_t *obj, uint8_t *read_data_buffer, size_t read_data_length)
	Reads byte from One Wire bus. More...
void	one_wire_timing_value_a (void)
	Configures device-specific timing "a" sequence value. More...
void	one_wire_timing_value_b (void)
	Configures device-specific timing "b" sequence value. More...
void	one_wire_timing_value_c (void)
	Configures device-specific timing "c" sequence value. More...
void	one_wire_timing_value_d (void)
	Configures device-specific timing "d" sequence value. More...
void	one_wire_timing_value_e (void)
	Configures device-specific timing "e" sequence value. More...
void	one_wire_timing_value_f (void)
	Configures device-specific timing "f" sequence value. More...
void	one_wire_timing_value_h (void)
	Configures device-specific timing "h" sequence value. More...
void	one_wire_timing_value_i (void)
	Configures device-specific timing "i" sequence value. More...
void	one_wire_timing_value_j (void)
	Configures device-specific timing "j" sequence value. More...

Detailed Description

API for configuring and manipulating One Wire HAL module.

Function Documentation

hal_one_wire_open()

err_t hal_one_wire_open

(

hal_one_wire_t *

obj

)

Opens One Wire HAL 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 HAL object. See hal_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 hal structure has been adequately populated beforehand.

Note

It is recommended to check return value for error.

Example

// One Wire HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}

hal_one_wire_configure_default()

void hal_one_wire_configure_default

(

hal_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 HAL object. See hal_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}

hal_one_wire_reset()

err_t hal_one_wire_reset

(

hal_one_wire_t *

obj

)

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

Parameters

[in,out]

*obj

One Wire HAL object. See hal_one_wire_t structure definition for detailed explanation.

Returns

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

Precondition

Before calling this function, the user is expected to call hal_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Send reset sequence on One Wire bus.
hal_one_wire_reset( &hal_one_wire );

hal_one_wire_read_rom()

err_t hal_one_wire_read_rom	(	hal_one_wire_t *	obj,
		hal_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.

Warning

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 HAL 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 hal_one_wire_err_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Read "Family Code" (1 byte), serial number (6 bytes) and CRC (1 byte).
hal_one_wire_read_rom( &hal_one_wire_object_1, &hal_one_wire_device_list );

hal_one_wire_skip_rom()

err_t hal_one_wire_skip_rom

(

hal_one_wire_t *

obj

)

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

Warning

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 HAL object. See hal_one_wire_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_one_wire_err_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_list;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
hal_one_wire_skip_rom( &hal_one_wire_object_1 );
 
// Start temperature conversion of a device.
hal_one_wire_write_byte( &hal_one_wire_object_1, &cmd_convert_temperature, 1 );

hal_one_wire_match_rom()

err_t hal_one_wire_match_rom	(	hal_one_wire_t *	obj,
		hal_one_wire_rom_address_t *	device_rom_address
	)

Select a One Wire device with specific ID.

Parameters

[in]	*obj	One Wire HAL object. See hal_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 hal_one_wire_err_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_list;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Try to match potential device on bus.
hal_one_wire_match( &hal_one_wire, &hal_one_wire_device_list );
 
// Start temperature conversion of a device.
hal_one_wire_write_byte( &hal_one_wire_object_1, &cmd_convert_temperature, 1 );

hal_one_wire_search_first_device()

err_t hal_one_wire_search_first_device	(	hal_one_wire_t *	obj,
		hal_one_wire_rom_address_t *	one_wire_device_list
	)

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

Parameters

[in]	*obj	One Wire HAL object. See hal_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 hal_one_wire_err_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_1;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Find 1st device on One Wire bus.
hal_one_wire_search_first_device( &hal_one_wire_object_1, &hal_one_wire_device_1 );

hal_one_wire_search_next_device()

err_t hal_one_wire_search_next_device	(	hal_one_wire_t *	obj,
		hal_one_wire_rom_address_t *	one_wire_device_list
	)

Search devices that is One Wire capable.

Parameters

[in]	*obj	One Wire HAL object. See hal_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 hal_one_wire_err_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 HAL initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_1;
hal_one_wire_rom_address_t hal_one_wire_device_2;
hal_one_wire_rom_address_t hal_one_wire_device_3;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Find 1st device on One Wire bus.
hal_one_wire_search_first_device( &hal_one_wire_object_1, &hal_one_wire_device_1 );
 
// Find 2nd device on One Wire bus.
hal_one_wire_search_next_device( &hal_one_wire_object_1, &hal_one_wire_device_2 );
 
// Find 3rd device on One Wire bus.
hal_one_wire_search_next_device( &hal_one_wire_object_1, &hal_one_wire_device_3 );

hal_one_wire_write_byte()

err_t hal_one_wire_write_byte	(	hal_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 HAL object. See hal_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 hal_one_wire_err_t, which is size dependant on the architecture.

Precondition

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

Example

// Command to write on bus.
uint8_t cmd_write_command = 0x44;
 
// One Wire driver initialization configuration structure.
static hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_list;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
hal_one_wire_skip_rom( &hal_one_wire_object_1 );
 
// Start temperature conversion of a device.
hal_one_wire_write_byte( &hal_one_wire_object_1, &cmd_write_command, 1 );

hal_one_wire_read_byte()

err_t hal_one_wire_read_byte	(	hal_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 HAL object. See hal_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 hal_one_wire_err_t, which is size dependant on the architecture.

Precondition

Before calling this function, the user is expected to call hal_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 hal_one_wire_t hal_one_wire_object_1;
 
// One Wire ROM address variable.
hal_one_wire_rom_address_t hal_one_wire_device_list;
 
// Configure default One Wire properties.
hal_one_wire_configure_default( &hal_one_wire_object_1 );
 
// Specify desired One Wire pin.
hal_one_wire_object_1.data_pin = MIKROBUS_1_PWM;
 
// Allocate resources for One Wire protocol.
if ( HAL_ONE_WIRE_SUCCESS != hal_one_wire_open( &hal_one_wire_object_1 ) ) {
 // Error handling strategy.
 return HAL_ONE_WIRE_ERROR; // To give an example...
}
 
// Skip sending ROM information of a device
// (this device is the only one on One Wire bus).
hal_one_wire_skip_rom( &hal_one_wire_object_1 );
 
// Start temperature conversion of a device.
hal_one_wire_write_byte( &hal-one_wire_object_1, &cmd_write_command, 1 );
 
// Check temperature conversion status.
hal_one_wire_read_byte( &hal_one_wire_pin_1, &conversion_status, 1 );

one_wire_timing_value_a()

void one_wire_timing_value_a

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_b()

void one_wire_timing_value_b

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_c()

void one_wire_timing_value_c

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_d()

void one_wire_timing_value_d

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_e()

void one_wire_timing_value_e

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_f()

void one_wire_timing_value_f

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_h()

void one_wire_timing_value_h

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_i()

void one_wire_timing_value_i

(

void

)

Configures custom One Wire delay.

Returns

none

one_wire_timing_value_j()

void one_wire_timing_value_j

(

void

)

Configures custom One Wire delay.

Returns

none