DS28E17.hpp

00001 /*******************************************************************************
00002 * Copyright (C) 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 MaximInterfaceDevices_DS28E17_hpp
00034 #define MaximInterfaceDevices_DS28E17_hpp
00035 
00036 #include <stdint.h>
00037 #include <MaximInterfaceCore/SelectRom.hpp>
00038 #include <MaximInterfaceCore/span.hpp>
00039 #include "Config.hpp"
00040 
00041 namespace MaximInterfaceDevices {
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   // Values from 1-255 represent the Write Status byte.
00059   enum ErrorValue {
00060     TimeoutError = 256,
00061     OutOfRangeError,
00062     InvalidCrc16Error,
00063     AddressNackError,
00064     InvalidStartError
00065   };
00066 
00067   enum I2CSpeed { Speed100kHz, Speed400kHz, Speed900kHz };
00068 
00069   DS28E17(Core::OneWireMaster & master, const Core::SelectRom & selectRom)
00070       : selectRom(selectRom), master(&master) {}
00071 
00072   void setMaster(Core::OneWireMaster & master) { this->master = &master; }
00073 
00074   void setSelectRom(const Core::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   /// @returns
00085   /// Values from 1-255 in the DS28E17 category represent the Write Status
00086   /// indicating which write byte did not acknowledge.
00087   MaximInterfaceDevices_EXPORT Core::Result<void>
00088   writeDataWithStop(uint_least8_t I2C_addr,
00089                     Core::span<const uint_least8_t> data);
00090 
00091   /// @brief Write Data No Stop command.
00092   /// @details Output on I2C: S, Address + Write, Write Data [1-255]
00093   /// @param[in] I2C_addr
00094   /// I2C slave address. The least significant bit of the I2C address
00095   /// is automatically cleared by the command.
00096   /// @param[in] data I2C data to write with length 1-255.
00097   /// @returns
00098   /// Values from 1-255 in the DS28E17 category represent the Write Status
00099   /// indicating which write byte did not acknowledge.
00100   MaximInterfaceDevices_EXPORT Core::Result<void>
00101   writeDataNoStop(uint_least8_t I2C_addr, Core::span<const uint_least8_t> data);
00102 
00103   /// @brief Write Data Only command.
00104   /// @details Output on I2C: Write Data [1-255]
00105   /// @param[in] data I2C data to write with length 1-255.
00106   /// @returns
00107   /// Values from 1-255 in the DS28E17 category represent the Write Status
00108   /// indicating which write byte did not acknowledge.
00109   MaximInterfaceDevices_EXPORT Core::Result<void>
00110   writeDataOnly(Core::span<const uint_least8_t> data);
00111 
00112   /// @brief Write Data Only With Stop command.
00113   /// @details Output on I2C: Write Data [1-255], P
00114   /// @param[in] data I2C data to write with length 1-255.
00115   /// @returns
00116   /// Values from 1-255 in the DS28E17 category represent the Write Status
00117   /// indicating which write byte did not acknowledge.
00118   MaximInterfaceDevices_EXPORT Core::Result<void>
00119   writeDataOnlyWithStop(Core::span<const uint_least8_t> data);
00120 
00121   /// @brief Write, Read Data With Stop command.
00122   /// @details Output on I2C:
00123   /// S, Slave Address + Write, Write Data [1-255],
00124   /// Sr, Address + Read, Read Data [1-255], P (NACK last read byte)
00125   /// @param[in] I2C_addr
00126   /// I2C slave address. The least significant bit of the I2C address
00127   /// is automatically cleared and set by the command.
00128   /// @param[in] write_data I2C data to write with length 1-255.
00129   /// @param[out] read_data I2C data that was read with length 1-255.
00130   /// @returns
00131   /// Values from 1-255 in the DS28E17 category represent the Write Status
00132   /// indicating which write byte did not acknowledge.
00133   MaximInterfaceDevices_EXPORT Core::Result<void>
00134   writeReadDataWithStop(uint_least8_t I2C_addr,
00135                         Core::span<const uint_least8_t> write_data,
00136                         Core::span<uint_least8_t> read_data);
00137 
00138   /// @brief Read Data With Stop command.
00139   /// @details Output on I2C:
00140   /// S, Slave Address + Read, Read Data [1-255], P (NACK last read byte)
00141   /// @param[in]  I2C_addr
00142   /// I2C slave address. The least significant bit of the I2C address
00143   /// is automatically set by the command.
00144   /// @param[out] data I2C data that was read with length 1-255.
00145   MaximInterfaceDevices_EXPORT Core::Result<void>
00146   readDataWithStop(uint_least8_t I2C_addr, Core::span<uint_least8_t> data);
00147 
00148   /// Write to Configuration Register of DS28E17.
00149   MaximInterfaceDevices_EXPORT Core::Result<void>
00150   writeConfigReg(I2CSpeed speed);
00151 
00152   /// @brief Read the Configuration Register of DS28E17.
00153   /// @returns speed Speed read from configuration register.
00154   MaximInterfaceDevices_EXPORT Core::Result<I2CSpeed> readConfigReg() const;
00155 
00156   /// @brief Put the device into a low current mode.
00157   /// @details All 1-Wire communication is ignored until woken up. Immediately
00158   /// after the command, the device monitors the WAKEUP input pin and exits
00159   /// sleep mode on a rising edge.
00160   MaximInterfaceDevices_EXPORT Core::Result<void> enableSleepMode();
00161 
00162   /// @brief Read the Device Revision of DS28E17.
00163   /// @details The upper nibble is the major revision,
00164   /// and the lower nibble is the minor revision.
00165   /// @returns Device Revision.
00166   MaximInterfaceDevices_EXPORT Core::Result<uint_least8_t>
00167   readDeviceRevision() const;
00168 
00169   MaximInterfaceDevices_EXPORT static const Core::error_category &
00170   errorCategory();
00171 
00172 private:
00173   enum Command {
00174     WriteDataWithStopCmd = 0x4B,
00175     WriteDataNoStopCmd = 0x5A,
00176     WriteDataOnlyCmd = 0x69,
00177     WriteDataOnlyWithStopCmd = 0x78,
00178     ReadDataWithStopCmd = 0x87,
00179     WriteReadDataWithStopCmd = 0x2D,
00180     WriteConfigurationCmd = 0xD2,
00181     ReadConfigurationCmd = 0xE1,
00182     EnableSleepModeCmd = 0x1E,
00183     ReadDeviceRevisionCmd = 0xC3
00184   };
00185 
00186   Core::Result<void> sendPacket(Command command, const uint_least8_t * I2C_addr,
00187                                 Core::span<const uint_least8_t> write_data,
00188                                 Core::span<uint_least8_t> read_data);
00189 
00190   Core::SelectRom selectRom;
00191   Core::OneWireMaster * master;
00192 };
00193 
00194 } // namespace MaximInterfaceDevices
00195 namespace MaximInterfaceCore {
00196 
00197 template <>
00198 struct is_error_code_enum<MaximInterfaceDevices::DS28E17::ErrorValue>
00199     : true_type {};
00200 
00201 } // namespace MaximInterfaceCore
00202 namespace MaximInterfaceDevices {
00203 
00204 inline Core::error_code make_error_code(DS28E17::ErrorValue e) {
00205   return Core::error_code(e, DS28E17::errorCategory());
00206 }
00207 
00208 } // namespace MaximInterfaceDevices
00209 
00210 #endif