co2meter: comparison components/esp32-owb/include/owb.h

-:995557380e5f
+:acc1904cd70d
 * @brief Interface definitions for the 1-Wire bus component.
 *
 * This component provides structures and functions that are useful for communicating
 * with devices connected to a Maxim Integrated 1-Wire® bus via a single GPIO.
 *
-* Currently only externally powered devices are supported. Parasitic power is not supported.
+* Externally powered and "parasite-powered" devices are supported.
+* Please consult your device's datasheet for power requirements.
 */
 #ifndef ONE_WIRE_BUS_H
 #define ONE_WIRE_BUS_H
 #include <stdint.h>
 #include <stdbool.h>
 #include <stddef.h>
+#include "driver/gpio.h"
 #ifdef __cplusplus
 extern "C" {
 #endif
 // ROM commands
-#define OWB_ROM_SEARCH        0xF0	///< Command ROM search
+#define OWB_ROM_SEARCH        0xF0  ///< Perform Search ROM cycle to identify devices on the bus
-#define OWB_ROM_READ          0x33	///< ROM read
+#define OWB_ROM_READ          0x33  ///< Read device ROM (single device on bus only)
-#define OWB_ROM_MATCH         0x55	///< ROM address match
+#define OWB_ROM_MATCH         0x55  ///< Address a specific device on the bus by ROM
-#define OWB_ROM_SKIP          0xCC	///< Skip device
+#define OWB_ROM_SKIP          0xCC  ///< Address all devices on the bus simultaneously
-#define OWB_ROM_SEARCH_ALARM  0xEC	///< Search device with alarm set
+#define OWB_ROM_SEARCH_ALARM  0xEC  ///< Address all devices on the bus with a set alarm flag
 #define OWB_ROM_CODE_STRING_LENGTH (17)  ///< Typical length of OneWire bus ROM ID as ASCII hex string, including null terminator
+#ifndef GPIO_NUM_NC
+#  define GPIO_NUM_NC (-1)  ///< ESP-IDF prior to v4.x does not define GPIO_NUM_NC
+#endif
 struct owb_driver;
 /**
 * @brief Structure containing 1-Wire bus information relevant to a single instance.
 */
 typedef struct
 {
 const struct _OneWireBus_Timing * timing;   ///< Pointer to timing information
 bool use_crc;                               ///< True if CRC checks are to be used when retrieving information from a device on the bus
+bool use_parasitic_power;                   ///< True if parasitic-powered devices are expected on the bus
-const struct owb_driver *driver;
+gpio_num_t strong_pullup_gpio;              ///< Set if an external strong pull-up circuit is required
+const struct owb_driver * driver;           ///< Pointer to hardware driver instance
 } OneWireBus;
 /**
 * @brief Represents a 1-Wire ROM Code. This is a sequence of eight bytes, where
 *        the first byte is the family number, then the following 6 bytes form the
 *        Pass a pointer to this structure to owb_search_first() and
 *        owb_search_next() to iterate through detected devices on the bus.
 */
 typedef struct
 {
-OneWireBus_ROMCode rom_code;
+OneWireBus_ROMCode rom_code;   ///< Device ROM code
-int last_discrepancy;
+int last_discrepancy;          ///< Bit index that identifies from which bit the next search discrepancy check should start
-int last_family_discrepancy;
+int last_family_discrepancy;   ///< Bit index that identifies the last discrepancy within the first 8-bit family code of the ROM code
-int last_device_flag;
+int last_device_flag;          ///< Flag to indicate previous search was the last device detected
 } OneWireBus_SearchState;
 /**
-* @brief Status codes
+* @brief Represents the result of OWB API functions.
 */
 typedef enum
 {
-OWB_STATUS_OK,				///< Ok
+OWB_STATUS_NOT_SET = -1,           ///< A status value has not been set
-OWB_STATUS_NOT_INITIALIZED,			///< Init error
+OWB_STATUS_OK = 0,                 ///< Operation succeeded
-OWB_STATUS_PARAMETER_NULL,			///< NULL parameter
+OWB_STATUS_NOT_INITIALIZED,        ///< Function was passed an uninitialised variable
-OWB_STATUS_DEVICE_NOT_RESPONDING,		///< Device does not respond
+OWB_STATUS_PARAMETER_NULL,         ///< Function was passed a null pointer
-OWB_STATUS_CRC_FAILED,			///< CRC error
+OWB_STATUS_DEVICE_NOT_RESPONDING,  ///< No response received from the addressed device or devices
-OWB_STATUS_TOO_MANY_BITS,			///< Too many bits
+OWB_STATUS_CRC_FAILED,             ///< CRC failed on data received from a device or devices
-OWB_STATUS_HW_ERROR				///< Hardware error
+OWB_STATUS_TOO_MANY_BITS,          ///< Attempt to write an incorrect number of bits to the One Wire Bus
+OWB_STATUS_HW_ERROR                ///< A hardware error occurred
 } owb_status;
 /** NOTE: Driver assumes that (*init) was called prior to any other methods */
 struct owb_driver
 {
 const char* name;
 owb_status (*uninitialize)(const OneWireBus * bus);
+owb_status (*reset)(const OneWireBus *bus, bool *is_present);
-owb_status (*reset)(const OneWireBus * bus, bool *is_present);
-/** NOTE: The data is shifted out of the low bits, eg. it is written in the order of lsb to msb */
 owb_status (*write_bits)(const OneWireBus *bus, uint8_t out, int number_of_bits_to_write);
+owb_status (*write_bytes)(const OneWireBus *bus, uint8_t *bytes, int number_of_bytes_to_write);
-/** NOTE: Data is read into the high bits, eg. each bit read is shifted down before the next bit is read */
 owb_status (*read_bits)(const OneWireBus *bus, uint8_t *in, int number_of_bits_to_read);
+owb_status (*read_bytes)(const OneWireBus *bus, uint64_t *in, int number_of_bytes_to_read);
 };
+/// @cond ignore
+// note: the new owb_rmt driver uses the ESP-IDF's built-in `__containerof()` macro instead of this
 #define container_of(ptr, type, member) ({                      \
 const typeof( ((type *)0)->member ) *__mptr = (ptr);    \
 (type *)( (char *)__mptr - offsetof(type,member) );})
+/// @endcond
 /**
 * @brief call to release resources after completing use of the OneWireBus
 * @param[in] bus Pointer to initialised bus instance.
 * @return status
 * @return status
 */
 owb_status owb_use_crc(OneWireBus * bus, bool use_crc);
 /**
+* @brief Enable or disable use of parasitic power on the One Wire Bus.
+*        This affects how devices signal on the bus, as devices cannot
+*        signal by pulling the bus low when it is pulled high.
+* @param[in] bus Pointer to initialised bus instance.
+* @param[in] use_parasitic_power True to enable parasitic power, false to disable.
+* @return status
+*/
+owb_status owb_use_parasitic_power(OneWireBus * bus, bool use_parasitic_power);
+/**
+* @brief Enable or disable use of extra GPIO to activate strong pull-up circuit.
+*        This only has effect if parasitic power mode is enabled.
+*        signal by pulling the bus low when it is pulled high.
+* @param[in] bus Pointer to initialised bus instance.
+* @param[in] gpio Set to GPIO number to use, or GPIO_NUM_NC to disable.
+* @return status
+*/
+owb_status owb_use_strong_pullup_gpio(OneWireBus * bus, gpio_num_t gpio);
+/**
 * @brief Read ROM code from device - only works when there is a single device on the bus.
 * @param[in] bus Pointer to initialised bus instance.
 * @param[out] rom_code the value read from the device's rom
 * @return status
 */
-owb_status owb_read_rom(const OneWireBus * bus, OneWireBus_ROMCode *rom_code);
+owb_status owb_read_rom(const OneWireBus * bus, OneWireBus_ROMCode * rom_code);
 /**
 * @brief Verify the device specified by ROM code is present.
 * @param[in] bus Pointer to initialised bus instance.
 * @param[in] rom_code ROM code to verify.
-* @param[out] is_present set to true if a device is present, false if not
+* @param[out] is_present Set to true if a device is present, false if not
 * @return status
 */
-owb_status owb_verify_rom(const OneWireBus * bus, OneWireBus_ROMCode rom_code, bool* is_present);
+owb_status owb_verify_rom(const OneWireBus * bus, OneWireBus_ROMCode rom_code, bool * is_present);
 /**
 * @brief Reset the 1-Wire bus.
 * @param[in] bus Pointer to initialised bus instance.
-* @param[out] a_device_present set to true if at least one device is present on the bus
+* @param[out] is_present set to true if at least one device is present on the bus
 * @return status
 */
-owb_status owb_reset(const OneWireBus * bus, bool* a_device_present);
+owb_status owb_reset(const OneWireBus * bus, bool * is_present);
 /**
-* @brief Write a single byte to the 1-Wire bus.
+* @brief Read a single bit from the 1-Wire bus.
 * @param[in] bus Pointer to initialised bus instance.
-* @param[in] data Byte value to write to bus.
+* @param[out] out The bit value read from the bus.
 * @return status
 */
-owb_status owb_write_byte(const OneWireBus * bus, uint8_t data);
+owb_status owb_read_bit(const OneWireBus * bus, uint8_t * out);
 /**
 * @brief Read a single byte from the 1-Wire bus.
 * @param[in] bus Pointer to initialised bus instance.
-* @param[out] out The byte value read from the bus.
+* @param[out] out The byte value read from the bus (lsb only).
 * @return status
 */
-owb_status owb_read_byte(const OneWireBus * bus, uint8_t *out);
+owb_status owb_read_byte(const OneWireBus * bus, uint8_t * out);
 /**
 * @brief Read a number of bytes from the 1-Wire bus.
 * @param[in] bus Pointer to initialised bus instance.
 * @param[in, out] buffer Pointer to buffer to receive read data.
 * @param[in] len Number of bytes to read, must not exceed length of receive buffer.
 * @return status.
 */
-owb_status owb_read_bytes(const OneWireBus * bus, uint8_t * buffer, size_t len);
+owb_status owb_read_bytes(const OneWireBus * bus, uint8_t * buffer, unsigned int len);
+/**
+* @brief Write a bit to the 1-Wire bus.
+* @param[in] bus Pointer to initialised bus instance.
+* @param[in] bit Value to write (lsb only).
+* @return status
+*/
+owb_status owb_write_bit(const OneWireBus * bus, uint8_t bit);
+/**
+* @brief Write a single byte to the 1-Wire bus.
+* @param[in] bus Pointer to initialised bus instance.
+* @param[in] data Byte value to write to bus.
+* @return status
+*/
+owb_status owb_write_byte(const OneWireBus * bus, uint8_t data);
 /**
 * @brief Write a number of bytes to the 1-Wire bus.
 * @param[in] bus Pointer to initialised bus instance.
 * @param[in] buffer Pointer to buffer to write data from.
 *                See OWB_ROM_CODE_STRING_LENGTH.
 * @return pointer to the byte beyond the last byte written
 */
 char * owb_string_from_rom_code(OneWireBus_ROMCode rom_code, char * buffer, size_t len);
+/**
+* @brief Enable or disable the strong-pullup GPIO, if configured.
+* @param[in] bus Pointer to initialised bus instance.
+* @param[in] enable If true, enable the external strong pull-up by setting the GPIO high.
+*                   If false, disable the external strong pull-up by setting the GPIO low.
+* @return status
+*/
+owb_status owb_set_strong_pullup(const OneWireBus * bus, bool enable);
 #include "owb_gpio.h"
 #include "owb_rmt.h"
 #ifdef __cplusplus
 }

Mercurial > co2meter / file comparison

comparison: components/esp32-owb/include/owb.h

components/esp32-owb/include/owb.h