Superseded by MaximInterface.

File content as of revision 75:8b627804927c:

/******************************************************************//**
* Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included
* in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
* OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
* ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
* OTHER DEALINGS IN THE SOFTWARE.
*
* Except as contained in this notice, the name of Maxim Integrated
* Products, Inc. shall not be used except as stated in the Maxim Integrated
* Products, Inc. Branding Policy.
*
* The mere transfer of this software does not imply any licenses
* of trade secrets, proprietary technology, copyrights, patents,
* trademarks, maskwork rights, or any other form of intellectual
* property whatsoever. Maxim Integrated Products, Inc. retains all
* ownership rights.
**********************************************************************/

#ifndef OneWire_Masters_OneWireMaster
#define OneWire_Masters_OneWireMaster

#include <stdint.h>
#include <stddef.h>
#include "RomId.h"

namespace OneWire
{
    namespace Masters
    {
        /// Base class for all 1-Wire Masters.
        class OneWireMaster
        {
        public:
            /// Speed of the 1-Wire bus
            enum OWSpeed
            {
                StandardSpeed = 0x00,
                OverdriveSpeed = 0x01
            };

            /// Level of the 1-Wire bus
            enum OWLevel
            {
                NormalLevel = 0x00,
                StrongLevel = 0x02
            };

            /// Search direction for the Triplet
            enum SearchDirection
            {
                WriteZero = 0,
                WriteOne = 1
            };

            /// Result of all 1-Wire commands
            enum CmdResult
            {
                Success,
                CommunicationWriteError,
                CommunicationReadError,
                TimeoutError,
                OperationFailure
            };

            /// State used by all ROM ID search functions.
            struct SearchState
            {
                RomId romId;
                uint8_t last_discrepancy;
                uint8_t last_family_discrepancy;
                bool last_device_flag;

                /// Reset to the search state to start at the beginning.
                void reset()
                {
                    last_discrepancy = 0;
                    last_device_flag = false;
                    last_family_discrepancy = 0;
                    romId.reset();
                }

                SearchState() { reset(); }
            };

            /// Perform a CRC16 calculation.
            /// @param crc16 Beginning state of the CRC generator.
            /// @param data Data to pass though the CRC generator.
            /// @returns The calculated CRC16.
            static uint16_t calculateCrc16(uint16_t crc16, uint16_t data);

            /// Perform a CRC16 calculation with variable length data.
            /// @param[in] data Data array to pass through the CRC generator.
            /// @param data_offset Offset of the data array to begin processing.
            /// @param data_len Length of the data array to process.
            /// @param crc Beginning state of the CRC generator.
            /// @returns The calculated CRC16.
            static uint16_t calculateCrc16(const uint8_t * data, size_t dataOffset, size_t dataLen, uint16_t crc = 0);

            /// Allow freeing through a base class pointer.
            virtual ~OneWireMaster() { }

            /// Initialize a master for use.
            virtual CmdResult OWInitMaster() = 0;

            /// Reset all of the devices on the 1-Wire bus and check for a presence pulse.
            /// @returns OperationFailure if reset was performed but no presence pulse was detected.
            virtual CmdResult OWReset() = 0;

            /// Send and receive one bit of communication and set a new level on the 1-Wire bus.
            /// @param[in,out] sendRecvBit Buffer containing the bit to send on 1-Wire bus in lsb.
            ///                            Read data from 1-Wire bus will be returned in lsb.
            /// @param afterLevel Level to set the 1-Wire bus to after communication.
            virtual CmdResult OWTouchBitSetLevel(uint8_t & sendRecvBit, OWLevel afterLevel) = 0;

            /// Send one byte of communication and set a new level on the 1-Wire bus.
            /// @param sendByte Byte to send on the 1-Wire bus.
            /// @param afterLevel Level to set the 1-Wire bus to after communication.
            virtual CmdResult OWWriteByteSetLevel(uint8_t sendByte, OWLevel afterLevel) = 0;

            /// Receive one byte of communication and set a new level on the 1-Wire bus.
            /// @param recvByte Buffer to receive the data from the 1-Wire bus.
            /// @param afterLevel Level to set the 1-Wire bus to after communication.
            virtual CmdResult OWReadByteSetLevel(uint8_t & recvByte, OWLevel afterLevel) = 0;

            /// Send a block of communication on the 1-Wire bus.
            /// @param[in] sendBuf Buffer to send on the 1-Wire bus.
            /// @param sendLen Length of the buffer to send.
            virtual CmdResult OWWriteBlock(const uint8_t *sendBuf, uint8_t sendLen);

            /// Receive a block of communication on the 1-Wire bus.
            /// @param[out] recvBuf Buffer to receive the data from the 1-Wire bus.
            /// @param recvLen Length of the buffer to receive.
            virtual CmdResult OWReadBlock(uint8_t *recvBuf, uint8_t recvLen);

            /// Set the 1-Wire bus communication speed.
            virtual CmdResult OWSetSpeed(OWSpeed newSpeed) = 0;

            /// Set the 1-Wire bus level.
            virtual CmdResult OWSetLevel(OWLevel newLevel) = 0;

            /**********************************************************//**
            * @brief 1-Wire Triplet operation.
            *
            * @details Perform one bit of a 1-Wire search. This command
            * does two read bits and one write bit. The write bit is either
            * the default direction (all device have same bit) or in case
            * of a discrepancy, the 'search_direction' parameter is used.
            *
            * @param[in,out] search_direction
            * Input with desired direction in case both read bits are zero.
            * Output with direction taken based on read bits.
            *
            * @param[out] sbr Bit result of first read operation.
            * @param[out] tsb Bit result of second read operation.
            **************************************************************/
            virtual CmdResult OWTriplet(SearchDirection & searchDirection, uint8_t & sbr, uint8_t & tsb);

            /// Send one bit of communication and set a new level on the 1-Wire bus.
            /// @param sendBit Buffer containing the bit to send on 1-Wire bus in lsb.
            /// @param afterLevel Level to set the 1-Wire bus to after communication.
            CmdResult OWWriteBitSetLevel(uint8_t sendBit, OWLevel afterLevel) { return OWTouchBitSetLevel(sendBit, afterLevel); }

            /// Receive one bit of communication and set a new level on the 1-Wire bus.
            /// @param[out] sendRecvBit Read data from 1-Wire bus will be returned in lsb.
            /// @param afterLevel Level to set the 1-Wire bus to after communication.
            CmdResult OWReadBitSetLevel(uint8_t & recvBit, OWLevel afterLevel) { recvBit = 0x01; return OWTouchBitSetLevel(recvBit, afterLevel); }

            // Alternate forms of read and write functions
            CmdResult OWWriteBit(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, NormalLevel); }
            CmdResult OWReadBit(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, NormalLevel); }
            CmdResult OWWriteBitPower(uint8_t sendBit) { return OWWriteBitSetLevel(sendBit, StrongLevel); }
            CmdResult OWReadBitPower(uint8_t & recvBit) { return OWReadBitSetLevel(recvBit, StrongLevel); }
            CmdResult OWWriteByte(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, NormalLevel); }
            CmdResult OWReadByte(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, NormalLevel); }
            CmdResult OWWriteBytePower(uint8_t sendByte) { return OWWriteByteSetLevel(sendByte, StrongLevel); }
            CmdResult OWReadBytePower(uint8_t & recvByte) { return OWReadByteSetLevel(recvByte, StrongLevel); }

            /// Find the 'first' devices on the 1-Wire network.
            CmdResult OWFirst(SearchState & searchState);

            /// Find the 'next' devices on the 1-Wire network.
            CmdResult OWNext(SearchState & searchState);

            /// Verify that the device with the specified ROM ID is present.
            CmdResult OWVerify(const RomId & romId);

            /// Setup the search to find the device type 'family_code'
            /// on the next call to OWNext() if it is present.
            void OWTargetSetup(SearchState & searchState);

            /// Setup the search to skip the current device type on the
            /// next call to OWNext().
            void OWFamilySkipSetup(SearchState & searchState);

            /// Use Read ROM command to read ROM ID from device on bus.
            /// @note Only use this command with a single drop bus, data
            ///       collisions will occur if more than 1 device on bus.
            /// @param[out] romId ROM ID read from device.
            CmdResult OWReadRom(RomId & romId);

            /// Issue Skip ROM command on bus.
            /// @note Only use this command with a single drop bus, data
            ///       collisions will occur if more than 1 device on bus.
            CmdResult OWSkipRom();

            /// Use the Match ROM command to select the device by its known ID.
            /// @param[in] romId ROM ID of device to select.
            CmdResult OWMatchRom(const RomId & romId);

            /// Issue Overdrive Skip ROM command on bus.
            /// @details This command causes all devices supporting Overdrive
            ///          mode to switch to Overdrive timing.
            /// @note Only use this command with a single drop bus, data
            ///       collisions will occur if more than 1 device on bus.
            CmdResult OWOverdriveSkipRom();

            
            CmdResult OWOverdriveMatchRom(const RomId & romId);

            /// Perform a Resume ROM command on bus.
            /// @details Resumes communication with the last device selected
            ///          though a Match ROM or Search ROM operation.
            CmdResult OWResume();

            /**********************************************************//**
            * @brief Enumerate all devices on the 1-Wire bus.
            *
            * @details The 'OWSearch' function does a general search.  This
            *        function continues from the previous search state. The
            *        search state can be reset by using the 'OWFirst'
            *        function. This function contains one parameter
            *        'alarm_only'. When 'alarm_only' is TRUE (1) the find
            *        alarm command 0xEC is sent instead of the normal search
            *        command 0xF0. Using the find alarm command 0xEC will
            *        limit the search to only 1-Wire devices that are in an
            *        'alarm' state.
            **************************************************************/
            CmdResult OWSearch(SearchState & searchState);
        };
    }
}

#endif