Mercurial > brewboard / file comparison

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

components/esp32-owb/include/owb.h

changeset 0
b74b0e4902c3
child 29
45647136ec95
equal deleted inserted replaced
-1:000000000000 0:b74b0e4902c3
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 *
33 * Currently only externally powered devices are supported. Parasitic power is not supported.
34 */
35
36 #ifndef ONE_WIRE_BUS_H
37 #define ONE_WIRE_BUS_H
38
39 #include <stdint.h>
40 #include <stdbool.h>
41 #include <stddef.h>
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47
48 // ROM commands
49 #define OWB_ROM_SEARCH 0xF0
50 #define OWB_ROM_READ 0x33
51 #define OWB_ROM_MATCH 0x55
52 #define OWB_ROM_SKIP 0xCC
53 #define OWB_ROM_SEARCH_ALARM 0xEC
54
55 #define OWB_ROM_CODE_STRING_LENGTH (17) ///< Typical length of OneWire bus ROM ID as ASCII hex string, including null terminator
56
57 struct owb_driver;
58
59 /**
60 * @brief Structure containing 1-Wire bus information relevant to a single instance.
61 */
62 typedef struct
63 {
64 const struct _OneWireBus_Timing * timing; ///< Pointer to timing information
65 bool use_crc; ///< True if CRC checks are to be used when retrieving information from a device on the bus
66
67 const struct owb_driver *driver;
68 } OneWireBus;
69
70 /**
71 * @brief Represents a 1-Wire ROM Code. This is a sequence of eight bytes, where
72 * the first byte is the family number, then the following 6 bytes form the
73 * serial number. The final byte is the CRC8 check byte.
74 */
75 typedef union
76 {
77 /// Provides access via field names
78 struct fields
79 {
80 uint8_t family[1]; ///< family identifier (1 byte, LSB - read/write first)
81 uint8_t serial_number[6]; ///< serial number (6 bytes)
82 uint8_t crc[1]; ///< CRC check byte (1 byte, MSB - read/write last)
83 } fields; ///< Provides access via field names
84
85 uint8_t bytes[8]; ///< Provides raw byte access
86
87 } OneWireBus_ROMCode;
88
89 /**
90 * @brief Represents the state of a device search on the 1-Wire bus.
91 *
92 * Pass a pointer to this structure to owb_search_first() and
93 * owb_search_next() to iterate through detected devices on the bus.
94 */
95 typedef struct
96 {
97 OneWireBus_ROMCode rom_code;
98 int last_discrepancy;
99 int last_family_discrepancy;
100 int last_device_flag;
101 } OneWireBus_SearchState;
102
103 typedef enum
104 {
105 OWB_STATUS_OK,
106 OWB_STATUS_NOT_INITIALIZED,
107 OWB_STATUS_PARAMETER_NULL,
108 OWB_STATUS_DEVICE_NOT_RESPONDING,
109 OWB_STATUS_CRC_FAILED,
110 OWB_STATUS_TOO_MANY_BITS,
111 OWB_STATUS_HW_ERROR
112 } owb_status;
113
114 /** NOTE: Driver assumes that (*init) was called prior to any other methods */
115 struct owb_driver
116 {
117 const char* name;
118
119 owb_status (*uninitialize)(const OneWireBus * bus);
120
121 owb_status (*reset)(const OneWireBus * bus, bool *is_present);
122
123 /** NOTE: The data is shifted out of the low bits, eg. it is written in the order of lsb to msb */
124 owb_status (*write_bits)(const OneWireBus *bus, uint8_t out, int number_of_bits_to_write);
125
126 /** NOTE: Data is read into the high bits, eg. each bit read is shifted down before the next bit is read */
127 owb_status (*read_bits)(const OneWireBus *bus, uint8_t *in, int number_of_bits_to_read);
128 };
129
130 #define container_of(ptr, type, member) ({ \
131 const typeof( ((type *)0)->member ) *__mptr = (ptr); \
132 (type *)( (char *)__mptr - offsetof(type,member) );})
133
134 /**
135 * @brief call to release resources after completing use of the OneWireBus
136 */
137 owb_status owb_uninitialize(OneWireBus * bus);
138
139 /**
140 * @brief Enable or disable use of CRC checks on device communications.
141 * @param[in] bus Pointer to initialised bus instance.
142 * @param[in] use_crc True to enable CRC checks, false to disable.
143 * @return status
144 */
145 owb_status owb_use_crc(OneWireBus * bus, bool use_crc);
146
147 /**
148 * @brief Read ROM code from device - only works when there is a single device on the bus.
149 * @param[in] bus Pointer to initialised bus instance.
150 * @param[out] rom_code the value read from the device's rom
151 * @return status
152 */
153 owb_status owb_read_rom(const OneWireBus * bus, OneWireBus_ROMCode *rom_code);
154
155 /**
156 * @brief Verify the device specified by ROM code is present.
157 * @param[in] bus Pointer to initialised bus instance.
158 * @param[in] rom_code ROM code to verify.
159 * @param[out] is_present set to true if a device is present, false if not
160 * @return status
161 */
162 owb_status owb_verify_rom(const OneWireBus * bus, OneWireBus_ROMCode rom_code, bool* is_present);
163
164 /**
165 * @brief Reset the 1-Wire bus.
166 * @param[in] bus Pointer to initialised bus instance.
167 * @param[out] is_present set to true if at least one device is present on the bus
168 * @return status
169 */
170 owb_status owb_reset(const OneWireBus * bus, bool* a_device_present);
171
172 /**
173 * @brief Write a single byte to the 1-Wire bus.
174 * @param[in] bus Pointer to initialised bus instance.
175 * @param[in] data Byte value to write to bus.
176 * @return status
177 */
178 owb_status owb_write_byte(const OneWireBus * bus, uint8_t data);
179
180 /**
181 * @brief Read a single byte from the 1-Wire bus.
182 * @param[in] bus Pointer to initialised bus instance.
183 * @param[out] out The byte value read from the bus.
184 * @return status
185 */
186 owb_status owb_read_byte(const OneWireBus * bus, uint8_t *out);
187
188 /**
189 * @brief Read a number of bytes from the 1-Wire bus.
190 * @param[in] bus Pointer to initialised bus instance.
191 * @param[in, out] buffer Pointer to buffer to receive read data.
192 * @param[in] len Number of bytes to read, must not exceed length of receive buffer.
193 * @return status.
194 */
195 owb_status owb_read_bytes(const OneWireBus * bus, uint8_t * buffer, size_t len);
196
197 /**
198 * @brief Write a number of bytes to the 1-Wire bus.
199 * @param[in] bus Pointer to initialised bus instance.
200 * @param[in] buffer Pointer to buffer to write data from.
201 * @param[in] len Number of bytes to write.
202 * @return status
203 */
204 owb_status owb_write_bytes(const OneWireBus * bus, const uint8_t * buffer, size_t len);
205
206 /**
207 * @brief Write a ROM code to the 1-Wire bus ensuring LSB is sent first.
208 * @param[in] bus Pointer to initialised bus instance.
209 * @param[in] rom_code ROM code to write to bus.
210 * @return status
211 */
212 owb_status owb_write_rom_code(const OneWireBus * bus, OneWireBus_ROMCode rom_code);
213
214 /**
215 * @brief 1-Wire 8-bit CRC lookup.
216 * @param[in] crc Starting CRC value. Pass in prior CRC to accumulate.
217 * @param[in] data Byte to feed into CRC.
218 * @return Resultant CRC value.
219 * Should be zero if last byte was the CRC byte and the CRC matches.
220 */
221 uint8_t owb_crc8_byte(uint8_t crc, uint8_t data);
222
223 /**
224 * @brief 1-Wire 8-bit CRC lookup with accumulation over a block of bytes.
225 * @param[in] crc Starting CRC value. Pass in prior CRC to accumulate.
226 * @param[in] data Array of bytes to feed into CRC.
227 * @param[in] len Length of data array in bytes.
228 * @return Resultant CRC value.
229 * Should be zero if last byte was the CRC byte and the CRC matches.
230 */
231 uint8_t owb_crc8_bytes(uint8_t crc, const uint8_t * data, size_t len);
232
233 /**
234 * @brief Locates the first device on the 1-Wire bus, if present.
235 * @param[in] bus Pointer to initialised bus instance.
236 * @param[in,out] state Pointer to an existing search state structure.
237 * @param[out] found_device True if a device is found, false if no devices are found.
238 * If a device is found, the ROM Code can be obtained from the state.
239 * @return status
240 */
241 owb_status owb_search_first(const OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device);
242
243 /**
244 * @brief Locates the next device on the 1-Wire bus, if present, starting from
245 * the provided state. Further calls will yield additional devices, if present.
246 * @param[in] bus Pointer to initialised bus instance.
247 * @param[in,out] state Pointer to an existing search state structure.
248 * @param[out] found_device True if a device is found, false if no devices are found.
249 * If a device is found, the ROM Code can be obtained from the state.
250 * @return status
251 */
252 owb_status owb_search_next(const OneWireBus * bus, OneWireBus_SearchState * state, bool *found_device);
253
254 /**
255 * @brief Create a string representation of a ROM code, most significant byte (CRC8) first.
256 * @param[in] rom_code The ROM code to convert to string representation.
257 * @param[out] buffer The destination for the string representation. It will be null terminated.
258 * @param[in] len The length of the buffer in bytes. 64-bit ROM codes require 16 characters
259 * to represent as a string, plus a null terminator, for 17 bytes.
260 * See OWB_ROM_CODE_STRING_LENGTH.
261 * @return pointer to the byte beyond the last byte written
262 */
263 char * owb_string_from_rom_code(OneWireBus_ROMCode rom_code, char * buffer, size_t len);
264
265 #include "owb_gpio.h"
266 #include "owb_rmt.h"
267
268 #ifdef __cplusplus
269 }
270 #endif
271
272 #endif // ONE_WIRE_BUS_H

Mercurial Repository: brewboard

mercurial