DS28E17.h

00001 /******************************************************************//**
00002 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
00003 *
00004 * Permission is hereby granted, free of charge, to any person obtaining a
00005 * copy of this software and associated documentation files (the "Software"),
00006 * to deal in the Software without restriction, including without limitation
00007 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00008 * and/or sell copies of the Software, and to permit persons to whom the
00009 * Software is furnished to do so, subject to the following conditions:
00010 *
00011 * The above copyright notice and this permission notice shall be included
00012 * in all copies or substantial portions of the Software.
00013 *
00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00015 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00016 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00017 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00018 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00019 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00020 * OTHER DEALINGS IN THE SOFTWARE.
00021 *
00022 * Except as contained in this notice, the name of Maxim Integrated
00023 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00024 * Products, Inc. Branding Policy.
00025 *
00026 * The mere transfer of this software does not imply any licenses
00027 * of trade secrets, proprietary technology, copyrights, patents,
00028 * trademarks, maskwork rights, or any other form of intellectual
00029 * property whatsoever. Maxim Integrated Products, Inc. retains all
00030 * ownership rights.
00031 **********************************************************************/
00032 
00033 #ifndef OneWire_Bridge_DS28E17
00034 #define OneWire_Bridge_DS28E17
00035 
00036 #include <stdint.h>
00037 #include <stddef.h>
00038 #include "Slaves/OneWireSlave.h"
00039 
00040 namespace OneWire
00041 {
00042     class OneWireMaster;
00043     
00044     /**
00045     * @brief DS28E17 1-Wire®-to-I2C Master Bridge
00046     *
00047     * @details The DS28E17 is a 1-Wire slave to I2C master bridge 
00048     * device that interfaces directly to I2C slaves at standard 
00049     * (100kHz max) or fast (400kHz max). Data transfers serially by 
00050     * means of the 1-Wire® protocol, which requires only a single data 
00051     * lead and a ground return. Every DS28E17 is guaranteed to have a 
00052     * unique 64-bit ROM registration number that serves as a node 
00053     * address in the 1-Wire network. Multiple DS28E17 devices can 
00054     * coexist with other devices in the 1-Wire network and be accessed 
00055     * individually without affecting other devices. The DS28E17 allows 
00056     * using complex I2C devices such as display controllers, ADCs, DACs,
00057     * I2C sensors, etc. in a 1-Wire environment. Each self-timed DS28E17 
00058     * provides 1-Wire access for a single I2C interface.
00059     *
00060     */
00061     class DS28E17 : public OneWireSlave
00062     {
00063     public:
00064         
00065         ///Result of all operations
00066         enum CmdResult
00067         {
00068             Success,
00069             CommsReadBitError,
00070             CommsWriteBitError,
00071             CommsReadByteError,
00072             CommsWriteByteError,
00073             CommsReadBlockError,
00074             CommsWriteBlockError,
00075             TimeoutError,
00076             OperationFailure
00077         };
00078 
00079         /**********************************************************//**
00080         * @brief DS28E17 constructor
00081         *
00082         *
00083         * On Entry:
00084         * @param[in] selector - RandomAccessRomIterator object that 
00085         * encapsulates master associated with this device and rom control 
00086         * commands
00087         **************************************************************/
00088         DS28E17(RandomAccessRomIterator &selector);
00089 
00090         /**********************************************************//**
00091         * @brief Write to selected DS28E17's I2C with Stop.
00092         * Poll until I2C write complete and receive status info.
00093         *
00094         * @details Output on I2C: S, Address + Write, Write Data [1-255], P
00095         *
00096         * On Entry:
00097         * @param[in]  I2C_addr -
00098         * Writes I2C address. The least significant bit of the I2C
00099         * address is automatically cleared by the command.
00100         *
00101         * @param[in] length
00102         * The number of data bytes to be written ranging from 01h to FFh.
00103         * A value of zero will assert the Error Detected pin (ED).
00104         *
00105         * @param[in] *data
00106         * User defines write data ranging from 1-255 bytes.
00107         *
00108         * On Exit:
00109         * @param[out] status
00110         * Detects the condition of the Start (bit3), N/A (bit2),
00111         * Address(bit1) and CRC16(bit0) bits.
00112         * b3;0=No Err|1=I2CStart prev-not issued,
00113         * b2;0=No Err|1=I2C N/A Err,
00114         * b1;0=No Err|1=Addr Err,
00115         * b0;0=Valid CRC16|1=Invalid CRC16
00116         *
00117         * @param[out] wr_status
00118         * Indicates which write byte NACK’d. A value of 00h indicates
00119         * all bytes were acknowledged by the slave.
00120         * A non-zero value indicates the byte number that NACK’d.
00121         *
00122         * @return CmdResult - result of operation
00123         **************************************************************/
00124         CmdResult writeDataWithStop(uint8_t I2C_addr, uint8_t length,
00125                                         uint8_t *data, uint8_t &status,
00126                                         uint8_t &wr_status);
00127 
00128         /**********************************************************//**
00129         * @brief Write to selected DS28E17's I2C No Stop.
00130         * Poll until I2C write complete and receive status info.
00131         *
00132         * @details Output on I2C: S, Address + Write, Write Data [1-255]
00133         *
00134         * On Entry:
00135         * @param[in]  I2C_addr
00136         * Writes I2C address. The least significant bit of the I2C address
00137         * is automatically cleared by the command.
00138         *
00139         * @param[in]  length
00140         * The number of data bytes to be written ranging from 01h to FFh.
00141         * A value of zero will assert the Error Detected pin (ED).
00142         *
00143         * @param[in]  *data
00144         * User defines write data ranging from 1-255 bytes.
00145         *
00146         * On Exit:
00147         * @param[out]  status
00148         * Detects the condition of the Start (bit3), N/A (bit2),
00149         * Address(bit1) and CRC16(bit0) bits.
00150         * b3;0=No Err|1=I2CStart prev-not issued,
00151         * b2;0=No Err|1=I2C N/A Err,
00152         * b1;0=No Err|1=Addr Err,
00153         * b0;0=Valid CRC16|1=Invalid CRC16
00154         *
00155         * @param[out] wr_status
00156         * Indicates which write byte NACK’d. A value of 00h indicates
00157         * all bytes were acknowledged by the slave.
00158         * A non-zero value indicates the byte number that NACK’d.
00159         *
00160         * @return CmdResult - result of operation
00161         **************************************************************/
00162         CmdResult writeDataNoStop(uint8_t I2C_addr, uint8_t length,
00163                                       uint8_t *data, uint8_t &status,
00164                                       uint8_t &wr_status);
00165 
00166 
00167         /**********************************************************//**
00168         * @brief Write to selected DS28E17's I2C with Data only.
00169         * Poll until I2C write complete and receive status info.
00170         *
00171         * @details Output on I2C: Write Data [1-255]
00172         *
00173         * On Entry:
00174         * @param[in]  length
00175         * The number of data bytes to be written ranging from 01h to FFh.
00176         * A value of zero will assert the Error Detected pin (ED).
00177         *
00178         * @param[in]  *data
00179         * User defines write data ranging from 1-255 bytes.
00180         *
00181         * On Exit:
00182         * @param[out]  status
00183         * Detects the condition of the Start (bit3), N/A (bit2),
00184         * Address(bit1) and CRC16(bit0) bits.
00185         * b3;0=No Err|1=I2CStart prev-not issued,
00186         * b2;0=No Err|1=I2C N/A Err,
00187         * b1;0=No Err|1=Addr Err,
00188         * b0;0=Valid CRC16|1=Invalid CRC16
00189         *
00190         * @param[out] wr_status
00191         * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
00192         * A non-zero value indicates the byte number that NACK’d.
00193         *
00194         * @return CmdResult - result of operation
00195         **************************************************************/
00196         CmdResult writeDataOnly(uint8_t length, uint8_t *data,
00197                                     uint8_t &status, uint8_t &wr_status);
00198 
00199 
00200         /**********************************************************//**
00201         * @brief Write to selected DS28E17's I2C with Stop.
00202         * Poll until I2C write complete and receive status info.
00203         *
00204         * @details Output on I2C: Write Data [1-255], P
00205         *
00206         * On Entry:
00207         * @param[in]  length
00208         * The number of data bytes to be written ranging from 01h to FFh.
00209         * A value of zero will assert the Error Detected pin (ED).
00210         *
00211         * @param[in]  *data
00212         * User defines write data ranging from 1-255 bytes.
00213         *
00214         * On Exit:
00215         * @param[out]  status
00216         * Detects the condition of the Start (bit3), N/A (bit2),
00217         * Address(bit1) and CRC16(bit0) bits.
00218         * b3;0=No Err|1=I2CStart prev-not issued,
00219         * b2;0=No Err|1=I2C N/A Err,
00220         * b1;0=No Err|1=Addr Err,
00221         * b0;0=Valid CRC16|1=Invalid CRC16
00222         *
00223         * @param[out] wr_status
00224         * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
00225         * A non-zero value indicates the byte number that NACK’d.
00226         *
00227         * @return CmdResult - result of operation
00228         **************************************************************/
00229         CmdResult writeDataOnlyWithStop(uint8_t length, uint8_t *data,
00230                                             uint8_t &status, uint8_t &wr_status);
00231 
00232 
00233         /**********************************************************//**
00234         * @brief Write to selected DS28E17's I2C with Stop and poll until I2C write complete
00235         * receive status info, and read data with a stop at the end.
00236         *
00237         * @details Output on I2C:
00238         * S, Slave Address + Write, Write Data [1-255],
00239         * Sr, Address + Read, Read Data [1-255], P (NACK last read byte)
00240         *
00241         * On Entry:
00242         * @param[in]  I2C_addr
00243         * Writes I2C address. The least significant bit of the I2C address
00244         * is automatically cleared by the command.
00245         *
00246         * @param[in]  length
00247         * The number of data bytes to be written ranging from 01h to FFh.
00248         * A value of zero will assert the Error Detected pin (ED).
00249         *
00250         * @param[in]  *data
00251         * User defines write data ranging from 1-255 bytes.
00252         *
00253         * @param[in] nu_bytes_read
00254         * Number of I2C bytes to read. A value of zero will assert the Error Detected pin (ED).
00255         *
00256         * On Exit:
00257         * @param[out]  status
00258         * Detects the condition of the Start (bit3), N/A (bit2),
00259         * Address(bit1) and CRC16(bit0) bits.
00260         * b3;0=No Err|1=I2CStart prev-not issued,
00261         * b2;0=No Err|1=I2C N/A Err,
00262         * b1;0=No Err|1=Addr Err,
00263         * b0;0=Valid CRC16|1=Invalid CRC16
00264         *
00265         * @param[out] wr_status
00266         * Indicates which write byte NACK’d. A value of 00h indicates all bytes were acknowledged by the slave.
00267         * A non-zero value indicates the byte number that NACK’d.
00268         *
00269         * @param[out] *read_data
00270         * Array of read data received from I2C.
00271         *
00272         * @return CmdResult - result of operation
00273         **************************************************************/
00274         CmdResult writeReadDataWithStop(uint8_t I2C_addr, uint8_t length,
00275                                             uint8_t *data, uint8_t nu_bytes_read,
00276                                             uint8_t &status, uint8_t &wr_status,
00277                                             uint8_t *read_data);
00278 
00279 
00280         /**********************************************************//**
00281         * @brief Selected DS28E17's and send I2C address and poll until
00282         * I2C read address complete, receive status info, and read data
00283         * with a stop at the end.
00284         *
00285         * @details Output on I2C:
00286         * S, Slave Address + Read, Read Data [1-255], P (NACK last read byte)
00287         *
00288         * On Entry:
00289         * @param[in]  I2C_addr
00290         * Defines the 7-bit I2C address to be written. 
00291         * The least significant bit must be set, indicating an I2C read.
00292         *
00293         * On Exit:
00294         * @param[out] nu_bytes_read
00295         * Number of I2C bytes to read. A value of zero will assert the Error Detected pin (ED).
00296         *
00297         * @param[out]  status
00298         * Detects the condition of the Start (bit3), N/A (bit2),
00299         * Address(bit1) and CRC16(bit0) bits.
00300         * b3;0=No Err|1=I2CStart prev-not issued,
00301         * b2;0=No Err|1=I2C N/A Err,
00302         * b1;0=No Err|1=Addr Err,
00303         * b0;0=Valid CRC16|1=Invalid CRC16
00304         *
00305         * @param[out] *read_data
00306         * Array of read data received from I2C.
00307         *
00308         * @return CmdResult - result of operation
00309         **************************************************************/
00310         CmdResult readDataWithStop(uint8_t I2C_addr, uint8_t nu_bytes_read,
00311                                        uint8_t &status, uint8_t *read_data);
00312 
00313 
00314         /**********************************************************//**
00315         * @brief Write to Configuration Register of DS28E17.
00316         *
00317         * @details
00318         *
00319         * On Entry:
00320         * @param[in] data
00321         * sent to configuration register
00322         *
00323         * @return CmdResult - result of operation
00324         **************************************************************/
00325         CmdResult writeConfigReg(uint8_t data);
00326 
00327 
00328         /**********************************************************//**
00329         * @brief Read the Configuration Register of DS28E17.
00330         *
00331         * @details
00332         *
00333         * On Exit:
00334         * @param[out] config - contents of configuration register
00335         *
00336         * @return CmdResult - result of operation
00337         **************************************************************/
00338         CmdResult readConfigReg(uint8_t & config);
00339 
00340 
00341         /**********************************************************//**
00342         * @brief The Enable Sleep Mode command puts the device into a low current mode.
00343         * All 1-Wire communication is ignored until woken up. Immediately after
00344         * the command, the device monitors the WAKEUP input pin and
00345         * exits sleep mode on a rising edge.
00346         *
00347         * @return CmdResult - result of operation
00348         **************************************************************/
00349         CmdResult enableSleepMode();
00350 
00351 
00352         /**********************************************************//**
00353         * @brief Read the Device Revision of DS28E17. The revision value
00354         *  should never be zero.  The upper nibble is the major revision
00355         *  and the lower nibble is the minor revision.
00356         *
00357         * On Exit:
00358         * @param[out] rev - device revision
00359         *
00360         * @return CmdResult - result of operation
00361         **************************************************************/
00362         CmdResult readDeviceRevision(uint8_t & rev);
00363 
00364     private:
00365         static const size_t pollLimit = 10000;
00366 
00367         CmdResult sendPacket(const uint8_t * data, uint8_t data_length,
00368                               uint8_t & status, uint8_t & wr_status);
00369 
00370         //overloaded function for I2C read only command 
00371         CmdResult sendPacket(const uint8_t * data, uint8_t data_length,
00372                               uint8_t & status);
00373     };
00374 }
00375 
00376 #endif
00377