Mike Fruge / OneWire

Implementation of 1-Wire with added Alarm Search Functionality

Dependents:   Max32630_One_Wire_Interface

Masters/OneWireMaster.h@77:529edb329ee0, 2016-05-16 (annotated)

Committer:
IanBenzMaxim
Date:
Mon May 16 10:36:30 2016 -0500
Revision:
77:529edb329ee0
Parent:
76:84e6c4994e29
Child:
78:0cbbac7f2016
Added iterators for selecting 1-Wire devices on the bus and added support iterator support to OneWireSlave class.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
j3 5:ce108eeb878d 1 /******************************************************************//**
j3 5:ce108eeb878d 2 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
j3 5:ce108eeb878d 3 *
j3 5:ce108eeb878d 4 * Permission is hereby granted, free of charge, to any person obtaining a
j3 5:ce108eeb878d 5 * copy of this software and associated documentation files (the "Software"),
j3 5:ce108eeb878d 6 * to deal in the Software without restriction, including without limitation
j3 5:ce108eeb878d 7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
j3 5:ce108eeb878d 8 * and/or sell copies of the Software, and to permit persons to whom the
j3 5:ce108eeb878d 9 * Software is furnished to do so, subject to the following conditions:
j3 5:ce108eeb878d 10 *
j3 5:ce108eeb878d 11 * The above copyright notice and this permission notice shall be included
j3 5:ce108eeb878d 12 * in all copies or substantial portions of the Software.
j3 5:ce108eeb878d 13 *
j3 5:ce108eeb878d 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
j3 5:ce108eeb878d 15 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
j3 5:ce108eeb878d 16 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
j3 5:ce108eeb878d 17 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
j3 5:ce108eeb878d 18 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
j3 5:ce108eeb878d 19 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
j3 5:ce108eeb878d 20 * OTHER DEALINGS IN THE SOFTWARE.
j3 5:ce108eeb878d 21 *
j3 5:ce108eeb878d 22 * Except as contained in this notice, the name of Maxim Integrated
j3 5:ce108eeb878d 23 * Products, Inc. shall not be used except as stated in the Maxim Integrated
j3 5:ce108eeb878d 24 * Products, Inc. Branding Policy.
j3 5:ce108eeb878d 25 *
j3 5:ce108eeb878d 26 * The mere transfer of this software does not imply any licenses
j3 5:ce108eeb878d 27 * of trade secrets, proprietary technology, copyrights, patents,
j3 5:ce108eeb878d 28 * trademarks, maskwork rights, or any other form of intellectual
j3 5:ce108eeb878d 29 * property whatsoever. Maxim Integrated Products, Inc. retains all
j3 5:ce108eeb878d 30 * ownership rights.
j3 5:ce108eeb878d 31 **********************************************************************/
j3 5:ce108eeb878d 32
IanBenzMaxim 73:2cecc1372acc 33 #ifndef OneWire_Masters_OneWireMaster
IanBenzMaxim 73:2cecc1372acc 34 #define OneWire_Masters_OneWireMaster
j3 5:ce108eeb878d 35
IanBenzMaxim 73:2cecc1372acc 36 #include <stdint.h>
IanBenzMaxim 73:2cecc1372acc 37 #include <stddef.h>
IanBenzMaxim 73:2cecc1372acc 38 #include "RomId.h"
IanBenzMaxim 73:2cecc1372acc 39
IanBenzMaxim 73:2cecc1372acc 40 namespace OneWire
IanBenzMaxim 73:2cecc1372acc 41 {
IanBenzMaxim 76:84e6c4994e29 42 /// Base class for all 1-Wire Masters.
IanBenzMaxim 76:84e6c4994e29 43 class OneWireMaster
IanBenzMaxim 32:bce180b544ed 44 {
IanBenzMaxim 76:84e6c4994e29 45 public:
IanBenzMaxim 76:84e6c4994e29 46 /// Speed of the 1-Wire bus
IanBenzMaxim 76:84e6c4994e29 47 enum OWSpeed
IanBenzMaxim 74:23be10c32fa3 48 {
IanBenzMaxim 76:84e6c4994e29 49 StandardSpeed = 0x00,
IanBenzMaxim 76:84e6c4994e29 50 OverdriveSpeed = 0x01
IanBenzMaxim 76:84e6c4994e29 51 };
IanBenzMaxim 74:23be10c32fa3 52
IanBenzMaxim 76:84e6c4994e29 53 /// Level of the 1-Wire bus
IanBenzMaxim 76:84e6c4994e29 54 enum OWLevel
IanBenzMaxim 76:84e6c4994e29 55 {
IanBenzMaxim 76:84e6c4994e29 56 NormalLevel = 0x00,
IanBenzMaxim 76:84e6c4994e29 57 StrongLevel = 0x02
IanBenzMaxim 76:84e6c4994e29 58 };
IanBenzMaxim 74:23be10c32fa3 59
IanBenzMaxim 76:84e6c4994e29 60 /// Search direction for the Triplet
IanBenzMaxim 76:84e6c4994e29 61 enum SearchDirection
IanBenzMaxim 76:84e6c4994e29 62 {
IanBenzMaxim 76:84e6c4994e29 63 WriteZero = 0,
IanBenzMaxim 76:84e6c4994e29 64 WriteOne = 1
IanBenzMaxim 76:84e6c4994e29 65 };
IanBenzMaxim 74:23be10c32fa3 66
IanBenzMaxim 76:84e6c4994e29 67 /// Result of all 1-Wire commands
IanBenzMaxim 76:84e6c4994e29 68 enum CmdResult
IanBenzMaxim 76:84e6c4994e29 69 {
IanBenzMaxim 76:84e6c4994e29 70 Success,
IanBenzMaxim 76:84e6c4994e29 71 CommunicationWriteError,
IanBenzMaxim 76:84e6c4994e29 72 CommunicationReadError,
IanBenzMaxim 76:84e6c4994e29 73 TimeoutError,
IanBenzMaxim 76:84e6c4994e29 74 OperationFailure
IanBenzMaxim 76:84e6c4994e29 75 };
IanBenzMaxim 77:529edb329ee0 76
IanBenzMaxim 77:529edb329ee0 77 /// State used by all ROM ID search functions.
IanBenzMaxim 77:529edb329ee0 78 struct SearchState
IanBenzMaxim 77:529edb329ee0 79 {
IanBenzMaxim 77:529edb329ee0 80 RomId romId;
IanBenzMaxim 77:529edb329ee0 81 uint8_t last_discrepancy;
IanBenzMaxim 77:529edb329ee0 82 uint8_t last_family_discrepancy;
IanBenzMaxim 77:529edb329ee0 83 bool last_device_flag;
IanBenzMaxim 77:529edb329ee0 84
IanBenzMaxim 77:529edb329ee0 85 /// Reset to the search state to start at the beginning.
IanBenzMaxim 77:529edb329ee0 86 void reset();
IanBenzMaxim 77:529edb329ee0 87
IanBenzMaxim 77:529edb329ee0 88 /// Setup the search to find the device type 'family_code'
IanBenzMaxim 77:529edb329ee0 89 /// on the next call to OWNext() if it is present.
IanBenzMaxim 77:529edb329ee0 90 void findFamily(uint8_t familyCode);
IanBenzMaxim 77:529edb329ee0 91
IanBenzMaxim 77:529edb329ee0 92 /// Setup the search to skip the current device type on the
IanBenzMaxim 77:529edb329ee0 93 /// next call to OWNext().
IanBenzMaxim 77:529edb329ee0 94 void skipCurrentFamily();
IanBenzMaxim 77:529edb329ee0 95
IanBenzMaxim 77:529edb329ee0 96 SearchState() { reset(); }
IanBenzMaxim 77:529edb329ee0 97 };
IanBenzMaxim 74:23be10c32fa3 98
IanBenzMaxim 76:84e6c4994e29 99 /// Perform a CRC16 calculation.
IanBenzMaxim 76:84e6c4994e29 100 /// @param crc16 Beginning state of the CRC generator.
IanBenzMaxim 76:84e6c4994e29 101 /// @param data Data to pass though the CRC generator.
IanBenzMaxim 76:84e6c4994e29 102 /// @returns The calculated CRC16.
IanBenzMaxim 76:84e6c4994e29 103 static uint16_t calculateCrc16(uint16_t crc16, uint16_t data);
IanBenzMaxim 74:23be10c32fa3 104
IanBenzMaxim 76:84e6c4994e29 105 /// Perform a CRC16 calculation with variable length data.
IanBenzMaxim 76:84e6c4994e29 106 /// @param[in] data Data array to pass through the CRC generator.
IanBenzMaxim 76:84e6c4994e29 107 /// @param data_offset Offset of the data array to begin processing.
IanBenzMaxim 76:84e6c4994e29 108 /// @param data_len Length of the data array to process.
IanBenzMaxim 76:84e6c4994e29 109 /// @param crc Beginning state of the CRC generator.
IanBenzMaxim 76:84e6c4994e29 110 /// @returns The calculated CRC16.
IanBenzMaxim 76:84e6c4994e29 111 static uint16_t calculateCrc16(const uint8_t * data, size_t dataOffset, size_t dataLen, uint16_t crc = 0);
IanBenzMaxim 75:8b627804927c 112
IanBenzMaxim 76:84e6c4994e29 113 /// Allow freeing through a base class pointer.
IanBenzMaxim 76:84e6c4994e29 114 virtual ~OneWireMaster() { }
IanBenzMaxim 75:8b627804927c 115
IanBenzMaxim 76:84e6c4994e29 116 /// Initialize a master for use.
IanBenzMaxim 76:84e6c4994e29 117 virtual CmdResult OWInitMaster() = 0;
IanBenzMaxim 74:23be10c32fa3 118
IanBenzMaxim 76:84e6c4994e29 119 /// Reset all of the devices on the 1-Wire bus and check for a presence pulse.
IanBenzMaxim 76:84e6c4994e29 120 /// @returns OperationFailure if reset was performed but no presence pulse was detected.
IanBenzMaxim 76:84e6c4994e29 121 virtual CmdResult OWReset() = 0;
IanBenzMaxim 75:8b627804927c 122
IanBenzMaxim 76:84e6c4994e29 123 /// Send and receive one bit of communication and set a new level on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 124 /// @param[in,out] sendRecvBit Buffer containing the bit to send on 1-Wire bus in lsb.
IanBenzMaxim 76:84e6c4994e29 125 /// Read data from 1-Wire bus will be returned in lsb.
IanBenzMaxim 76:84e6c4994e29 126 /// @param afterLevel Level to set the 1-Wire bus to after communication.
IanBenzMaxim 76:84e6c4994e29 127 virtual CmdResult OWTouchBitSetLevel(uint8_t & sendRecvBit, OWLevel afterLevel) = 0;
IanBenzMaxim 74:23be10c32fa3 128
IanBenzMaxim 76:84e6c4994e29 129 /// Send one byte of communication and set a new level on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 130 /// @param sendByte Byte to send on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 131 /// @param afterLevel Level to set the 1-Wire bus to after communication.
IanBenzMaxim 76:84e6c4994e29 132 virtual CmdResult OWWriteByteSetLevel(uint8_t sendByte, OWLevel afterLevel) = 0;
IanBenzMaxim 76:84e6c4994e29 133
IanBenzMaxim 76:84e6c4994e29 134 /// Receive one byte of communication and set a new level on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 135 /// @param recvByte Buffer to receive the data from the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 136 /// @param afterLevel Level to set the 1-Wire bus to after communication.
IanBenzMaxim 76:84e6c4994e29 137 virtual CmdResult OWReadByteSetLevel(uint8_t & recvByte, OWLevel afterLevel) = 0;
IanBenzMaxim 74:23be10c32fa3 138
IanBenzMaxim 76:84e6c4994e29 139 /// Send a block of communication on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 140 /// @param[in] sendBuf Buffer to send on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 141 /// @param sendLen Length of the buffer to send.
IanBenzMaxim 76:84e6c4994e29 142 virtual CmdResult OWWriteBlock(const uint8_t *sendBuf, uint8_t sendLen);
IanBenzMaxim 74:23be10c32fa3 143
IanBenzMaxim 76:84e6c4994e29 144 /// Receive a block of communication on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 145 /// @param[out] recvBuf Buffer to receive the data from the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 146 /// @param recvLen Length of the buffer to receive.
IanBenzMaxim 76:84e6c4994e29 147 virtual CmdResult OWReadBlock(uint8_t *recvBuf, uint8_t recvLen);
IanBenzMaxim 74:23be10c32fa3 148
IanBenzMaxim 76:84e6c4994e29 149 /// Set the 1-Wire bus communication speed.
IanBenzMaxim 76:84e6c4994e29 150 virtual CmdResult OWSetSpeed(OWSpeed newSpeed) = 0;
IanBenzMaxim 74:23be10c32fa3 151
IanBenzMaxim 76:84e6c4994e29 152 /// Set the 1-Wire bus level.
IanBenzMaxim 76:84e6c4994e29 153 virtual CmdResult OWSetLevel(OWLevel newLevel) = 0;
IanBenzMaxim 74:23be10c32fa3 154
IanBenzMaxim 76:84e6c4994e29 155 /**********************************************************//**
IanBenzMaxim 76:84e6c4994e29 156 * @brief 1-Wire Triplet operation.
IanBenzMaxim 76:84e6c4994e29 157 *
IanBenzMaxim 76:84e6c4994e29 158 * @details Perform one bit of a 1-Wire search. This command
IanBenzMaxim 76:84e6c4994e29 159 * does two read bits and one write bit. The write bit is either
IanBenzMaxim 76:84e6c4994e29 160 * the default direction (all device have same bit) or in case
IanBenzMaxim 76:84e6c4994e29 161 * of a discrepancy, the 'search_direction' parameter is used.
IanBenzMaxim 76:84e6c4994e29 162 *
IanBenzMaxim 76:84e6c4994e29 163 * @param[in,out] search_direction
IanBenzMaxim 76:84e6c4994e29 164 * Input with desired direction in case both read bits are zero.
IanBenzMaxim 76:84e6c4994e29 165 * Output with direction taken based on read bits.
IanBenzMaxim 76:84e6c4994e29 166 *
IanBenzMaxim 76:84e6c4994e29 167 * @param[out] sbr Bit result of first read operation.
IanBenzMaxim 76:84e6c4994e29 168 * @param[out] tsb Bit result of second read operation.
IanBenzMaxim 76:84e6c4994e29 169 **************************************************************/
IanBenzMaxim 76:84e6c4994e29 170 virtual CmdResult OWTriplet(SearchDirection & searchDirection, uint8_t & sbr, uint8_t & tsb);
IanBenzMaxim 75:8b627804927c 171
IanBenzMaxim 76:84e6c4994e29 172 /// Send one bit of communication and set a new level on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 173 /// @param sendBit Buffer containing the bit to send on 1-Wire bus in lsb.
IanBenzMaxim 76:84e6c4994e29 174 /// @param afterLevel Level to set the 1-Wire bus to after communication.
IanBenzMaxim 76:84e6c4994e29 175 CmdResult OWWriteBitSetLevel(uint8_t sendBit, OWLevel afterLevel) { return OWTouchBitSetLevel(sendBit, afterLevel); }
IanBenzMaxim 75:8b627804927c 176
IanBenzMaxim 76:84e6c4994e29 177 /// Receive one bit of communication and set a new level on the 1-Wire bus.
IanBenzMaxim 76:84e6c4994e29 178 /// @param[out] sendRecvBit Read data from 1-Wire bus will be returned in lsb.
IanBenzMaxim 76:84e6c4994e29 179 /// @param afterLevel Level to set the 1-Wire bus to after communication.
IanBenzMaxim 76:84e6c4994e29 180 CmdResult OWReadBitSetLevel(uint8_t & recvBit, OWLevel afterLevel) { recvBit = 0x01; return OWTouchBitSetLevel(recvBit, afterLevel); }
IanBenzMaxim 75:8b627804927c 181
IanBenzMaxim 76:84e6c4994e29 182 // Alternate forms of read and write functions
IanBenzMaxim 76:84e6c4994e29 183 CmdResult OWWriteBit(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, NormalLevel); }
IanBenzMaxim 76:84e6c4994e29 184 CmdResult OWReadBit(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, NormalLevel); }
IanBenzMaxim 76:84e6c4994e29 185 CmdResult OWWriteBitPower(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, StrongLevel); }
IanBenzMaxim 76:84e6c4994e29 186 CmdResult OWReadBitPower(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, StrongLevel); }
IanBenzMaxim 76:84e6c4994e29 187 CmdResult OWWriteByte(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, NormalLevel); }
IanBenzMaxim 76:84e6c4994e29 188 CmdResult OWReadByte(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, NormalLevel); }
IanBenzMaxim 76:84e6c4994e29 189 CmdResult OWWriteBytePower(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, StrongLevel); }
IanBenzMaxim 76:84e6c4994e29 190 CmdResult OWReadBytePower(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, StrongLevel); }
IanBenzMaxim 77:529edb329ee0 191
IanBenzMaxim 77:529edb329ee0 192 /// Find the 'first' devices on the 1-Wire network.
IanBenzMaxim 77:529edb329ee0 193 CmdResult OWFirst(SearchState & searchState);
IanBenzMaxim 77:529edb329ee0 194
IanBenzMaxim 77:529edb329ee0 195 /// Find the 'next' devices on the 1-Wire network.
IanBenzMaxim 77:529edb329ee0 196 CmdResult OWNext(SearchState & searchState);
IanBenzMaxim 77:529edb329ee0 197
IanBenzMaxim 77:529edb329ee0 198 /// Verify that the device with the specified ROM ID is present.
IanBenzMaxim 77:529edb329ee0 199 CmdResult OWVerify(const RomId & romId);
IanBenzMaxim 77:529edb329ee0 200
IanBenzMaxim 77:529edb329ee0 201 /// Use Read ROM command to read ROM ID from device on bus.
IanBenzMaxim 77:529edb329ee0 202 /// @note Only use this command with a single drop bus, data
IanBenzMaxim 77:529edb329ee0 203 /// collisions will occur if more than 1 device on bus.
IanBenzMaxim 77:529edb329ee0 204 /// @param[out] romId ROM ID read from device.
IanBenzMaxim 77:529edb329ee0 205 CmdResult OWReadRom(RomId & romId);
IanBenzMaxim 77:529edb329ee0 206
IanBenzMaxim 77:529edb329ee0 207 /// Issue Skip ROM command on bus.
IanBenzMaxim 77:529edb329ee0 208 /// @note Only use this command with a single drop bus, data
IanBenzMaxim 77:529edb329ee0 209 /// collisions will occur if more than 1 device on bus.
IanBenzMaxim 77:529edb329ee0 210 CmdResult OWSkipRom();
IanBenzMaxim 77:529edb329ee0 211
IanBenzMaxim 77:529edb329ee0 212 /// Use the Match ROM command to select the device by its known ID.
IanBenzMaxim 77:529edb329ee0 213 /// @param[in] romId ROM ID of device to select.
IanBenzMaxim 77:529edb329ee0 214 CmdResult OWMatchRom(const RomId & romId);
IanBenzMaxim 77:529edb329ee0 215
IanBenzMaxim 77:529edb329ee0 216 /// Issue Overdrive Skip ROM command on bus.
IanBenzMaxim 77:529edb329ee0 217 /// @details This command causes all devices supporting Overdrive
IanBenzMaxim 77:529edb329ee0 218 /// mode to switch to Overdrive timing.
IanBenzMaxim 77:529edb329ee0 219 /// @note Only use this command with a single drop bus, data
IanBenzMaxim 77:529edb329ee0 220 /// collisions will occur if more than 1 device on bus.
IanBenzMaxim 77:529edb329ee0 221 CmdResult OWOverdriveSkipRom();
IanBenzMaxim 77:529edb329ee0 222
IanBenzMaxim 77:529edb329ee0 223
IanBenzMaxim 77:529edb329ee0 224 CmdResult OWOverdriveMatchRom(const RomId & romId);
IanBenzMaxim 77:529edb329ee0 225
IanBenzMaxim 77:529edb329ee0 226 /// Perform a Resume ROM command on bus.
IanBenzMaxim 77:529edb329ee0 227 /// @details Resumes communication with the last device selected
IanBenzMaxim 77:529edb329ee0 228 /// though a Match ROM or Search ROM operation.
IanBenzMaxim 77:529edb329ee0 229 CmdResult OWResume();
IanBenzMaxim 77:529edb329ee0 230
IanBenzMaxim 77:529edb329ee0 231 /**********************************************************//**
IanBenzMaxim 77:529edb329ee0 232 * @brief Enumerate all devices on the 1-Wire bus.
IanBenzMaxim 77:529edb329ee0 233 *
IanBenzMaxim 77:529edb329ee0 234 * @details The 'OWSearch' function does a general search. This
IanBenzMaxim 77:529edb329ee0 235 * function continues from the previous search state. The
IanBenzMaxim 77:529edb329ee0 236 * search state can be reset by using the 'OWFirst'
IanBenzMaxim 77:529edb329ee0 237 * function. This function contains one parameter
IanBenzMaxim 77:529edb329ee0 238 * 'alarm_only'. When 'alarm_only' is TRUE (1) the find
IanBenzMaxim 77:529edb329ee0 239 * alarm command 0xEC is sent instead of the normal search
IanBenzMaxim 77:529edb329ee0 240 * command 0xF0. Using the find alarm command 0xEC will
IanBenzMaxim 77:529edb329ee0 241 * limit the search to only 1-Wire devices that are in an
IanBenzMaxim 77:529edb329ee0 242 * 'alarm' state.
IanBenzMaxim 77:529edb329ee0 243 **************************************************************/
IanBenzMaxim 77:529edb329ee0 244 CmdResult OWSearch(SearchState & searchState);
IanBenzMaxim 76:84e6c4994e29 245 };
IanBenzMaxim 73:2cecc1372acc 246 }
j3 15:f6cb0d906fb6 247
IanBenzMaxim 74:23be10c32fa3 248 #endif