Superseded by MaximInterface.

File content as of revision 17:b646b1e3970b:

/******************************************************************//**
* 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 DS28E17_H
#define DS28E17_H


#include "mbed.h"
#include "OneWireMasters.h"


class Ds28e17
{
    public:
    
    enum DS28E17_CMDS
    {
        CMD_I2C_WRITE_W_STOP = 0x4B,
        CMD_I2C_WRITE_NO_STOP = 0x5A,
        CMD_I2C_WRITE_ONLY = 0x69,
        CMD_I2C_WRITE_ONLY_W_STOP = 0x78,
        CMD_I2C_READ_W_STOP = 0x87,
        CMD_I2C_WRITE_READ_W_STOP = 0x2D,
        CMD_WRITE_CONFIG_REG = 0xD2,
        CMD_READ_CONFIG_REG = 0xE1,
        CMD_DISABLE_OW_MODE = 0x96,
        CMD_ENABLE_SLEEP_MODE = 0x1E,
        CMD_READ_DEVICE_REV = 0xC3
    };
    
    enum CmdResult
    {
        Success,
        CommsReadBitError,
        CommsWriteBitError,
        CommsReadByteError,
        CommsWriteByteError,
        CommsReadBlockError,
        CommsWriteBlockError,
        TimeoutError,
        OperationFailure
    };
    
    static const size_t POLL_LIMIT = 10000;
    
    /**********************************************************//**
    * @brief Ds28e17 constructor
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] p_owm - pointer to a 1-wire master of the following
    *                        types; Ds248x, Ds2480b, OwGpio which
    *                        inherit the base class 'OneWireInterface'
    *
    * On Exit:
    *    @return 
    **************************************************************/
    Ds28e17(OneWireInterface &owm);
    
    /**********************************************************//**
    * @brief 
    * 
    * @details 
    *
    * On Entry:
    *     @param[in] romId - reference to RomId type
    *
    * On Exit:
    *
    * @return 
    **************************************************************/
    void set_rom_id(const RomId & romId);
    
    /**********************************************************//**
    * @brief
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return current RomId held by this object
    **************************************************************/
    RomId get_rom_id(void);
    
    /**********************************************************//**
    * @brief Write to selected DS28E17's I2C with Stop.  
    * Poll until I2C write complete and receive status info.
    * 
    * @details Output on I2C: S, Address + Write, Write Data [1-255], P
    *
    * On Entry:
    * @param[in]  I2C_addr - 
    * Writes I2C address. The least significant bit of the I2C 
    * address is automatically cleared by the command.
    *
    * @param[in] length
    * The number of data bytes to be written ranging from 01h to FFh.
    * A value of zero will assert the Error Detected pin (ED).
    *
    * @param[in] *data
    * User defines write data ranging from 1-255 bytes.
    *
    * On Exit:
    * @param[out] status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] wr_status
    * Indicates which write byte NACK’d. A value of 00h indicates 
    * all bytes were acknowledged by the slave.
    * A non-zero value indicates the byte number that NACK’d.
    *
    * @return 
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult I2C_WriteDataWithStop(uint8_t I2C_addr, uint8_t length, 
                               uint8_t *data, uint8_t &status, 
                               uint8_t &wr_status);
    
    /**********************************************************//**
    * @brief Write to selected DS28E17's I2C No Stop.  
    * Poll until I2C write complete and receive status info.
    * 
    * @details Output on I2C: S, Address + Write, Write Data [1-255]
    *
    * On Entry:
    * @param[in]  I2C_addr
    * Writes I2C address. The least significant bit of the I2C address
    * is automatically cleared by the command.
    *
    * @param[in]  length
    * The number of data bytes to be written ranging from 01h to FFh.
    * A value of zero will assert the Error Detected pin (ED).
    *
    * @param[in]  *data
    * User defines write data ranging from 1-255 bytes.
    *
    * On Exit:
    * @param[out]  status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] wr_status
    * Indicates which write byte NACK’d. A value of 00h indicates 
    * all bytes were acknowledged by the slave.
    * A non-zero value indicates the byte number that NACK’d.
    *
    * @return 
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult I2C_WriteDataNoStop(uint8_t I2C_addr, uint8_t length, 
                             uint8_t *data, uint8_t &status, 
                             uint8_t &wr_status);
    
    
    /**********************************************************//**
    * @brief Write to selected DS28E17's I2C with Data only.  
    * Poll until I2C write complete and receive status info.
    * 
    * @details Output on I2C: Write Data [1-255]
    *
    * On Entry:
    * @param[in]  length
    * The number of data bytes to be written ranging from 01h to FFh.
    * A value of zero will assert the Error Detected pin (ED).
    *
    * @param[in]  *data
    * User defines write data ranging from 1-255 bytes.
    *
    * On Exit:
    * @param[out]  status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] wr_status
    * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
    * A non-zero value indicates the byte number that NACK’d.
    *
    * @return 
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult I2C_WriteDataOnly(uint8_t length, uint8_t *data, 
                           uint8_t &status, uint8_t &wr_status);
    
    
    /**********************************************************//**
    * @brief Write to selected DS28E17's I2C with Stop.  
    * Poll until I2C write complete and receive status info.
    * 
    * @details Output on I2C: Write Data [1-255], P
    *
    * On Entry:
    * @param[in]  length
    * The number of data bytes to be written ranging from 01h to FFh.
    * A value of zero will assert the Error Detected pin (ED).
    *
    * @param[in]  *data
    * User defines write data ranging from 1-255 bytes.
    *
    * On Exit:
    * @param[out]  status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] wr_status
    * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
    * A non-zero value indicates the byte number that NACK’d.
    *
    * @return 
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult I2C_WriteDataOnlyWithStop(uint8_t length, uint8_t *data, 
                                   uint8_t &status, uint8_t &wr_status);
    
    
    /**********************************************************//**
    * @brief Write to selected DS28E17's I2C with Stop and poll until I2C write complete
    * receive status info, and read data with a stop at the end.
    * 
    * @details Output on I2C:
    * S, Slave Address + Write, Write Data [1-255],
    * Sr, Address + Read, Read Data [1-255], P (NACK last read byte)
    *
    * On Entry:
    * @param[in]  I2C_addr
    * Writes I2C address. The least significant bit of the I2C address
    * is automatically cleared by the command.
    *
    * @param[in]  length
    * The number of data bytes to be written ranging from 01h to FFh.
    * A value of zero will assert the Error Detected pin (ED).
    *
    * @param[in]  *data
    * User defines write data ranging from 1-255 bytes.
    *
    * @param[in] nu_bytes_read
    * Number of I2C bytes to read. A value of zero will assert the Error Detected pin (ED).
    *
    * On Exit:
    * @param[out]  status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] wr_status
    * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
    * A non-zero value indicates the byte number that NACK’d.
    *
    * @param[out] *read_data
    * Array of read data received from I2C.
    *
    * @return 
    * true if device selected, written and read @n
    * false if failed device select or timeout occurred or CRC16 error
    **************************************************************/
    CmdResult I2C_WriteReadDataWithStop(uint8_t I2C_addr, uint8_t length, 
                                   uint8_t *data, uint8_t nu_bytes_read, 
                                   uint8_t &status, uint8_t &wr_status, 
                                   uint8_t *read_data);
    
    
    /**********************************************************//**
    * @brief Selected DS28E17's and send I2C address and poll until 
    * I2C read address complete, receive status info, and read data 
    * with a stop at the end.
    * 
    * @details Output on I2C:
    * S, Slave Address + Read, Read Data [1-255], P (NACK last read byte)
    *
    * On Entry:
    * @param[in]  I2C_addr
    * Writes I2C address. The least significant bit of the I2C address
    * is automatically cleared by the command.
    *
    * On Exit:
    * @param[out] nu_bytes_read
    * Number of I2C bytes to read. A value of zero will assert the Error Detected pin (ED).
    *
    * @param[out]  status
    * Detects the condition of the Start (bit3), N/A (bit2), 
    * Address(bit1) and CRC16(bit0) bits.
    * b3;0=No Err|1=I2CStart prev-not issued, 
    * b2;0=No Err|1=I2C N/A Err,
    * b1;0=No Err|1=Addr Err, 
    * b0;0=Valid CRC16|1=Invalid CRC16
    *
    * @param[out] *read_data
    * Array of read data received from I2C.
    *
    * @return 
    * true if device selected, written and read @n
    * false if failed device select or timeout occurred or CRC16 error
    **************************************************************/
    CmdResult I2C_ReadDataWithStop(uint8_t I2C_addr, uint8_t nu_bytes_read, 
                              uint8_t &status, uint8_t *read_data);
    
    
    /**********************************************************//**
    * @brief Write to Configuration Register of DS28E17.
    * 
    * @details 
    *
    * On Entry:
    * @param[in] data
    * sent to configuration register
    *
    * On Exit:
    *
    * @return
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult WriteConfigReg(uint8_t data);
    
    
    /**********************************************************//**
    * @brief Read the Configuration Register of DS28E17.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return 
    * true if device selected and read correctly @n
    * false if failed device select
    **************************************************************/
    CmdResult ReadConfigReg(uint8_t & config);
    
    
    /**********************************************************//**
    * @brief Disable 1-Wire Mode DS28E17 and activates the input detection pin.
    * Immediately after the command, all 1-Wire signaling will be ignored
    * until the 1W_DET pin is high for more than 3ms.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return
    * true if device selected and written @n
    * false if failed device select
    **************************************************************/
    CmdResult DisableOWMode();
    
    
    /**********************************************************//**
    * @brief The Enable Sleep Mode command puts the device into a low current mode.
    * All 1-Wire communication is ignored until woken up. Immediately after
    * the command, the device monitors the WAKEUP input pin and
    * exits sleep mode on a rising edge.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return
    * true if device selected and written @n
    * false if failed device select*    
    **************************************************************/
    CmdResult EnableSleepMode();
    
    
    /**********************************************************//**
    * @brief Read the Device Revision of DS28E17. The revision value 
    *  should never be zero.  The upper nibble is the major revision 
    *  and the lower nibble is the minor revision.
    * 
    * @details 
    *
    * On Entry:
    *
    * On Exit:
    *
    * @return
    * revision value if device selected and read correctly @n
    * false if failed device select (i.e. 00h)
    **************************************************************/
    CmdResult ReadDeviceRevision(uint8_t & rev);
    
    private:
    
    CmdResult send_packet(const uint8_t * data, uint8_t data_length, 
                          uint8_t & status, uint8_t & wr_status);
    
    //overloaded function for I2C read only command 
    CmdResult send_packet(const uint8_t * data, uint8_t data_length, 
                          uint8_t & status);
    
    OneWireInterface &_owm;
    RomId _romId;
    
    uint16_t _crc16;
    uint8_t _i2c_speed;
    
    static const uint16_t _oddparity[16];
    
    uint16_t docrc16(uint16_t data);
};

#endif /*DS28E17_H*/