File content as of revision 23:e8e403d61359:

/******************************************************************//**
* 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 "mbed.h"
#include "RomId.hpp"


class OneWireMaster
{
    public:
    
    enum OW_ROM_CMD
    {
        READ_ROM = 0x33,
        MATCH_ROM = 0x55,
        SEARCH_ROM = 0xF0,
        SKIP_ROM = 0xCC,
        RESUME = 0xA5,
        OVERDRIVE_SKIP = 0x3C,
        OVERDRIVE_MATCH = 0x69
    };
    
    enum OW_SPEED
    {
        SPEED_STANDARD = 0x00,
        SPEED_OVERDRIVE = 0x01
    };
    
    enum OW_LEVEL
    {
        LEVEL_NORMAL = 0x00,
        LEVEL_STRONG = 0x02
    };
    
    enum CmdResult
    {
        Success,
        CommunicationWriteError,
        CommunicationReadError,
        TimeoutError,
        OperationFailure
    };
    
    static uint16_t calculateCRC16(uint16_t CRC16, uint16_t data);
    
    static uint16_t calculateCRC16(const uint8_t * data, size_t data_offset, size_t data_len, uint16_t crc = 0);
    
    
    /**********************************************************//**
    * @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(uint8_t & sendrecvbit) = 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(uint8_t sendbyte) = 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(uint8_t & recvbyte) = 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 uint8_t *tran_buf, 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(uint8_t *rx_buf, uint8_t rx_len) = 0;
    
    
    /**********************************************************//**
    * @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
    **************************************************************/
    virtual CmdResult OWSearch(RomId & romId) = 0;
    
    
    /**********************************************************//**
    * @brief OWSpeed()
    * 
    * @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 OWSpeed(OW_SPEED new_speed) = 0;
    
    /**********************************************************//**
    * @brief OWLevel()
    *
    * @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 OWLevel(OW_LEVEL new_level) = 0;
    
    
    /**********************************************************//**
    * @brief OWWriteBytePower()
    * 
    * @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.  After the 8 bits are sent 
    *          change the level of the 1-Wire net.
    *
    * On Entry:
    *     @param[in] 'sendbyte' - 8 bits to send (least significant bit)
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWWriteBytePower(uint8_t sendbyte) = 0;
    
    
    /**********************************************************//**
    * @brief OWReadBitPower()
    * 
    * @details 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. 
    *
    * On Entry:
    *     @param[in] 'applyPowerResponse' - 1 bit response to check, 
    *                                       if correct 
    *                                       then start power delivery 
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWReadBitPower(uint8_t applyPowerResponse) = 0;
    
    
    virtual CmdResult OWReadBytePower(uint8_t & recvbyte) = 0; 
    //{ return OperationFailure; }

    
    //Part of OneWireInterface that should only be implemented once
    
    
    /**********************************************************//**
    * @brief OWWriteBit()
    * 
    * @details Send 1 bit of communication to the 1-Wire Net.
    *          The parameter 'sendbit' least significant bit is used.
    *
    * On Entry:
    *     @param[in] 'sendbit' - 1 bit to send (least significant byte)
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWWriteBit(uint8_t sendbit);
    
    
    /**********************************************************//**
    * @brief OWReadBit()
    * 
    * @details Reads 1 bit of communication from the 1-Wire Net and 
    *          returns the result
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return CmdResult - zero on success, non-zero on failure
    **************************************************************/
    virtual CmdResult OWReadBit(uint8_t & recvbit);
    
    
    /**********************************************************//**
    * @brief OWTouchByte()
    * 
    * @details 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.
    *
    * 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 OWTouchByte(uint8_t & sendrecvbyte);
    
    
    /**********************************************************//**
    * @brief OWBlock()
    * 
    * @details The 'OWBlock' transfers a block of data to and from the
    *        1-Wire Net. The result is returned in the same buffer.
    *
    * 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 CmdResult - zero on success, non-zero on failure 
    **************************************************************/
    virtual CmdResult OWBlock(uint8_t *tran_buf, uint8_t tran_len);
    
    
    /**********************************************************//**
    * @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
    **************************************************************/
    virtual CmdResult OWFirst(RomId & romId);
    
    
    /**********************************************************//**
    * @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
    **************************************************************/
    virtual CmdResult OWNext(RomId & romId);
    
    
    /**********************************************************//**
    * @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
    **************************************************************/
    virtual 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 
    **************************************************************/
    virtual void OWTargetSetup(RomId & romId);
    
    
    /**********************************************************//**
    * @brief OWFamilySkipSetup()
    * 
    * @details Setup the search to skip the current device type on the 
    *          next call to OWNext().
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return 
    **************************************************************/
    virtual void OWFamilySkipSetup(void);
    
    
    /**********************************************************//**
    * @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
    **************************************************************/
    virtual 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
    **************************************************************/
    virtual 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
    **************************************************************/
    virtual 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
    **************************************************************/
    virtual 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
    **************************************************************/
    virtual 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
    **************************************************************/
    virtual CmdResult OWResume(void);
    
    protected:
    
    // Search state
    uint8_t _last_discrepancy;
    uint8_t _last_family_discrepancy;
    bool _last_device_flag;

    private:
    
    static const uint16_t _oddparity[16];
};





#endif /*ONEWIREMASTERSSHARED_H*/