Superseded by MaximInterface.

File content as of revision 32:bce180b544ed:

/******************************************************************//**
* 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

#include <cstdint>
#include <cstddef>

#include "RomId.hpp"

class OneWireMaster
{   
public:
    
    enum OWSpeed
    {
        SPEED_STANDARD = 0x00,
        SPEED_OVERDRIVE = 0x01
    };
    
    enum OWLevel
    {
        LEVEL_NORMAL = 0x00,
        LEVEL_STRONG = 0x02
    };
    
    enum SearchDirection
    {
        DIRECTION_WRITE_ZERO = 0,
        DIRECTION_WRITE_ONE = 1
    };
    
    enum CmdResult
    {
        Success,
        CommunicationWriteError,
        CommunicationReadError,
        TimeoutError,
        OperationFailure
    };
    
    struct SearchState
    {
        RomId romId;
        std::uint8_t last_discrepancy;
        std::uint8_t last_family_discrepancy;
        bool last_device_flag;
        
        void reset()
        {
            last_discrepancy = 0;
            last_device_flag = false;
            last_family_discrepancy = 0;
            romId.reset();
        }
        
        SearchState() { reset(); }
    };
    
    static std::uint16_t calculateCRC16(std::uint16_t CRC16, std::uint16_t data);
    
    static std::uint16_t calculateCRC16(const std::uint8_t * data, std::size_t data_offset, std::size_t data_len, std::uint16_t crc = 0);
    
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWTouchBit(std::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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWWriteByte(std::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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWReadByte(std::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:
    *
    * @return CmdResult - zero on success, non-zero on failure 
    **************************************************************/
    virtual CmdResult OWWriteBlock(const std::uint8_t *tran_buf, std::uint8_t tran_len) = 0;
    
    
    /**********************************************************//**
    * @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:
    *
    * @return CmdResult - zero on success, non-zero on failure  
    **************************************************************/
    virtual CmdResult OWReadBlock(std::uint8_t *rx_buf, std::uint8_t rx_len) = 0;
    
    
    /**********************************************************//**
    * @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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWSetLevel(OWLevel new_level) = 0;
    
    
    
    
    virtual CmdResult OWTriplet(SearchDirection & search_direction, std::uint8_t & sbr, std::uint8_t & tsb);
    
    
    CmdResult OWWriteBit(std::uint8_t sendbit, OWLevel after_level) { return OWTouchBit(sendbit, after_level); }
    CmdResult OWReadBit(std::uint8_t & recvbit, OWLevel after_level) { recvbit = 0x01; return OWTouchBit(recvbit, after_level); }
    
    CmdResult OWWriteBit(std::uint8_t sendbit) { return OWWriteBit(sendbit, LEVEL_NORMAL); }
    CmdResult OWReadBit(std::uint8_t & recvbit) { return OWReadBit(recvbit, LEVEL_NORMAL); }
    CmdResult OWWriteBitPower(std::uint8_t sendbit) { return OWWriteBit(sendbit, LEVEL_STRONG); }
    CmdResult OWReadBitPower(std::uint8_t & recvbit) { return OWReadBit(recvbit, LEVEL_STRONG); }
    CmdResult OWWriteByte(std::uint8_t sendbyte) { return OWWriteByte(sendbyte, LEVEL_NORMAL); }
    CmdResult OWReadByte(std::uint8_t & recvbyte) { return OWReadByte(recvbyte, LEVEL_NORMAL); }
    CmdResult OWWriteBytePower(std::uint8_t sendbyte) { return OWWriteByte(sendbyte, LEVEL_STRONG); }
    CmdResult OWReadBytePower(std::uint8_t & recvbyte) { return OWReadByte(recvbyte, LEVEL_STRONG); }
    
    
    /**********************************************************//**
    * @brief OWFirst()
    * 
    * @details Find the 'first' devices on the 1-Wire network
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    CmdResult OWFirst(SearchState & searchState);
    
    
    /**********************************************************//**
    * @brief OWNext()
    * 
    * @details Find the 'next' devices on the 1-Wire network
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    CmdResult OWNext(SearchState & searchState);
    
    
    /**********************************************************//**
    * @brief OWVerify()
    * 
    * @details Verify the device with the ROM number in ROM_NO buffer 
    *        is present.
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return 
    **************************************************************/
    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:
    *
    * @return 
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    CmdResult OWReadROM(RomId & romId);
    
    
    /**********************************************************//**
    * @brief OWSkipROM()
    * 
    * @details Issue SKIP_ROM command on 1-wire bus
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    CmdResult OWOverdriveSkipROM(void);
    
    
    /**********************************************************//**
    * @brief OWOverdriveMatchROM()
    * 
    * @details Issues OVERDRIVE_MATCH rom command.  DS248X OW speed 
    * is set to SPEED_OVERDRIVE
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    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:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    CmdResult OWSearch(SearchState & searchState);
    
    
private:

    enum OW_ROM_CMD
    {
        READ_ROM = 0x33,
        MATCH_ROM = 0x55,
        SEARCH_ROM = 0xF0,
        SKIP_ROM = 0xCC,
        RESUME = 0xA5,
        OVERDRIVE_SKIP_ROM = 0x3C,
        OVERDRIVE_MATCH_ROM = 0x69
    };
    
    static const std::uint16_t _oddparity[16];
};





#endif /*ONEWIREMASTER_H*/