Mon, 24 Jun 2024 17:09:07 +0200
Added new files and remove obsolete.
0 | 1 | /* |
2 | * MIT License | |
3 | * | |
4 | * Copyright (c) 2017 David Antliff | |
5 | * Copyright (c) 2017 Chris Morgan <chmorgan@gmail.com> | |
6 | * | |
7 | * Permission is hereby granted, free of charge, to any person obtaining a copy | |
8 | * of this software and associated documentation files (the "Software"), to deal | |
9 | * in the Software without restriction, including without limitation the rights | |
10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | |
11 | * copies of the Software, and to permit persons to whom the Software is | |
12 | * furnished to do so, subject to the following conditions: | |
13 | * | |
14 | * The above copyright notice and this permission notice shall be included in all | |
15 | * copies or substantial portions of the Software. | |
16 | * | |
17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | |
18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | |
19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | |
20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | |
21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | |
22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | |
23 | * SOFTWARE. | |
24 | */ | |
25 | ||
26 | /** | |
27 | * @file | |
28 | * @brief Interface definitions for the 1-Wire bus component. | |
29 | * | |
30 | * This component provides structures and functions that are useful for communicating | |
31 | * with devices connected to a Maxim Integrated 1-Wire® bus via a single GPIO. | |
32 | * | |
129 | 33 | * Externally powered and "parasite-powered" devices are supported. |
34 | * Please consult your device's datasheet for power requirements. | |
0 | 35 | */ |
36 | ||
37 | #ifndef ONE_WIRE_BUS_H | |
38 | #define ONE_WIRE_BUS_H | |
39 | ||
40 | #include <stdint.h> | |
41 | #include <stdbool.h> | |
42 | #include <stddef.h> | |
129 | 43 | #include "driver/gpio.h" |
0 | 44 | |
45 | #ifdef __cplusplus | |
46 | extern "C" { | |
47 | #endif | |
48 | ||
49 | ||
50 | // ROM commands | |
129 | 51 | #define OWB_ROM_SEARCH 0xF0 ///< Perform Search ROM cycle to identify devices on the bus |
52 | #define OWB_ROM_READ 0x33 ///< Read device ROM (single device on bus only) | |
53 | #define OWB_ROM_MATCH 0x55 ///< Address a specific device on the bus by ROM | |
54 | #define OWB_ROM_SKIP 0xCC ///< Address all devices on the bus simultaneously | |
55 | #define OWB_ROM_SEARCH_ALARM 0xEC ///< Address all devices on the bus with a set alarm flag | |
0 | 56 | |
57 | #define OWB_ROM_CODE_STRING_LENGTH (17) ///< Typical length of OneWire bus ROM ID as ASCII hex string, including null terminator | |
58 | ||
129 | 59 | #ifndef GPIO_NUM_NC |
60 | # define GPIO_NUM_NC (-1) ///< ESP-IDF prior to v4.x does not define GPIO_NUM_NC | |
61 | #endif | |
62 | ||
0 | 63 | struct owb_driver; |
64 | ||
65 | /** | |
66 | * @brief Structure containing 1-Wire bus information relevant to a single instance. | |
67 | */ | |
68 | typedef struct | |
69 | { | |
70 | const struct _OneWireBus_Timing * timing; ///< Pointer to timing information | |
71 | bool use_crc; ///< True if CRC checks are to be used when retrieving information from a device on the bus | |
129 | 72 | bool use_parasitic_power; ///< True if parasitic-powered devices are expected on the bus |
73 | gpio_num_t strong_pullup_gpio; ///< Set if an external strong pull-up circuit is required | |
74 | const struct owb_driver * driver; ///< Pointer to hardware driver instance | |
0 | 75 | } OneWireBus; |
76 | ||
77 | /** | |
78 | * @brief Represents a 1-Wire ROM Code. This is a sequence of eight bytes, where | |
79 | * the first byte is the family number, then the following 6 bytes form the | |
80 | * serial number. The final byte is the CRC8 check byte. | |
81 | */ | |
82 | typedef union | |
83 | { | |
84 | /// Provides access via field names | |
85 | struct fields | |
86 | { | |
87 | uint8_t family[1]; ///< family identifier (1 byte, LSB - read/write first) | |
88 | uint8_t serial_number[6]; ///< serial number (6 bytes) | |
89 | uint8_t crc[1]; ///< CRC check byte (1 byte, MSB - read/write last) | |
90 | } fields; ///< Provides access via field names | |
91 | ||
92 | uint8_t bytes[8]; ///< Provides raw byte access | |
93 | ||
94 | } OneWireBus_ROMCode; | |
95 | ||
96 | /** | |
97 | * @brief Represents the state of a device search on the 1-Wire bus. | |
98 | * | |
99 | * Pass a pointer to this structure to owb_search_first() and | |
100 | * owb_search_next() to iterate through detected devices on the bus. | |
101 | */ | |
102 | typedef struct | |
103 | { | |
129 | 104 | OneWireBus_ROMCode rom_code; ///< Device ROM code |
105 | int last_discrepancy; ///< Bit index that identifies from which bit the next search discrepancy check should start | |
106 | int last_family_discrepancy; ///< Bit index that identifies the last discrepancy within the first 8-bit family code of the ROM code | |
107 | int last_device_flag; ///< Flag to indicate previous search was the last device detected | |
0 | 108 | } OneWireBus_SearchState; |
109 | ||
29 | 110 | /** |
129 | 111 | * @brief Represents the result of OWB API functions. |
29 | 112 | */ |
0 | 113 | typedef enum |
114 | { | |
129 | 115 | OWB_STATUS_NOT_SET = -1, ///< A status value has not been set |
116 | OWB_STATUS_OK = 0, ///< Operation succeeded | |
117 | OWB_STATUS_NOT_INITIALIZED, ///< Function was passed an uninitialised variable | |
118 | OWB_STATUS_PARAMETER_NULL, ///< Function was passed a null pointer | |
119 | OWB_STATUS_DEVICE_NOT_RESPONDING, ///< No response received from the addressed device or devices | |
120 | OWB_STATUS_CRC_FAILED, ///< CRC failed on data received from a device or devices | |
121 | OWB_STATUS_TOO_MANY_BITS, ///< Attempt to write an incorrect number of bits to the One Wire Bus | |
122 | OWB_STATUS_HW_ERROR ///< A hardware error occurred | |
0 | 123 | } owb_status; |
124 | ||
125 | /** NOTE: Driver assumes that (*init) was called prior to any other methods */ | |
126 | struct owb_driver | |
127 | { | |
128 | const char* name; | |
129 | owb_status (*uninitialize)(const OneWireBus * bus); | |
129 | 130 | owb_status (*reset)(const OneWireBus *bus, bool *is_present); |
0 | 131 | owb_status (*write_bits)(const OneWireBus *bus, uint8_t out, int number_of_bits_to_write); |
129 | 132 | owb_status (*write_bytes)(const OneWireBus *bus, uint8_t *bytes, int number_of_bytes_to_write); |
0 | 133 | owb_status (*read_bits)(const OneWireBus *bus, uint8_t *in, int number_of_bits_to_read); |
129 | 134 | owb_status (*read_bytes)(const OneWireBus *bus, uint64_t *in, int number_of_bytes_to_read); |
0 | 135 | }; |
136 | ||
129 | 137 | /// @cond ignore |
138 | // note: the new owb_rmt driver uses the ESP-IDF's built-in `__containerof()` macro instead of this | |
0 | 139 | #define container_of(ptr, type, member) ({ \ |
140 | const typeof( ((type *)0)->member ) *__mptr = (ptr); \ | |
141 | (type *)( (char *)__mptr - offsetof(type,member) );}) | |
129 | 142 | /// @endcond |
0 | 143 | |
144 | /** | |
145 | * @brief call to release resources after completing use of the OneWireBus | |
29 | 146 | * @param[in] bus Pointer to initialised bus instance. |
147 | * @return status | |
0 | 148 | */ |
149 | owb_status owb_uninitialize(OneWireBus * bus); | |
150 | ||
151 | /** | |
152 | * @brief Enable or disable use of CRC checks on device communications. | |
153 | * @param[in] bus Pointer to initialised bus instance. | |
154 | * @param[in] use_crc True to enable CRC checks, false to disable. | |
155 | * @return status | |
156 | */ | |
157 | owb_status owb_use_crc(OneWireBus * bus, bool use_crc); | |
158 | ||
159 | /** | |
129 | 160 | * @brief Enable or disable use of parasitic power on the One Wire Bus. |
161 | * This affects how devices signal on the bus, as devices cannot | |
162 | * signal by pulling the bus low when it is pulled high. | |
163 | * @param[in] bus Pointer to initialised bus instance. | |
164 | * @param[in] use_parasitic_power True to enable parasitic power, false to disable. | |
165 | * @return status | |
166 | */ | |
167 | owb_status owb_use_parasitic_power(OneWireBus * bus, bool use_parasitic_power); | |
168 | ||
169 | /** | |
170 | * @brief Enable or disable use of extra GPIO to activate strong pull-up circuit. | |
171 | * This only has effect if parasitic power mode is enabled. | |
172 | * signal by pulling the bus low when it is pulled high. | |
173 | * @param[in] bus Pointer to initialised bus instance. | |
174 | * @param[in] gpio Set to GPIO number to use, or GPIO_NUM_NC to disable. | |
175 | * @return status | |
176 | */ | |
177 | owb_status owb_use_strong_pullup_gpio(OneWireBus * bus, gpio_num_t gpio); | |
178 | ||
179 | /** | |
0 | 180 | * @brief Read ROM code from device - only works when there is a single device on the bus. |
181 | * @param[in] bus Pointer to initialised bus instance. | |
182 | * @param[out] rom_code the value read from the device's rom | |
183 | * @return status | |
184 | */ | |
129 | 185 | owb_status owb_read_rom(const OneWireBus * bus, OneWireBus_ROMCode * rom_code); |
0 | 186 | |
187 | /** | |
188 | * @brief Verify the device specified by ROM code is present. | |
189 | * @param[in] bus Pointer to initialised bus instance. | |
190 | * @param[in] rom_code ROM code to verify. | |
129 | 191 | * @param[out] is_present Set to true if a device is present, false if not |
0 | 192 | * @return status |
193 | */ | |
129 | 194 | owb_status owb_verify_rom(const OneWireBus * bus, OneWireBus_ROMCode rom_code, bool * is_present); |
0 | 195 | |
196 | /** | |
197 | * @brief Reset the 1-Wire bus. | |
198 | * @param[in] bus Pointer to initialised bus instance. | |
129 | 199 | * @param[out] is_present set to true if at least one device is present on the bus |
200 | * @return status | |
201 | */ | |
202 | owb_status owb_reset(const OneWireBus * bus, bool * is_present); | |
203 | ||
204 | /** | |
205 | * @brief Read a single bit from the 1-Wire bus. | |
206 | * @param[in] bus Pointer to initialised bus instance. | |
207 | * @param[out] out The bit value read from the bus. | |
208 | * @return status | |
209 | */ | |
210 | owb_status owb_read_bit(const OneWireBus * bus, uint8_t * out); | |
211 | ||
212 | /** | |
213 | * @brief Read a single byte from the 1-Wire bus. | |
214 | * @param[in] bus Pointer to initialised bus instance. | |
215 | * @param[out] out The byte value read from the bus (lsb only). | |
0 | 216 | * @return status |
217 | */ | |
129 | 218 | owb_status owb_read_byte(const OneWireBus * bus, uint8_t * out); |
219 | ||
220 | /** | |
221 | * @brief Read a number of bytes from the 1-Wire bus. | |
222 | * @param[in] bus Pointer to initialised bus instance. | |
223 | * @param[in, out] buffer Pointer to buffer to receive read data. | |
224 | * @param[in] len Number of bytes to read, must not exceed length of receive buffer. | |
225 | * @return status. | |
226 | */ | |
227 | owb_status owb_read_bytes(const OneWireBus * bus, uint8_t * buffer, unsigned int len); | |
228 | ||
229 | /** | |
230 | * @brief Write a bit to the 1-Wire bus. | |
231 | * @param[in] bus Pointer to initialised bus instance. | |
232 | * @param[in] bit Value to write (lsb only). | |
233 | * @return status | |
234 | */ | |
235 | owb_status owb_write_bit(const OneWireBus * bus, uint8_t bit); | |
0 | 236 | |
237 | /** | |
238 | * @brief Write a single byte to the 1-Wire bus. | |
239 | * @param[in] bus Pointer to initialised bus instance. | |
240 | * @param[in] data Byte value to write to bus. | |
241 | * @return status | |
242 | */ | |
243 | owb_status owb_write_byte(const OneWireBus * bus, uint8_t data); | |
244 | ||
245 | /** | |
246 | * @brief Write a number of bytes to the 1-Wire bus. | |
247 | * @param[in] bus Pointer to initialised bus instance. | |
248 | * @param[in] buffer Pointer to buffer to write data from. | |
249 | * @param[in] len Number of bytes to write. | |
250 | * @return status | |
251 | */ | |
252 | owb_status owb_write_bytes(const OneWireBus * bus, const uint8_t * buffer, size_t len); | |
253 | ||
254 | /** | |
255 | * @brief Write a ROM code to the 1-Wire bus ensuring LSB is sent first. | |
256 | * @param[in] bus Pointer to initialised bus instance. | |
257 | * @param[in] rom_code ROM code to write to bus. | |
258 | * @return status | |
259 | */ | |
260 | owb_status owb_write_rom_code(const OneWireBus * bus, OneWireBus_ROMCode rom_code); | |
261 | ||
262 | /** | |
263 | * @brief 1-Wire 8-bit CRC lookup. | |
264 | * @param[in] crc Starting CRC value. Pass in prior CRC to accumulate. | |
265 | * @param[in] data Byte to feed into CRC. | |
266 | * @return Resultant CRC value. | |
267 | * Should be zero if last byte was the CRC byte and the CRC matches. | |
268 | */ | |
269 | uint8_t owb_crc8_byte(uint8_t crc, uint8_t data); | |
270 | ||
271 | /** | |
272 | * @brief 1-Wire 8-bit CRC lookup with accumulation over a block of bytes. | |
273 | * @param[in] crc Starting CRC value. Pass in prior CRC to accumulate. | |
274 | * @param[in] data Array of bytes to feed into CRC. | |
275 | * @param[in] len Length of data array in bytes. | |
276 | * @return Resultant CRC value. | |
277 | * Should be zero if last byte was the CRC byte and the CRC matches. | |
278 | */ | |
279 | uint8_t owb_crc8_bytes(uint8_t crc, const uint8_t * data, size_t len); | |
280 | ||
281 | /** | |
282 | * @brief Locates the first device on the 1-Wire bus, if present. | |
283 | * @param[in] bus Pointer to initialised bus instance. | |
284 | * @param[in,out] state Pointer to an existing search state structure. | |
285 | * @param[out] found_device True if a device is found, false if no devices are found. | |
286 | * If a device is found, the ROM Code can be obtained from the state. | |
287 | * @return status | |
288 | */ | |
289 | owb_status owb_search_first(const OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device); | |
290 | ||
291 | /** | |
292 | * @brief Locates the next device on the 1-Wire bus, if present, starting from | |
293 | * the provided state. Further calls will yield additional devices, if present. | |
294 | * @param[in] bus Pointer to initialised bus instance. | |
295 | * @param[in,out] state Pointer to an existing search state structure. | |
296 | * @param[out] found_device True if a device is found, false if no devices are found. | |
297 | * If a device is found, the ROM Code can be obtained from the state. | |
298 | * @return status | |
299 | */ | |
300 | owb_status owb_search_next(const OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device); | |
301 | ||
302 | /** | |
303 | * @brief Create a string representation of a ROM code, most significant byte (CRC8) first. | |
304 | * @param[in] rom_code The ROM code to convert to string representation. | |
305 | * @param[out] buffer The destination for the string representation. It will be null terminated. | |
306 | * @param[in] len The length of the buffer in bytes. 64-bit ROM codes require 16 characters | |
307 | * to represent as a string, plus a null terminator, for 17 bytes. | |
308 | * See OWB_ROM_CODE_STRING_LENGTH. | |
309 | * @return pointer to the byte beyond the last byte written | |
310 | */ | |
311 | char * owb_string_from_rom_code(OneWireBus_ROMCode rom_code, char * buffer, size_t len); | |
312 | ||
129 | 313 | /** |
314 | * @brief Enable or disable the strong-pullup GPIO, if configured. | |
315 | * @param[in] bus Pointer to initialised bus instance. | |
316 | * @param[in] enable If true, enable the external strong pull-up by setting the GPIO high. | |
317 | * If false, disable the external strong pull-up by setting the GPIO low. | |
318 | * @return status | |
319 | */ | |
320 | owb_status owb_set_strong_pullup(const OneWireBus * bus, bool enable); | |
321 | ||
322 | ||
0 | 323 | #include "owb_gpio.h" |
324 | #include "owb_rmt.h" | |
325 | ||
326 | #ifdef __cplusplus | |
327 | } | |
328 | #endif | |
329 | ||
330 | #endif // ONE_WIRE_BUS_H |