OneWireMaster.hpp

00001 /*******************************************************************************
00002 * Copyright (C) 2017 Maxim Integrated Products, Inc., All Rights Reserved.
00003 *
00004 * Permission is hereby granted, free of charge, to any person obtaining a
00005 * copy of this software and associated documentation files (the "Software"),
00006 * to deal in the Software without restriction, including without limitation
00007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008 * and/or sell copies of the Software, and to permit persons to whom the
00009 * Software is furnished to do so, subject to the following conditions:
00010 *
00011 * The above copyright notice and this permission notice shall be included
00012 * in all copies or substantial portions of the Software.
00013 *
00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020 * OTHER DEALINGS IN THE SOFTWARE.
00021 *
00022 * Except as contained in this notice, the name of Maxim Integrated
00023 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024 * Products, Inc. Branding Policy.
00025 *
00026 * The mere transfer of this software does not imply any licenses
00027 * of trade secrets, proprietary technology, copyrights, patents,
00028 * trademarks, maskwork rights, or any other form of intellectual
00029 * property whatsoever. Maxim Integrated Products, Inc. retains all
00030 * ownership rights.
00031 *******************************************************************************/
00032 
00033 #ifndef MaximInterface_OneWireMaster
00034 #define MaximInterface_OneWireMaster
00035 
00036 #include <stdint.h>
00037 #include <MaximInterface/Utilities/Export.h>
00038 #include <MaximInterface/Utilities/span.hpp>
00039 #include <MaximInterface/Utilities/system_error.hpp>
00040 
00041 namespace MaximInterface {
00042 
00043 /// 1-Wire master interface.
00044 class OneWireMaster {
00045 public:
00046   /// Speed of the 1-Wire bus.
00047   enum Speed { StandardSpeed = 0x00, OverdriveSpeed = 0x01 };
00048 
00049   /// Level of the 1-Wire bus.
00050   enum Level { NormalLevel = 0x00, StrongLevel = 0x02 };
00051 
00052   /// Result of all 1-Wire commands.
00053   enum ErrorValue {
00054     NoSlaveError = 1, ///< Slave not detected, typically due to no presence pulse.
00055     ShortDetectedError,
00056     InvalidSpeedError,
00057     InvalidLevelError
00058   };
00059 
00060   struct TripletData {
00061     bool writeBit;
00062     bool readBit;
00063     bool readBitComplement;
00064   };
00065 
00066   virtual ~OneWireMaster() {}
00067 
00068   /// @brief
00069   /// Reset all of the devices on the 1-Wire bus and check for a presence pulse.
00070   /// @returns
00071   /// NoSlaveError if reset was performed but no presence pulse was detected.
00072   virtual error_code reset() = 0;
00073 
00074   /// @brief
00075   /// Send and receive one bit of communication and set a new level on the
00076   /// 1-Wire bus.
00077   /// @param[in,out] sendRecvBit
00078   /// Input containing the bit to send and output containing the received bit.
00079   /// @param afterLevel Level to set the 1-Wire bus to after communication.
00080   virtual error_code touchBitSetLevel(bool & sendRecvBit, Level afterLevel) = 0;
00081 
00082   /// @brief
00083   /// Send one byte of communication and set a new level on the 1-Wire bus.
00084   /// @param sendByte Byte to send on the 1-Wire bus.
00085   /// @param afterLevel Level to set the 1-Wire bus to after communication.
00086   MaximInterface_EXPORT virtual error_code
00087   writeByteSetLevel(uint_least8_t sendByte, Level afterLevel);
00088 
00089   /// @brief
00090   /// Receive one byte of communication and set a new level on the 1-Wire bus.
00091   /// @param recvByte Buffer to receive the data from the 1-Wire bus.
00092   /// @param afterLevel Level to set the 1-Wire bus to after communication.
00093   MaximInterface_EXPORT virtual error_code
00094   readByteSetLevel(uint_least8_t & recvByte, Level afterLevel);
00095 
00096   /// @brief Send a block of communication on the 1-Wire bus.
00097   /// @param[in] sendBuf Buffer to send on the 1-Wire bus.
00098   MaximInterface_EXPORT virtual error_code
00099   writeBlock(span<const uint_least8_t> sendBuf);
00100 
00101   /// @brief Receive a block of communication on the 1-Wire bus.
00102   /// @param[out] recvBuf Buffer to receive the data from the 1-Wire bus.
00103   MaximInterface_EXPORT virtual error_code
00104   readBlock(span<uint_least8_t> recvBuf);
00105 
00106   /// Set the 1-Wire bus communication speed.
00107   virtual error_code setSpeed(Speed newSpeed) = 0;
00108 
00109   /// Set the 1-Wire bus level.
00110   virtual error_code setLevel(Level newLevel) = 0;
00111 
00112   /// @brief 1-Wire Triplet operation.
00113   /// @details Perform one bit of a 1-Wire search. This command
00114   /// does two read bits and one write bit. The write bit is either
00115   /// the default direction (all devices have same bit) or in case
00116   /// of a discrepancy, the data.writeBit parameter is used.
00117   /// @param[in,out] data
00118   /// Input with desired writeBit in case both read bits are zero.
00119   /// Output with all data fields set.
00120   MaximInterface_EXPORT virtual error_code triplet(TripletData & data);
00121 
00122   /// @brief
00123   /// Send one bit of communication and set a new level on the 1-Wire bus.
00124   /// @param sendBit Bit to send on the 1-Wire bus.
00125   /// @param afterLevel Level to set the 1-Wire bus to after communication.
00126   error_code writeBitSetLevel(bool sendBit, Level afterLevel) {
00127     return touchBitSetLevel(sendBit, afterLevel);
00128   }
00129 
00130   /// @brief
00131   /// Receive one bit of communication and set a new level on the 1-Wire bus.
00132   /// @param[out] recvBit Received data from the 1-Wire bus.
00133   /// @param afterLevel Level to set the 1-Wire bus to after communication.
00134   error_code readBitSetLevel(bool & recvBit, Level afterLevel) {
00135     recvBit = 1;
00136     return touchBitSetLevel(recvBit, afterLevel);
00137   }
00138 
00139   // Alternate forms of the read and write functions.
00140   
00141   error_code touchBit(bool & sendRecvBit) {
00142     return touchBitSetLevel(sendRecvBit, NormalLevel);
00143   }
00144   
00145   error_code writeBit(bool sendBit) {
00146     return writeBitSetLevel(sendBit, NormalLevel);
00147   }
00148   
00149   error_code readBit(bool & recvBit) {
00150     return readBitSetLevel(recvBit, NormalLevel);
00151   }
00152   
00153   error_code writeBitPower(bool sendBit) {
00154     return writeBitSetLevel(sendBit, StrongLevel);
00155   }
00156   
00157   error_code readBitPower(bool & recvBit) {
00158     return readBitSetLevel(recvBit, StrongLevel);
00159   }
00160   
00161   error_code writeByte(uint_least8_t sendByte) {
00162     return writeByteSetLevel(sendByte, NormalLevel);
00163   }
00164   
00165   error_code readByte(uint_least8_t & recvByte) {
00166     return readByteSetLevel(recvByte, NormalLevel);
00167   }
00168   
00169   error_code writeBytePower(uint_least8_t sendByte) {
00170     return writeByteSetLevel(sendByte, StrongLevel);
00171   }
00172   
00173   error_code readBytePower(uint_least8_t & recvByte) {
00174     return readByteSetLevel(recvByte, StrongLevel);
00175   }
00176 
00177   MaximInterface_EXPORT static const error_category & errorCategory();
00178 };
00179 
00180 inline error_code make_error_code(OneWireMaster::ErrorValue e) {
00181   return error_code(e, OneWireMaster::errorCategory());
00182 }
00183 
00184 inline error_condition make_error_condition(OneWireMaster::ErrorValue e) {
00185   return error_condition(e, OneWireMaster::errorCategory());
00186 }
00187 
00188 } // namespace MaximInterface
00189 
00190 #endif