File content as of revision 73:2cecc1372acc:

/******************************************************************//**
* 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
            {
                SPEED_STANDARD = 0x00,
                SPEED_OVERDRIVE = 0x01
            };
            
            /// Level of the 1-Wire bus
            enum OWLevel
            {
                LEVEL_NORMAL = 0x00,
                LEVEL_STRONG = 0x02,
                LEVEL_PROGRAM = 0x04,
            };
            
            /// Search direction for the Triplet
            enum SearchDirection
            {
                DIRECTION_WRITE_ZERO = 0,
                DIRECTION_WRITE_ONE = 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 data_offset, size_t data_len, uint16_t crc = 0);
            
            /// Allow freeing through a base class pointer.
            virtual ~OneWireMaster() { }
            
            
            /**********************************************************//**
            * @brief OWInitMaster()
            * 
            * @details Initiializes particular master being instaniated.
            *  Added to interface to provide a common 'init' function between
            *  all masters
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWInitMaster(void) = 0;
            
            
            /**********************************************************//**
            * @brief OWReset()
            * 
            * @details Reset all of the devices on the 1-Wire Net and return 
            *          the result.
            *
            * On Entry:
            *
            * On Exit:
            *
            * @returns OperationFailure if reset was performed but no
            *          presence pulse was detected.
            **************************************************************/
            virtual CmdResult OWReset(void) = 0;
            
            
            /**********************************************************//**
            * @brief OWTouchBit()
            * 
            * @details Send 1 bit of communication to the 1-Wire Net and return 
            *          the result 1 bit read from the 1-Wire Net.  The 
            *          parameter 'sendbit' least significant bit is used and 
            *          the least significant bit of the result is the return 
            *          bit.
            *
            * On Entry:
            *     @param[in] 'sendbit' - the least significant bit is the bit to send
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWTouchBitSetLevel(uint8_t & sendrecvbit, OWLevel after_level) = 0;
            
            
            /**********************************************************//**
            * @brief OWWRiteByte()
            * 
            * @details Send 8 bits of communication to the 1-Wire Net and 
            *          verify that the 8 bits read from the 1-Wire Net is the 
            *          same (write operation).The parameter 'sendbyte' least 
            *          significant 8 bits are used.
            *
            * On Entry:
            *     @param[in] 'sendbyte' - 8 bits to send (least significant byte)
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWWriteByteSetLevel(uint8_t sendbyte, OWLevel after_level) = 0;
            
            
            /**********************************************************//**
            * @brief OWReadByte()
            * 
            * @details Send 8 bits of read communication to the 1-Wire Net 
            *          and return the result 8 bits read from the 1-Wire Net.
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWReadByteSetLevel(uint8_t & recvbyte, OWLevel after_level) = 0;
            
            
            /**********************************************************//**
            * @brief OWWriteBlock()
            * 
            * @details complements OWBlock, writes 'tran_len' bytes from 
            * 'tran_buf' to 1-wire Net.
            *
            * On Entry:
            *     @param[in] tran_buf - pointer to data to write
            *     @param[in] tran_len - number of bytes to write
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWWriteBlock(const uint8_t *tran_buf, uint8_t tran_len);
            
            
            /**********************************************************//**
            * @brief OWReadBlock()
            * 
            * @details complements OWBlock, reads 'recv_len' bytes from 
            * 1-wire Net and puts them in 'recv_buf'.
            *
            * On Entry:
            *     @param[in] recv_buf - pointer to receive buffer
            *     @param[in] recv_len - number of bytes to read
            *
            * On Exit:
            *  
            **************************************************************/
            virtual CmdResult OWReadBlock(uint8_t *rx_buf, uint8_t rx_len);
            
            
            /**********************************************************//**
            * @brief OWSetSpeed()
            * 
            * @details Set the 1-Wire Net communication speed.
            *
            * On Entry:
            *     @param[in] 'new_speed' - new speed defined as
            *                              MODE_STANDARD   0x00
            *                              MODE_OVERDRIVE  0x01
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWSetSpeed(OWSpeed new_speed) = 0;
            
            
            /**********************************************************//**
            * @brief OWSetLevel()
            *
            * @details Set the 1-Wire Net line level pull-up to normal. The 
            *          ds2484 does only allows enabling strong pull-up on a 
            *          bit or byte event. Consequently this function only 
            *          allows the MODE_STANDARD argument. To enable strong 
            *          pull-up use OWWriteBytePower or OWReadBitPower. 
            *
            * On Entry:
            *     @param[in] 'new_level' - new level defined as
            *                              MODE_STANDARD     0x00
            *
            * On Exit:
            *
            **************************************************************/
            virtual CmdResult OWSetLevel(OWLevel new_level) = 0;
            
            
            /**********************************************************//**
            * @brief OWTriplet()
            * 
            * @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 & search_direction, uint8_t & sbr, uint8_t & tsb);
            
            /// OWWriteBit()
            CmdResult OWWriteBitSetLevel(uint8_t sendbit, OWLevel after_level) { return OWTouchBitSetLevel(sendbit, after_level); }
            
            /// OWReadBit()
            CmdResult OWReadBitSetLevel(uint8_t & recvbit, OWLevel after_level) { recvbit = 0x01; return OWTouchBitSetLevel(recvbit, after_level); }
            
            // Alternate forms of read and write functions
            CmdResult OWWriteBit(uint8_t sendbit) { return OWWriteBitSetLevel(sendbit, LEVEL_NORMAL); }
            CmdResult OWReadBit(uint8_t & recvbit) { return OWReadBitSetLevel(recvbit, LEVEL_NORMAL); }
            CmdResult OWWriteBitPower(uint8_t sendbit) { return OWWriteBitSetLevel(sendbit, LEVEL_STRONG); }
            CmdResult OWReadBitPower(uint8_t & recvbit) { return OWReadBitSetLevel(recvbit, LEVEL_STRONG); }
            CmdResult OWWriteByte(uint8_t sendbyte) { return OWWriteByteSetLevel(sendbyte, LEVEL_NORMAL); }
            CmdResult OWReadByte(uint8_t & recvbyte) { return OWReadByteSetLevel(recvbyte, LEVEL_NORMAL); }
            CmdResult OWWriteBytePower(uint8_t sendbyte) { return OWWriteByteSetLevel(sendbyte, LEVEL_STRONG); }
            CmdResult OWReadBytePower(uint8_t & recvbyte) { return OWReadByteSetLevel(recvbyte, LEVEL_STRONG); }
            
            /**********************************************************//**
            * @brief OWFirst()
            * 
            * @details Find the 'first' devices on the 1-Wire network
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWFirst(SearchState & searchState);
            
            /**********************************************************//**
            * @brief OWNext()
            * 
            * @details Find the 'next' devices on the 1-Wire network
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWNext(SearchState & searchState);
            
            /**********************************************************//**
            * @brief OWVerify()
            * 
            * @details Verify the device with the ROM number in ROM_NO buffer 
            *        is present.
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWVerify(const RomId & romId);
            
            /**********************************************************//**
            * @brief OWTargetSetup()
            * 
            * @details Setup the search to find the device type 'family_code' 
            *        on the next call to OWNext() if it is present.
            *
            * On Entry:
            *     @param[in] family_code - family code of device
            *
            * On Exit:
            *
            **************************************************************/
            void OWTargetSetup(SearchState & searchState);
            
            /**********************************************************//**
            * @brief OWFamilySkipSetup()
            * 
            * @details Setup the search to skip the current device type on the 
            *          next call to OWNext().
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            void OWFamilySkipSetup(SearchState & searchState);
            
            /**********************************************************//**
            * @brief OWReadROM()
            * 
            * @details Only use this command with a single drop bus, data
            * collisions will occur if more than 1 device on bus.
            * Issues READ_ROM command, slave device will respond with ROM ID.
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWReadROM(RomId & romId);
            
            /**********************************************************//**
            * @brief OWSkipROM()
            * 
            * @details Issue SKIP_ROM command on 1-wire bus
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWSkipROM(void);
            
            /**********************************************************//**
            * @brief OWMatchROM()
            * 
            * @details Issues MATCH_ROM command on 1-wire bus and then sends
            * the rom id in _rom_number
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWMatchROM(const RomId & romId);
            
            /**********************************************************//**
            * @brief OWOverdriveSkipROM()
            * 
            * @details Issues OVERDRIVE_SKIP rom command.  DS248X OW speed 
            * is set to SPEED_OVERDRIVE
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWOverdriveSkipROM(void);
            
            /**********************************************************//**
            * @brief OWOverdriveMatchROM()
            * 
            * @details Issues OVERDRIVE_MATCH rom command.  DS248X OW speed 
            * is set to SPEED_OVERDRIVE
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWOverdriveMatchROM(const RomId & romId);
            
            /**********************************************************//**
            * @brief OWResume()
            * 
            * @details Issues RESUME command, very usefull.  Is like skip 
            * on a multidrop bus, however you must first select the device 
            * you want to interface with using a MATCH, or SEARCH.  The 
            * device stays selected until another device is selected, 
            * see slave datasheet for detailed explanation.
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWResume(void);
            
            /**********************************************************//**
            * @brief OWSearch()
            * 
            * @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.
            *
            * On Entry:
            *
            * On Exit:
            *
            **************************************************************/
            CmdResult OWSearch(SearchState & searchState);
        };
    }
}

#endif /*ONEWIREMASTER_H*/