--- a/components/esp32-owb/include/owb.h Tue Sep 26 14:56:04 2023 +0200
+++ b/components/esp32-owb/include/owb.h Tue Sep 26 14:57:18 2023 +0200
@@ -30,7 +30,8 @@
* 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
@@ -39,6 +40,7 @@
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
+#include "driver/gpio.h"
#ifdef __cplusplus
extern "C" {
@@ -46,14 +48,18 @@
// ROM commands
-#define OWB_ROM_SEARCH 0xF0 ///< Command ROM search
-#define OWB_ROM_READ 0x33 ///< ROM read
-#define OWB_ROM_MATCH 0x55 ///< ROM address match
-#define OWB_ROM_SKIP 0xCC ///< Skip device
-#define OWB_ROM_SEARCH_ALARM 0xEC ///< Search device with alarm set
+#define OWB_ROM_SEARCH 0xF0 ///< Perform Search ROM cycle to identify devices on the bus
+#define OWB_ROM_READ 0x33 ///< Read device ROM (single device on bus only)
+#define OWB_ROM_MATCH 0x55 ///< Address a specific device on the bus by ROM
+#define OWB_ROM_SKIP 0xCC ///< Address all devices on the bus simultaneously
+#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;
/**
@@ -63,8 +69,9 @@
{
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
-
- const struct owb_driver *driver;
+ bool use_parasitic_power; ///< True if parasitic-powered devices are expected on the bus
+ 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;
/**
@@ -94,45 +101,45 @@
*/
typedef struct
{
- OneWireBus_ROMCode rom_code;
- int last_discrepancy;
- int last_family_discrepancy;
- int last_device_flag;
+ OneWireBus_ROMCode rom_code; ///< Device ROM code
+ int last_discrepancy; ///< Bit index that identifies from which bit the next search discrepancy check should start
+ 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; ///< 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_INITIALIZED, ///< Init error
- OWB_STATUS_PARAMETER_NULL, ///< NULL parameter
- OWB_STATUS_DEVICE_NOT_RESPONDING, ///< Device does not respond
- OWB_STATUS_CRC_FAILED, ///< CRC error
- OWB_STATUS_TOO_MANY_BITS, ///< Too many bits
- OWB_STATUS_HW_ERROR ///< Hardware error
+ OWB_STATUS_NOT_SET = -1, ///< A status value has not been set
+ OWB_STATUS_OK = 0, ///< Operation succeeded
+ OWB_STATUS_NOT_INITIALIZED, ///< Function was passed an uninitialised variable
+ OWB_STATUS_PARAMETER_NULL, ///< Function was passed a null pointer
+ OWB_STATUS_DEVICE_NOT_RESPONDING, ///< No response received from the addressed device or devices
+ OWB_STATUS_CRC_FAILED, ///< CRC failed on data received from a device or devices
+ 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);
-
- /** NOTE: The data is shifted out of the low bits, eg. it is written in the order of lsb to msb */
+ owb_status (*reset)(const OneWireBus *bus, bool *is_present);
owb_status (*write_bits)(const OneWireBus *bus, uint8_t out, int number_of_bits_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 (*write_bytes)(const OneWireBus *bus, uint8_t *bytes, int number_of_bytes_to_write);
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
@@ -150,29 +157,82 @@
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 * is_present);
+
+/**
+ * @brief Read a single bit from the 1-Wire bus.
+ * @param[in] bus Pointer to initialised bus instance.
+ * @param[out] out The bit value read from the bus.
+ * @return status
+ */
+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 (lsb only).
* @return status
*/
-owb_status owb_reset(const OneWireBus * bus, bool* a_device_present);
+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, 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.
@@ -183,23 +243,6 @@
owb_status owb_write_byte(const OneWireBus * bus, uint8_t data);
/**
- * @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.
- * @return status
- */
-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);
-
-/**
* @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.
@@ -267,6 +310,16 @@
*/
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"
