DS28E17.hpp

00001 /*******************************************************************************
00002 * Copyright (C) 2017 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 MaximInterface_DS28E17
00034 #define MaximInterface_DS28E17
00035 
00036 #include <stdint.h>
00037 #include <MaximInterface/Links/SelectRom.hpp>
00038 #include <MaximInterface/Utilities/Export.h>
00039 #include <MaximInterface/Utilities/span.hpp>
00040 
00041 namespace MaximInterface {
00042 
00043 /// @brief DS28E17 1-Wire®-to-I2C Master Bridge
00044 /// @details The DS28E17 is a 1-Wire slave to I2C master bridge
00045 /// device that interfaces directly to I2C slaves at standard
00046 /// (100kHz max) or fast (400kHz max). Data transfers serially by
00047 /// means of the 1-Wire® protocol, which requires only a single data
00048 /// lead and a ground return. Every DS28E17 is guaranteed to have a
00049 /// unique 64-bit ROM registration number that serves as a node
00050 /// address in the 1-Wire network. Multiple DS28E17 devices can
00051 /// coexist with other devices in the 1-Wire network and be accessed
00052 /// individually without affecting other devices. The DS28E17 allows
00053 /// using complex I2C devices such as display controllers, ADCs, DACs,
00054 /// I2C sensors, etc. in a 1-Wire environment. Each self-timed DS28E17
00055 /// provides 1-Wire access for a single I2C interface.
00056 class DS28E17 {
00057 public:
00058   enum ErrorValue {
00059     TimeoutError = 1,
00060     OutOfRangeError,
00061     InvalidCrc16Error,
00062     AddressNackError,
00063     InvalidStartError,
00064     WriteNackError
00065   };
00066 
00067   enum I2CSpeed { Speed100kHz, Speed400kHz, Speed900kHz };
00068 
00069   DS28E17(OneWireMaster & master, const SelectRom & selectRom)
00070       : selectRom(selectRom), master(&master) {}
00071 
00072   void setMaster(OneWireMaster & master) { this->master = &master; }
00073   
00074   void setSelectRom(const SelectRom & selectRom) {
00075     this->selectRom = selectRom;
00076   }
00077 
00078   /// @brief Write Data With Stop command.
00079   /// @details Output on I2C: S, Address + Write, Write Data [1-255], P
00080   /// @param[in] I2C_addr
00081   /// I2C slave address. The least significant bit of the I2C
00082   /// address is automatically cleared by the command.
00083   /// @param[in] data I2C data to write with length 1-255.
00084   /// @param[out] wr_status
00085   /// Indicates which write byte NACK’d. A value of 00h indicates all bytes
00086   /// were acknowledged by the slave. A non-zero value indicates the byte number
00087   /// that NACK’d. May be set to NULL.
00088   MaximInterface_EXPORT error_code
00089   writeDataWithStop(uint_least8_t I2C_addr, span<const uint_least8_t> data,
00090                     uint_least8_t * wr_status = NULL);
00091 
00092   /// @brief Write Data No Stop command.
00093   /// @details Output on I2C: S, Address + Write, Write Data [1-255]
00094   /// @param[in] I2C_addr
00095   /// I2C slave address. The least significant bit of the I2C address
00096   /// is automatically cleared by the command.
00097   /// @param[in] data I2C data to write with length 1-255.
00098   /// @param[out] wr_status
00099   /// Indicates which write byte NACK’d. A value of 00h indicates all bytes
00100   /// were acknowledged by the slave. A non-zero value indicates the byte number
00101   /// that NACK’d. May be set to NULL.
00102   MaximInterface_EXPORT error_code
00103   writeDataNoStop(uint_least8_t I2C_addr, span<const uint_least8_t> data,
00104                   uint_least8_t * wr_status = NULL);
00105 
00106   /// @brief Write Data Only command.
00107   /// @details Output on I2C: Write Data [1-255]
00108   /// @param[in] data I2C data to write with length 1-255.
00109   /// @param[out] wr_status
00110   /// Indicates which write byte NACK’d. A value of 00h indicates all bytes
00111   /// were acknowledged by the slave. A non-zero value indicates the byte number
00112   /// that NACK’d. May be set to NULL.
00113   MaximInterface_EXPORT error_code
00114   writeDataOnly(span<const uint_least8_t> data,
00115                 uint_least8_t * wr_status = NULL);
00116 
00117   /// @brief Write Data Only With Stop command.
00118   /// @details Output on I2C: Write Data [1-255], P
00119   /// @param[in] data I2C data to write with length 1-255.
00120   /// @param[out] wr_status
00121   /// Indicates which write byte NACK’d. A value of 00h indicates all bytes
00122   /// were acknowledged by the slave. A non-zero value indicates the byte number
00123   /// that NACK’d. May be set to NULL.
00124   MaximInterface_EXPORT error_code
00125   writeDataOnlyWithStop(span<const uint_least8_t> data,
00126                         uint_least8_t * wr_status = NULL);
00127 
00128   /// @brief Write, Read Data With Stop command.
00129   /// @details Output on I2C:
00130   /// S, Slave Address + Write, Write Data [1-255],
00131   /// Sr, Address + Read, Read Data [1-255], P (NACK last read byte)
00132   /// @param[in] I2C_addr
00133   /// I2C slave address. The least significant bit of the I2C address
00134   /// is automatically cleared and set by the command.
00135   /// @param[in] write_data I2C data to write with length 1-255.
00136   /// @param[out] read_data I2C data that was read with length 1-255.
00137   /// @param[out] wr_status
00138   /// Indicates which write byte NACK’d. A value of 00h indicates all bytes
00139   /// were acknowledged by the slave. A non-zero value indicates the byte number
00140   /// that NACK’d. May be set to NULL.
00141   MaximInterface_EXPORT error_code writeReadDataWithStop(
00142       uint_least8_t I2C_addr, span<const uint_least8_t> write_data,
00143       span<uint_least8_t> read_data, uint_least8_t * wr_status = NULL);
00144 
00145   /// @brief Read Data With Stop command.
00146   /// @details Output on I2C:
00147   /// S, Slave Address + Read, Read Data [1-255], P (NACK last read byte)
00148   /// @param[in]  I2C_addr
00149   /// I2C slave address. The least significant bit of the I2C address
00150   /// is automatically set by the command.
00151   /// @param[out] data I2C data that was read with length 1-255.
00152   MaximInterface_EXPORT error_code readDataWithStop(uint_least8_t I2C_addr,
00153                                                     span<uint_least8_t> data);
00154 
00155   /// Write to Configuration Register of DS28E17.
00156   MaximInterface_EXPORT error_code writeConfigReg(I2CSpeed speed);
00157 
00158   /// @brief Read the Configuration Register of DS28E17.
00159   /// @param[out] speed Speed read from configuration register.
00160   MaximInterface_EXPORT error_code readConfigReg(I2CSpeed & speed);
00161 
00162   /// @brief Put the device into a low current mode.
00163   /// @details All 1-Wire communication is ignored until woken up. Immediately
00164   /// after the command, the device monitors the WAKEUP input pin and exits
00165   /// sleep mode on a rising edge.
00166   MaximInterface_EXPORT error_code enableSleepMode();
00167 
00168   /// @brief Read the Device Revision of DS28E17.
00169   /// @details The upper nibble is the major revision,
00170   /// and the lower nibble is the minor revision.
00171   /// @param[out] rev Device Revision.
00172   MaximInterface_EXPORT error_code readDeviceRevision(uint_least8_t & rev);
00173 
00174   MaximInterface_EXPORT static const error_category & errorCategory();
00175 
00176 private:
00177   enum Command {
00178     WriteDataWithStopCmd = 0x4B,
00179     WriteDataNoStopCmd = 0x5A,
00180     WriteDataOnlyCmd = 0x69,
00181     WriteDataOnlyWithStopCmd = 0x78,
00182     ReadDataWithStopCmd = 0x87,
00183     WriteReadDataWithStopCmd = 0x2D,
00184     WriteConfigurationCmd = 0xD2,
00185     ReadConfigurationCmd = 0xE1,
00186     EnableSleepModeCmd = 0x1E,
00187     ReadDeviceRevisionCmd = 0xC3
00188   };
00189 
00190   error_code sendPacket(Command command, const uint_least8_t * I2C_addr,
00191                         span<const uint_least8_t> write_data,
00192                         span<uint_least8_t> read_data,
00193                         uint_least8_t * wr_status);
00194 
00195   SelectRom selectRom;
00196   OneWireMaster * master;
00197 };
00198 
00199 inline error_code make_error_code(DS28E17::ErrorValue e) {
00200   return error_code(e, DS28E17::errorCategory());
00201 }
00202 
00203 } // namespace MaximInterface
00204 
00205 #endif