Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
1-Wire network layer

1-Wire network layer More...

Data Structures

struct  w1_rom
 w1_rom struct. More...
struct  w1_peripheral_config
 Node specific 1-wire configuration struct. More...

Macros

#define W1_SEARCH_ALL_FAMILIES   0x00
 This flag can be passed to searches in order to not filter on family ID.
#define W1_ROM_INIT_ZERO
 Initialize all w1_rom struct members to zero.
#define w1_slave_config   w1_peripheral_config __DEPRECATED_MACRO
 Node specific 1-wire configuration struct.

Typedefs

typedef void(* w1_search_callback_t) (struct w1_rom rom, void *user_data)
 Define the application callback handler function signature for searches.

Functions

int w1_read_rom (const struct device *dev, struct w1_rom *rom)
 Read Peripheral 64-bit ROM.
int w1_match_rom (const struct device *dev, const struct w1_peripheral_config *config)
 Select a specific peripheral by broadcasting a selected ROM.
int w1_resume_command (const struct device *dev)
 Select the peripheral last addressed with a Match ROM or Search ROM command.
int w1_skip_rom (const struct device *dev, const struct w1_peripheral_config *config)
 Select all peripherals regardless of ROM.
int w1_reset_select (const struct device *dev, const struct w1_peripheral_config *config)
 In single drop configurations use Skip Select command, otherwise use Match ROM command.
int w1_write_read (const struct device *dev, const struct w1_peripheral_config *config, const uint8_t *write_buf, size_t write_len, uint8_t *read_buf, size_t read_len)
 Write then read data from the 1-Wire peripheral with matching ROM.
int w1_search_bus (const struct device *dev, uint8_t command, uint8_t family, w1_search_callback_t callback, void *user_data)
 Search 1-wire peripherals on the bus.
static int w1_search_rom (const struct device *dev, w1_search_callback_t callback, void *user_data)
 Search for 1-Wire peripheral on bus.
static int w1_search_alarm (const struct device *dev, w1_search_callback_t callback, void *user_data)
 Search for 1-Wire peripherals with an active alarm.
static uint64_t w1_rom_to_uint64 (const struct w1_rom *rom)
 Function to convert a w1_rom struct to an uint64_t.
static void w1_uint64_to_rom (const uint64_t rom64, struct w1_rom *rom)
 Function to write an uint64_t to struct w1_rom pointer.
static uint8_t w1_crc8 (const uint8_t *src, size_t len)
 Compute CRC-8 chacksum as defined in the 1-Wire specification.
static uint16_t w1_crc16 (const uint16_t seed, const uint8_t *src, const size_t len)
 Compute 1-Wire variant of CRC 16.

1-Wire ROM Commands

#define W1_CMD_SKIP_ROM   0xCC
 This command allows the bus controller to read the peripheral devices without providing their ROM code.
#define W1_CMD_MATCH_ROM   0x55
 This command allows the bus controller to address a specific peripheral device by providing its ROM code.
#define W1_CMD_RESUME   0xA5
 This command allows the bus controller to resume a previous read out from where it left off.
#define W1_CMD_READ_ROM   0x33
 This command allows the bus controller to read the ROM code from a single peripheral device.
#define W1_CMD_SEARCH_ROM   0xF0
 This command allows the bus controller to discover the addresses (i.e., ROM codes) of all peripheral devices on the bus.
#define W1_CMD_SEARCH_ALARM   0xEC
 This command allows the bus controller to identify which devices have experienced an alarm condition.
#define W1_CMD_OVERDRIVE_SKIP_ROM   0x3C
 This command allows the bus controller to address all devices on the bus and then switch them to overdrive speed.
#define W1_CMD_OVERDRIVE_MATCH_ROM   0x69
 This command allows the bus controller to address a specific device and switch it to overdrive speed.

CRC Defines

#define W1_CRC8_SEED   0x00
 Seed value used to calculate the 1-Wire 8-bit crc.
#define W1_CRC8_POLYNOMIAL   0x8C
 Polynomial used to calculate the 1-Wire 8-bit crc.
#define W1_CRC16_SEED   0x0000
 Seed value used to calculate the 1-Wire 16-bit crc.
#define W1_CRC16_POLYNOMIAL   0xa001
 Polynomial used to calculate the 1-Wire 16-bit crc.

Detailed Description

1-Wire network layer

Macro Definition Documentation

◆ W1_CMD_MATCH_ROM

#define W1_CMD_MATCH_ROM   0x55

#include <zephyr/drivers/w1.h>

This command allows the bus controller to address a specific peripheral device by providing its ROM code.

◆ W1_CMD_OVERDRIVE_MATCH_ROM

#define W1_CMD_OVERDRIVE_MATCH_ROM   0x69

#include <zephyr/drivers/w1.h>

This command allows the bus controller to address a specific device and switch it to overdrive speed.

◆ W1_CMD_OVERDRIVE_SKIP_ROM

#define W1_CMD_OVERDRIVE_SKIP_ROM   0x3C

#include <zephyr/drivers/w1.h>

This command allows the bus controller to address all devices on the bus and then switch them to overdrive speed.

◆ W1_CMD_READ_ROM

#define W1_CMD_READ_ROM   0x33

#include <zephyr/drivers/w1.h>

This command allows the bus controller to read the ROM code from a single peripheral device.

This command should be used when there is only a single peripheral device on the bus.

◆ W1_CMD_RESUME

#define W1_CMD_RESUME   0xA5

#include <zephyr/drivers/w1.h>

This command allows the bus controller to resume a previous read out from where it left off.

◆ W1_CMD_SEARCH_ALARM

#define W1_CMD_SEARCH_ALARM   0xEC

#include <zephyr/drivers/w1.h>

This command allows the bus controller to identify which devices have experienced an alarm condition.

◆ W1_CMD_SEARCH_ROM

#define W1_CMD_SEARCH_ROM   0xF0

#include <zephyr/drivers/w1.h>

This command allows the bus controller to discover the addresses (i.e., ROM codes) of all peripheral devices on the bus.

◆ W1_CMD_SKIP_ROM

#define W1_CMD_SKIP_ROM   0xCC

#include <zephyr/drivers/w1.h>

This command allows the bus controller to read the peripheral devices without providing their ROM code.

◆ W1_CRC16_POLYNOMIAL

#define W1_CRC16_POLYNOMIAL   0xa001

#include <zephyr/drivers/w1.h>

Polynomial used to calculate the 1-Wire 16-bit crc.

◆ W1_CRC16_SEED

#define W1_CRC16_SEED   0x0000

#include <zephyr/drivers/w1.h>

Seed value used to calculate the 1-Wire 16-bit crc.

◆ W1_CRC8_POLYNOMIAL

#define W1_CRC8_POLYNOMIAL   0x8C

#include <zephyr/drivers/w1.h>

Polynomial used to calculate the 1-Wire 8-bit crc.

◆ W1_CRC8_SEED

#define W1_CRC8_SEED   0x00

#include <zephyr/drivers/w1.h>

Seed value used to calculate the 1-Wire 8-bit crc.

◆ W1_ROM_INIT_ZERO

#define W1_ROM_INIT_ZERO

#include <zephyr/drivers/w1.h>

Value:
{ \
.family = 0, .serial = { 0 }, .crc = 0, \
}

Initialize all w1_rom struct members to zero.

◆ W1_SEARCH_ALL_FAMILIES

#define W1_SEARCH_ALL_FAMILIES   0x00

#include <zephyr/drivers/w1.h>

This flag can be passed to searches in order to not filter on family ID.

◆ w1_slave_config

#define w1_slave_config   w1_peripheral_config __DEPRECATED_MACRO

#include <zephyr/drivers/w1.h>

Node specific 1-wire configuration struct.

Deprecated
Use struct w1_peripheral_config instead.

Typedef Documentation

◆ w1_search_callback_t

typedef void(* w1_search_callback_t) (struct w1_rom rom, void *user_data)

#include <zephyr/drivers/w1.h>

Define the application callback handler function signature for searches.

Parameters
romfound The ROM of the found peripheral.
user_dataUser data provided to the w1_search_bus() call.

Function Documentation

◆ w1_crc16()

uint16_t w1_crc16 ( const uint16_t seed,
const uint8_t * src,
const size_t len )
inlinestatic

#include <zephyr/drivers/w1.h>

Compute 1-Wire variant of CRC 16.

The 16-bit 1-Wire crc variant is using the reflected polynomial function X^16 + X^15 * + X^2 + 1 with the initial value set to 0x0000. See also APPLICATION NOTE 27: "UNDERSTANDING AND USING CYCLIC REDUNDANCY CHECKS WITH MAXIM 1-WIRE AND IBUTTON PRODUCTS" https://www.analog.com/en/resources/technical-articles/understanding-and-using-cyclic-redundancy-checks-with-maxim-1wire-and-ibutton-products.html

Parameters
seedInit value for the CRC, it is usually set to 0x0000.
[in]srcInput bytes for the computation.
lenLength of the input in bytes.
Returns
The computed CRC16 value.

◆ w1_crc8()

uint8_t w1_crc8 ( const uint8_t * src,
size_t len )
inlinestatic

#include <zephyr/drivers/w1.h>

Compute CRC-8 chacksum as defined in the 1-Wire specification.

The 1-Wire of CRC 8 variant is using 0x31 as its polynomial with the initial value set to 0x00. This CRC is used to check the correctness of the unique 56-bit ROM.

Parameters
[in]srcInput bytes for the computation.
lenLength of the input in bytes.
Returns
The computed CRC8 value.

◆ w1_match_rom()

int w1_match_rom ( const struct device * dev,
const struct w1_peripheral_config * config )

#include <zephyr/drivers/w1.h>

Select a specific peripheral by broadcasting a selected ROM.

This routine allows the 1-Wire bus controller to select a peripheral identified by its unique ROM, such that the next command will target only this single selected peripheral.

This command is only necessary in multidrop environments, otherwise the Skip ROM command can be issued. Once a peripheral has been selected, to reduce the communication overhead, the resume command can be used instead of this command to communicate with the selected peripheral.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]configPointer to the peripheral specific 1-Wire config.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.

◆ w1_read_rom()

int w1_read_rom ( const struct device * dev,
struct w1_rom * rom )

#include <zephyr/drivers/w1.h>

Read Peripheral 64-bit ROM.

This procedure allows the 1-Wire bus controller to read the peripherals’ 64-bit ROM without using the Search ROM procedure. This command can be used as long as not more than a single peripheral is connected to the bus. Otherwise data collisions occur and a faulty ROM is read.

Parameters
[in]devPointer to the device structure for the driver instance.
[out]romPointer to the ROM structure.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.

◆ w1_reset_select()

int w1_reset_select ( const struct device * dev,
const struct w1_peripheral_config * config )

#include <zephyr/drivers/w1.h>

In single drop configurations use Skip Select command, otherwise use Match ROM command.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]configPointer to the peripheral specific 1-Wire config.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.

◆ w1_resume_command()

int w1_resume_command ( const struct device * dev)

#include <zephyr/drivers/w1.h>

Select the peripheral last addressed with a Match ROM or Search ROM command.

This routine allows the 1-Wire bus controller to re-select a peripheral device that was already addressed using a Match ROM or Search ROM command.

Parameters
devPointer to the device structure for the driver instance.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.

◆ w1_rom_to_uint64()

uint64_t w1_rom_to_uint64 ( const struct w1_rom * rom)
inlinestatic

#include <zephyr/drivers/w1.h>

Function to convert a w1_rom struct to an uint64_t.

Parameters
[in]romPointer to the ROM struct.
Returns
The ROM converted to an unsigned integer in host endianness.

◆ w1_search_alarm()

int w1_search_alarm ( const struct device * dev,
w1_search_callback_t callback,
void * user_data )
inlinestatic

#include <zephyr/drivers/w1.h>

Search for 1-Wire peripherals with an active alarm.

This routine searches 1-Wire peripherals on the bus, which currently have an active alarm.

Parameters
[in]devPointer to the device structure for the driver instance.
callbackApplication callback handler function to be called for each found peripheral.
[in]user_dataUser data to pass to the application callback handler function.
Returns
Number of peripherals found, negative errno value on failure.

◆ w1_search_bus()

int w1_search_bus ( const struct device * dev,
uint8_t command,
uint8_t family,
w1_search_callback_t callback,
void * user_data )

#include <zephyr/drivers/w1.h>

Search 1-wire peripherals on the bus.

This function searches peripherals on the 1-wire bus, with the possibility to search either all peripherals or only peripherals that have an active alarm state. If a callback is passed, the callback is called for each found peripheral.

The algorithm mostly follows the suggestions of https://www.analog.com/en/resources/app-notes/1wire-search-algorithm.html

Note: Filtering on families is not supported.

Parameters
[in]devPointer to the device structure for the driver instance.
commandCan either be W1_CMD_SEARCH_ALARM or W1_CMD_SEARCH_ROM.
familyW1_SEARCH_ALL_FAMILIES searcheas all families, filtering on a specific family is not yet supported.
callbackApplication callback handler function to be called for each found peripheral.
[in]user_dataUser data to pass to the application callback handler function.
Returns
Number of peripherals found, negative errno value on failure.

◆ w1_search_rom()

int w1_search_rom ( const struct device * dev,
w1_search_callback_t callback,
void * user_data )
inlinestatic

#include <zephyr/drivers/w1.h>

Search for 1-Wire peripheral on bus.

This routine can discover unknown peripherals on the bus by scanning for the unique 64-bit registration number.

Parameters
[in]devPointer to the device structure for the driver instance.
callbackApplication callback handler function to be called for each found peripheral.
[in]user_dataUser data to pass to the application callback handler function.
Returns
Number of peripherals found, negative errno value on failure.

◆ w1_skip_rom()

int w1_skip_rom ( const struct device * dev,
const struct w1_peripheral_config * config )

#include <zephyr/drivers/w1.h>

Select all peripherals regardless of ROM.

This routine sets up the bus peripherals to receive a command. It is usually used when there is only one peripheral on the bus to avoid the overhead of the Match ROM command. But it can also be used to concurrently write to all peripheral devices.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]configPointer to the peripheral specific 1-Wire config.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.

◆ w1_uint64_to_rom()

void w1_uint64_to_rom ( const uint64_t rom64,
struct w1_rom * rom )
inlinestatic

#include <zephyr/drivers/w1.h>

Function to write an uint64_t to struct w1_rom pointer.

Parameters
rom64Unsigned 64 bit integer representing the ROM in host endianness.
[out]romThe ROM struct pointer.

◆ w1_write_read()

int w1_write_read ( const struct device * dev,
const struct w1_peripheral_config * config,
const uint8_t * write_buf,
size_t write_len,
uint8_t * read_buf,
size_t read_len )

#include <zephyr/drivers/w1.h>

Write then read data from the 1-Wire peripheral with matching ROM.

This routine uses w1_reset_select to select the given ROM. Then writes given data and reads the response back from the peripheral.

Parameters
[in]devPointer to the device structure for the driver instance.
[in]configPointer to the peripheral specific 1-Wire config.
[in]write_bufPointer to the data to be written.
write_lenNumber of bytes to write.
[out]read_bufPointer to storage for read data.
read_lenNumber of bytes to read.
Returns
0 on success, negative errno value on failure.
Return values
-ENODEVNo peripheral responds to reset.