1 /** 2 * @file owm.h 3 * @brief Registers, Bit Masks and Bit Positions for the 1-Wire Master 4 * peripheral module. 5 */ 6 7 /****************************************************************************** 8 * 9 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 10 * Analog Devices, Inc.), 11 * Copyright (C) 2023-2024 Analog Devices, Inc. 12 * 13 * Licensed under the Apache License, Version 2.0 (the "License"); 14 * you may not use this file except in compliance with the License. 15 * You may obtain a copy of the License at 16 * 17 * http://www.apache.org/licenses/LICENSE-2.0 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an "AS IS" BASIS, 21 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 * 25 ******************************************************************************/ 26 27 /* Define to prevent redundant inclusion */ 28 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_OWM_H_ 29 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_OWM_H_ 30 31 /* **** Includes **** */ 32 #include "mxc_device.h" 33 #include "mxc_sys.h" 34 #include "owm_regs.h" 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * @ingroup periphlibs 42 * @defgroup owm 1-Wire Master (OWM) 43 * @{ 44 */ 45 46 /* **** Definitions **** */ 47 48 /** 49 * @brief Enumeration type for specifying options for 1-Wire external pullup mode. 50 */ 51 typedef enum { 52 MXC_OWM_EXT_PU_ACT_HIGH = 0, /**< Pullup pin is active high when enabled. */ 53 MXC_OWM_EXT_PU_ACT_LOW = 1, /**< Pullup pin is active low when enabled. */ 54 MXC_OWM_EXT_PU_UNUSED = 2, /**< Pullup pin is not used for an external pullup. */ 55 } mxc_owm_ext_pu_t; 56 57 /** 58 * @brief Structure type for 1-Wire Master configuration. 59 */ 60 typedef struct { 61 uint8_t int_pu_en; /**< 1 = internal pullup on. */ 62 mxc_owm_ext_pu_t ext_pu_mode; /**< See #mxc_owm_ext_pu_t. */ 63 uint8_t long_line_mode; /**< 1 = long line mode enable. */ 64 // mxc_owm_overdrive_t overdrive_spec; /**< 0 = timeslot is 12us, 1 = timeslot is 10us. */ 65 } mxc_owm_cfg_t; 66 67 #define READ_ROM_COMMAND 0x33 /**< Read ROM Command */ 68 #define MATCH_ROM_COMMAND 0x55 /**< Match ROM Command */ 69 #define SEARCH_ROM_COMMAND 0xF0 /**< Search ROM Command */ 70 #define SKIP_ROM_COMMAND 0xCC /**< Skip ROM Command */ 71 #define OD_SKIP_ROM_COMMAND 0x3C /**< Overdrive Skip ROM Command */ 72 #define OD_MATCH_ROM_COMMAND 0x69 /**< Overdrive Match ROM Command */ 73 #define RESUME_COMMAND 0xA5 /**< Resume Command */ 74 75 /* **** Globals **** */ 76 77 /* **** Function Prototypes **** */ 78 79 /** 80 * @brief Initialize and enable OWM module. 81 * @param cfg Pointer to OWM configuration. 82 * @param map MAP_A, MAP_B or MAP_C onewire pins select. Has no effect 83 * incase of MSDK_NO_GPIO_CLK_INIT has been defined. 84 * 85 * @return #E_NO_ERROR if everything is successful 86 * @return #E_NULL_PTR if parameter is a null pointer 87 * @return #E_BUSY if IOMAN was not configured correctly 88 * @return #E_UNINITIALIZED if OWM CLK disabled 89 * @return #E_NOT_SUPPORTED if 1MHz CLK cannot be created with given system and owm CLK 90 * @return #E_BAD_PARAM if bad cfg parameter passed in 91 */ 92 int MXC_OWM_Init(const mxc_owm_cfg_t *cfg, sys_map_t map); 93 94 /** 95 * @brief Shutdown OWM module. 96 * 97 */ 98 void MXC_OWM_Shutdown(void); 99 100 /** 101 * @brief Send 1-Wire reset pulse. Will block until transaction is complete. 102 * 103 * @return 0 if no 1-wire devices reponded during the presence pulse, 1 otherwise 104 */ 105 int MXC_OWM_Reset(void); 106 107 /** 108 * @brief Get the presence pulse detect status. 109 * 110 * @return 0 if no 1-wire devices reponded during the presence pulse, 1 otherwise 111 */ 112 int MXC_OWM_GetPresenceDetect(void); 113 114 /** 115 * @brief Send and receive one byte of data. Will block until transaction is complete. 116 * 117 * @param data data to send 118 * 119 * @return data read (1 byte) 120 */ 121 int MXC_OWM_TouchByte(uint8_t data); 122 123 /** 124 * @brief Write one byte of data. Will block until transaction is complete. 125 * 126 * @param data data to send 127 * 128 * @return #E_NO_ERROR if everything is successful 129 * @return #E_COMM_ERR if data written != data parameter 130 */ 131 int MXC_OWM_WriteByte(uint8_t data); 132 133 /** 134 * @brief Read one byte of data. Will block until transaction is complete. 135 * 136 * @return data read (1 byte) 137 */ 138 int MXC_OWM_ReadByte(void); 139 140 /** 141 * @brief Send and receive one bit of data. Will block until transaction is complete. 142 * 143 * @param bit bit to send 144 * 145 * @return bit read 146 */ 147 int MXC_OWM_TouchBit(uint8_t bit); 148 149 /** 150 * @brief Write one bit of data. Will block until transaction is complete. 151 * 152 * @param bit bit to send 153 * 154 * @return #E_NO_ERROR if everything is successful 155 * @return #E_COMM_ERR if bit written != bit parameter 156 */ 157 int MXC_OWM_WriteBit(uint8_t bit); 158 159 /** 160 * @brief Read one bit of data. Will block until transaction is complete. 161 * 162 * @return bit read 163 */ 164 int MXC_OWM_ReadBit(void); 165 166 /** 167 * @brief Write multiple bytes of data. Will block until transaction is complete. 168 * 169 * @param data Pointer to buffer for write data. 170 * @param len Number of bytes to write. 171 * 172 * @return Number of bytes written if successful 173 * @return #E_COMM_ERR if line short detected before transaction 174 */ 175 int MXC_OWM_Write(uint8_t *data, int len); 176 177 /** 178 * @brief Read multiple bytes of data. Will block until transaction is complete. 179 * 180 * @param data Pointer to buffer for read data. 181 * @param len Number of bytes to read. 182 * 183 * @return Number of bytes read if successful 184 * @return #E_COMM_ERR if line short detected before transaction 185 */ 186 int MXC_OWM_Read(uint8_t *data, int len); 187 188 /** 189 * @brief Starts 1-Wire communication with Read ROM command 190 * @note Only use the Read ROM command with one slave on the bus 191 * 192 * @param ROMCode Pointer to buffer for ROM code read 193 * 194 * @return #E_NO_ERROR if everything is successful 195 * @return #E_COMM_ERR if reset, read or write fails 196 */ 197 int MXC_OWM_ReadROM(uint8_t *ROMCode); 198 199 /** 200 * @brief Starts 1-Wire communication with Match ROM command 201 * 202 * @param ROMCode Pointer to buffer with ROM code to match 203 * 204 * @return #E_NO_ERROR if everything is successful 205 * @return #E_COMM_ERR if reset or write fails 206 */ 207 int MXC_OWM_MatchROM(uint8_t *ROMCode); 208 209 /** 210 * @brief Starts 1-Wire communication with Overdrive Match ROM command 211 * @note After Overdrive Match ROM command is sent, the OWM is set to 212 * overdrive speed. To set back to standard speed use MXC_OWM_SetOverdrive. 213 * 214 * @param ROMCode Pointer to buffer with ROM code to match 215 * 216 * @return #E_NO_ERROR if everything is successful 217 * @return #E_COMM_ERR if reset or write fails 218 */ 219 int MXC_OWM_ODMatchROM(uint8_t *ROMCode); 220 221 /** 222 * @brief Starts 1-Wire communication with Skip ROM command 223 * 224 * @return #E_NO_ERROR if everything is successful 225 * @return #E_COMM_ERR if reset or write fails 226 */ 227 int MXC_OWM_SkipROM(void); 228 229 /** 230 * @brief Starts 1-Wire communication with Overdrive Skip ROM command 231 * @note After Overdrive Skip ROM command is sent, the OWM is set to 232 * overdrive speed. To set back to standard speed use MXC_OWM_SetOverdrive 233 * 234 * @return #E_NO_ERROR if everything is successful 235 * @return #E_COMM_ERR if reset or write fails 236 */ 237 int MXC_OWM_ODSkipROM(void); 238 239 /** 240 * @brief Starts 1-Wire communication with Resume command 241 * 242 * @return #E_NO_ERROR if everything is successful 243 * @return #E_COMM_ERR if reset or write fails 244 */ 245 int MXC_OWM_Resume(void); 246 247 /** 248 * @brief Starts 1-Wire communication with Search ROM command 249 * 250 * @param newSearch (1) = start new search, (0) = continue search for next ROM 251 * @param ROMCode Pointer to buffer with ROM code found 252 * 253 * @return (1) = ROM found, (0) = no new ROM found, end of search 254 */ 255 int MXC_OWM_SearchROM(int newSearch, uint8_t *ROMCode); 256 257 /** 258 * @brief Clear interrupt flags. 259 * 260 * @param mask Mask of interrupts to clear. 261 */ 262 void MXC_OWM_ClearFlags(uint32_t mask); 263 264 /** 265 * @brief Get interrupt flags. 266 * 267 * @return Mask of active flags. 268 */ 269 unsigned MXC_OWM_GetFlags(void); 270 271 /** 272 * @brief Enables/Disables the External pullup 273 * 274 * @param enable (1) = enable, (0) = disable 275 */ 276 void MXC_OWM_SetExtPullup(int enable); 277 278 /** 279 * @brief Enables/Disables Overdrive speed 280 * 281 * @param enable (1) = overdrive, (0) = standard 282 */ 283 void MXC_OWM_SetOverdrive(int enable); 284 285 /** 286 * @brief Enables interrupts 287 * 288 * @param flags which owm interrupts to enable 289 */ 290 void MXC_OWM_EnableInt(int flags); 291 292 /** 293 * @brief Disables interrupts 294 * 295 * @param flags which owm interrupts to disable 296 */ 297 void MXC_OWM_DisableInt(int flags); 298 299 /** 300 * @brief Enables/Disables driving of OWM_IO low during presence detection 301 * 302 * @param enable (1) = enable, (0) = disable 303 * 304 * @return See \ref MXC_Error_Codes for a list of return codes. 305 */ 306 int MXC_OWM_SetForcePresenceDetect(int enable); 307 308 /** 309 * @brief Enables/Disables the Internal pullup 310 * 311 * @param enable (1) = enable, (0) = disable 312 * 313 * @return See \ref MXC_Error_Codes for a list of return codes. 314 */ 315 int MXC_OWM_SetInternalPullup(int enable); 316 317 /** 318 * @brief Enables/Disables the External pullup 319 * 320 * @param ext_pu_mode See mxc_owm_ext_pu_t for values 321 * 322 * @return See \ref MXC_Error_Codes for a list of return codes. 323 */ 324 int MXC_OWM_SetExternalPullup(mxc_owm_ext_pu_t ext_pu_mode); 325 326 /** 327 * @brief Call to correct divider if system clock has changed 328 * 329 * @return See \ref MXC_Error_Codes for a list of return codes. 330 */ 331 int MXC_OWM_SystemClockUpdated(void); 332 333 /** 334 * @brief Enable/Disable Search ROM Accelerator mode 335 * 336 * @param enable (1) = enable, (0) = disable 337 * 338 * @return See \ref MXC_Error_Codes for a list of return codes. 339 */ 340 int MXC_OWM_SetSearchROMAccelerator(int enable); 341 342 /** 343 * @brief Prepare OWM for bit bang mode 344 * 345 * @param initialState Starting value of owm 346 * 347 * @return See \ref MXC_Error_Codes for a list of return codes. 348 */ 349 int MXC_OWM_BitBang_Init(int initialState); 350 351 /** 352 * @brief Read current value of wire 353 * 354 * @return Value of wire 355 */ 356 int MXC_OWM_BitBang_Read(void); 357 358 /** 359 * @brief Set value of wire 360 * 361 * @param state Value to drive wire to 362 * 363 * @return See \ref MXC_Error_Codes for a list of return codes. 364 */ 365 int MXC_OWM_BitBang_Write(int state); 366 367 /** 368 * @brief Disable Bit Bang mode 369 * 370 * @return See \ref MXC_Error_Codes for a list of return codes. 371 */ 372 int MXC_OWM_BitBang_Disable(void); 373 374 /**@} end of group owm */ 375 #ifdef __cplusplus 376 } 377 #endif 378 379 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32570_OWM_H_ 380
