OneWireMaster.h

00001 /******************************************************************//**
00002 * Copyright (C) 2016 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 OneWire_Masters_OneWireMaster
00034 #define OneWire_Masters_OneWireMaster
00035 
00036 #include <stdint.h>
00037 #include <stddef.h>
00038 
00039 namespace OneWire
00040 {
00041     /// Base class for all 1-Wire Masters.
00042     class OneWireMaster
00043     {
00044     public:
00045         /// Speed of the 1-Wire bus.
00046         enum OWSpeed
00047         {
00048             StandardSpeed = 0x00,
00049             OverdriveSpeed = 0x01
00050         };
00051 
00052         /// Level of the 1-Wire bus.
00053         enum OWLevel
00054         {
00055             NormalLevel = 0x00,
00056             StrongLevel = 0x02
00057         };
00058 
00059         /// Search direction for the triplet operation.
00060         enum SearchDirection
00061         {
00062             WriteZero = 0,
00063             WriteOne = 1
00064         };
00065 
00066         /// Result of all 1-Wire commands.
00067         enum CmdResult
00068         {
00069             Success,
00070             CommunicationWriteError,
00071             CommunicationReadError,
00072             TimeoutError,
00073             OperationFailure
00074         };
00075 
00076         /// Allow freeing through a base class pointer.
00077         virtual ~OneWireMaster() { }
00078 
00079         /// Initialize a master for use.
00080         virtual CmdResult OWInitMaster() = 0;
00081 
00082         /// Reset all of the devices on the 1-Wire bus and check for a presence pulse.
00083         /// @returns OperationFailure if reset was performed but no presence pulse was detected.
00084         virtual CmdResult OWReset() = 0;
00085 
00086         /// Send and receive one bit of communication and set a new level on the 1-Wire bus.
00087         /// @param[in,out] sendRecvBit Buffer containing the bit to send on 1-Wire bus in lsb.
00088         ///                            Read data from 1-Wire bus will be returned in lsb.
00089         /// @param afterLevel Level to set the 1-Wire bus to after communication.
00090         virtual CmdResult OWTouchBitSetLevel(uint8_t & sendRecvBit, OWLevel afterLevel) = 0;
00091 
00092         /// Send one byte of communication and set a new level on the 1-Wire bus.
00093         /// @param sendByte Byte to send on the 1-Wire bus.
00094         /// @param afterLevel Level to set the 1-Wire bus to after communication.
00095         virtual CmdResult OWWriteByteSetLevel(uint8_t sendByte, OWLevel afterLevel) = 0;
00096 
00097         /// Receive one byte of communication and set a new level on the 1-Wire bus.
00098         /// @param recvByte Buffer to receive the data from the 1-Wire bus.
00099         /// @param afterLevel Level to set the 1-Wire bus to after communication.
00100         virtual CmdResult OWReadByteSetLevel(uint8_t & recvByte, OWLevel afterLevel) = 0;
00101 
00102         /// Send a block of communication on the 1-Wire bus.
00103         /// @param[in] sendBuf Buffer to send on the 1-Wire bus.
00104         /// @param sendLen Length of the buffer to send.
00105         virtual CmdResult OWWriteBlock(const uint8_t *sendBuf, size_t sendLen);
00106 
00107         /// Receive a block of communication on the 1-Wire bus.
00108         /// @param[out] recvBuf Buffer to receive the data from the 1-Wire bus.
00109         /// @param recvLen Length of the buffer to receive.
00110         virtual CmdResult OWReadBlock(uint8_t *recvBuf, size_t recvLen);
00111 
00112         /// Set the 1-Wire bus communication speed.
00113         virtual CmdResult OWSetSpeed(OWSpeed newSpeed) = 0;
00114 
00115         /// Set the 1-Wire bus level.
00116         virtual CmdResult OWSetLevel(OWLevel newLevel) = 0;
00117 
00118         /**********************************************************//**
00119         * @brief 1-Wire Triplet operation.
00120         *
00121         * @details Perform one bit of a 1-Wire search. This command
00122         * does two read bits and one write bit. The write bit is either
00123         * the default direction (all device have same bit) or in case
00124         * of a discrepancy, the 'searchDirection' parameter is used.
00125         *
00126         * @param[in,out] searchDirection
00127         * Input with desired direction in case both read bits are zero.
00128         * Output with direction taken based on read bits.
00129         *
00130         * @param[out] sbr Bit result of first read operation.
00131         * @param[out] tsb Bit result of second read operation.
00132         **************************************************************/
00133         virtual CmdResult OWTriplet(SearchDirection & searchDirection, uint8_t & sbr, uint8_t & tsb);
00134 
00135         /// Send one bit of communication and set a new level on the 1-Wire bus.
00136         /// @param sendBit Buffer containing the bit to send on 1-Wire bus in lsb.
00137         /// @param afterLevel Level to set the 1-Wire bus to after communication.
00138         CmdResult OWWriteBitSetLevel(uint8_t sendBit, OWLevel afterLevel) { return OWTouchBitSetLevel(sendBit, afterLevel); }
00139 
00140         /// Receive one bit of communication and set a new level on the 1-Wire bus.
00141         /// @param[out] sendRecvBit Read data from 1-Wire bus will be returned in lsb.
00142         /// @param afterLevel Level to set the 1-Wire bus to after communication.
00143         CmdResult OWReadBitSetLevel(uint8_t & recvBit, OWLevel afterLevel) { recvBit = 0x01; return OWTouchBitSetLevel(recvBit, afterLevel); }
00144 
00145         // Alternate forms of read and write functions
00146         CmdResult OWWriteBit(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, NormalLevel); }
00147         CmdResult OWReadBit(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, NormalLevel); }
00148         CmdResult OWWriteBitPower(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, StrongLevel); }
00149         CmdResult OWReadBitPower(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, StrongLevel); }
00150         CmdResult OWWriteByte(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, NormalLevel); }
00151         CmdResult OWReadByte(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, NormalLevel); }
00152         CmdResult OWWriteBytePower(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, StrongLevel); }
00153         CmdResult OWReadBytePower(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, StrongLevel); }
00154     };
00155 }
00156 
00157 #endif