Superseded by MaximInterface.

File content as of revision 0:19ec8044b826:

/******************************************************************//**
* @file OneWireMaster.h
*
* @author Justin Jordan
*
* @version 0.0
*
* Started: 29JAN16
*
* Updated: 
*
* @brief Header file for abstract class that defines 1-wire interface 
***********************************************************************
* 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 ONEWIREMASTER_H
#define ONEWIREMASTER_H


/*

http://www.learncpp.com/cpp-tutorial/126-pure-virtual-functions-abstract-base-classes-and-interface-classes/

Interface classes

An interface class is a class that has no members variables, and where 
all of the functions are pure virtual! In other words, the class is purely 
a definition, and has no actual implementation. Interfaces are useful when 
you want to define the functionality that derived classes must implement, 
but leave the details of how the derived class implements that functionality 
entirely up to the derived class.

*/

//interface taken from AN3684
//https://www.maximintegrated.com/en/app-notes/index.mvp/id/3684

class OneWireMaster
{
    public:
    
    /**********************************************************//**
    * @brief Reset all of the devices on the 1-Wire Net and return 
    *        the result.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return TRUE(1):  presence pulse(s) detected, device(s) reset
    *            FALSE(0): no presence pulses detected
    **************************************************************/
    virtual uint8_t OWReset() = 0;
    
    
    /**********************************************************//**
    * @brief Send 1 bit of communication to the 1-Wire Net.
    *        The parameter 'sendbit' least significant bit is used.
    * 
    * @details
    *
    * On Entry:
    *     @param[in] 'sendbit' - 1 bit to send (least significant byte)
    *
    * On Exit:
    *    @return 
    **************************************************************/
    virtual void OWWriteBit(uint8_t sendbit) = 0;
    
    
    /**********************************************************//**
    * @brief Reads 1 bit of communication from the 1-Wire Net and 
    *        returns the result
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return 1 bit read from 1-Wire Net
    **************************************************************/
    virtual uint8_t OWReadBit() = 0;
    
    
    /**********************************************************//**
    * @brief 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.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'sendbit' - the least significant bit is the bit to send
    *
    * On Exit:
    *    @return 0:   0 bit read from sendbit
    *            1:   1 bit read from sendbit
    **************************************************************/
    virtual uint8_t OWTouchBit(uint8_t sendbit) = 0;
    
    
    /**********************************************************//**
    * @brief 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.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'sendbyte' - 8 bits to send (least significant byte)
    *
    * On Exit:
    *    @return TRUE: bytes written and echo was the same
    *            FALSE: echo was not the same
    **************************************************************/
    virtual void OWWRiteByte(uint8_t sendbyte) = 0;
    
    
    /**********************************************************//**
    * @brief Send 8 bits of read communication to the 1-Wire Net and 
    *        return the result 8 bits read from the 1-Wire Net.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return 8 bits read from 1-Wire Net
    **************************************************************/
    virtual uint8_t OWReadByte(void) = 0;
    
    
    /**********************************************************//**
    * @brief Send 8 bits of communication to the 1-Wire Net and 
    *        return the result 8 bits read from the 1-Wire Net.  The 
    *        parameter 'sendbyte' least significant 8 bits are used 
    *        and the least significant 8 bits of the result is the 
    *        return byte.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'sendbyte' - 8 bits to send (least significant byte)
    *
    * On Exit:
    *    @return 8 bits read from sendbyte
    **************************************************************/
    virtual uint8_t OWTouchByte(uint8_t sendbyte) = 0;
    
    
    /**********************************************************//**
    * @brief The 'OWBlock' transfers a block of data to and from the
    *        1-Wire Net. The result is returned in the same buffer.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'tran_buf' - pointer to a block of unsigned
    *                             chars of length 'tran_len' that 
    *                             will be sent to the 1-Wire Net
    *     @param[in] 'tran_len' - length in bytes to transfer
    *
    * On Exit:
    *    @return 
    **************************************************************/
    virtual void OWBlock(uint8_t *tran_buf, uint8_t tran_len) = 0;
    
    
    /**********************************************************//**
    * @brief Find the 'first' devices on the 1-Wire network
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return TRUE  : device found, ROM number in ROM_NO buffer
    *            FALSE : no device present
    **************************************************************/
    virtual void OWFirst(void) = 0;
    
    
    /**********************************************************//**
    * @brief Find the 'next' devices on the 1-Wire network
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return TRUE  : device found, ROM number in ROM_NO buffer
    *            FALSE : device not found, end of search
    **************************************************************/
    virtual uint8_t OWNext(void) = 0;
    
    
    /**********************************************************//**
    * @brief Verify the device with the ROM number in ROM_NO buffer 
    *        is present.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return TRUE  : device verified present
    *            FALSE : device not present
    **************************************************************/
    virtual uint8_t OWVerify(void) = 0;
    
    
    /**********************************************************//**
    * @brief Setup the search to find the device type 'family_code' 
    *        on the next call to OWNext() if it is present.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] family_code - family code of device
    *
    * On Exit:
    *    @return 
    **************************************************************/
    virtual void OWTargetSetup(uint8_t family_code) = 0;
    
    
    /**********************************************************//**
    * @brief Setup the search to skip the current device type on the 
    *        next call to OWNext().
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return 
    **************************************************************/
    virtual void OWFamilySkipSetup(void) = 0;
    
    
    **********************************************************//**
    * @brief 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.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *    @return TRUE (1) : when a 1-Wire device was found and its
    *                       Serial Number placed in the global ROM 
    *            FALSE (0): when no new device was found.  Either the
    *                       last search was the last device or there
    *                       are no devices on the 1-Wire Net.
    **************************************************************/
    virtual uint8_t OWSearch(void) = 0;
    
    
    **********************************************************//**
    * @brief Set the 1-Wire Net communication speed.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'new_speed' - new speed defined as
    *                              MODE_STANDARD   0x00
    *                              MODE_OVERDRIVE  0x01
    *
    * On Exit:
    *    @return current 1-Wire Net speed
    **************************************************************/
    virtual uint8_t OWSpeed(uint8_t new_speed) = 0;
    
    
    **********************************************************//**
    * @brief 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. 
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'new_level' - new level defined as
    *                              MODE_STANDARD     0x00
    *
    * On Exit:
    *    @return current 1-Wire Net level
    **************************************************************/
    virtual uint8_t OWLevel(uint8_t new_level) = 0;
    
    
    **********************************************************//**
    * @brief 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.  After the 8 bits are sent 
    *        change the level of the 1-Wire net.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'sendbyte' - 8 bits to send (least significant bit)
    *
    * On Exit:
    *    @return TRUE: bytes written and echo was the same, strong pullup now on
    *            FALSE: echo was not the same 
    **************************************************************/
    virtual uint8_t OWWriteBytePower(uint8_t sendbyte) = 0;
    
    
    **********************************************************//**
    * @brief Send 1 bit of communication to the 1-Wire Net and verify
    *        that the response matches the 'applyPowerResponse' bit 
    *        and apply power delivery to the 1-Wire net.  Note that 
    *        some implementations may apply the power first and then 
    *        turn it off if the response is incorrect.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] 'applyPowerResponse' - 1 bit response to check, 
    *                                       if correct 
    *                                       then start power delivery 
    *
    * On Exit:
    *    @return 
    **************************************************************/
    virtual uint8_t OWReadBitPower(uint8_t applyPowerResponse) = 0;
    
    
    **********************************************************//**
    * @brief Calculate the CRC8 of the byte value provided with the 
    *        current global 'crc8' value.
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] data
    *
    * On Exit:
    *    @return current global crc8 value
    **************************************************************/
    virtual uint8_t calc_crc8(uint8_t data) = 0;
    
};

#endif /*ONEWIREMASTER_H*/