Superseded by MaximInterface.

Diff: Masters/OneWireMaster.h

Revision:

73:2cecc1372acc

Parent:

72:6892702709ee

Child:

74:23be10c32fa3

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Masters/OneWireMaster.h	Thu May 12 14:38:16 2016 -0500
@@ -0,0 +1,468 @@
+/******************************************************************//**
+* 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 OneWire_Masters_OneWireMaster
+#define OneWire_Masters_OneWireMaster
+
+#include <stdint.h>
+#include <stddef.h>
+
+#include "RomId.h"
+
+namespace OneWire
+{
+    namespace Masters
+    {
+        /// Base class for all 1-Wire Masters.
+        class OneWireMaster
+        {   
+        public:
+            
+            /// Speed of the 1-Wire bus
+            enum OWSpeed
+            {
+                SPEED_STANDARD = 0x00,
+                SPEED_OVERDRIVE = 0x01
+            };
+            
+            /// Level of the 1-Wire bus
+            enum OWLevel
+            {
+                LEVEL_NORMAL = 0x00,
+                LEVEL_STRONG = 0x02,
+                LEVEL_PROGRAM = 0x04,
+            };
+            
+            /// Search direction for the Triplet
+            enum SearchDirection
+            {
+                DIRECTION_WRITE_ZERO = 0,
+                DIRECTION_WRITE_ONE = 1
+            };
+            
+            /// Result of all 1-Wire commands
+            enum CmdResult
+            {
+                Success,
+                CommunicationWriteError,
+                CommunicationReadError,
+                TimeoutError,
+                OperationFailure
+            };
+            
+            /// State used by all ROM ID search functions.
+            struct SearchState
+            {
+                RomId romId;
+                uint8_t last_discrepancy;
+                uint8_t last_family_discrepancy;
+                bool last_device_flag;
+                
+                /// Reset to the search state to start at the beginning.
+                void reset()
+                {
+                    last_discrepancy = 0;
+                    last_device_flag = false;
+                    last_family_discrepancy = 0;
+                    romId.reset();
+                }
+                
+                SearchState() { reset(); }
+            };
+            
+            /// Perform a CRC16 calculation.
+            /// @param CRC16 Beginning state of the CRC generator.
+            /// @param data Data to pass though the CRC generator.
+            /// @returns The calculated CRC16.
+            static uint16_t calculateCRC16(uint16_t CRC16, uint16_t data);
+            
+            /// Perform a CRC16 calculation with variable length data.
+            /// @param[in] data Data array to pass through the CRC generator.
+            /// @param data_offset Offset of the data array to begin processing.
+            /// @param data_len Length of the data array to process.
+            /// @param crc Beginning state of the CRC generator.
+            /// @returns The calculated CRC16.
+            static uint16_t calculateCRC16(const uint8_t * data, size_t data_offset, size_t data_len, uint16_t crc = 0);
+            
+            /// Allow freeing through a base class pointer.
+            virtual ~OneWireMaster() { }
+            
+            
+            /**********************************************************//**
+            * @brief OWInitMaster()
+            * 
+            * @details Initiializes particular master being instaniated.
+            *  Added to interface to provide a common 'init' function between
+            *  all masters
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            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:
+            *
+            * @returns OperationFailure if reset was performed but no
+            *          presence pulse was detected.
+            **************************************************************/
+            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:
+            *
+            **************************************************************/
+            virtual CmdResult OWTouchBitSetLevel(uint8_t & sendrecvbit, OWLevel after_level) = 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:
+            *
+            **************************************************************/
+            virtual CmdResult OWWriteByteSetLevel(uint8_t sendbyte, OWLevel after_level) = 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:
+            *
+            **************************************************************/
+            virtual CmdResult OWReadByteSetLevel(uint8_t & recvbyte, OWLevel after_level) = 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:
+            *
+            **************************************************************/
+            virtual CmdResult OWWriteBlock(const uint8_t *tran_buf, uint8_t tran_len);
+            
+            
+            /**********************************************************//**
+            * @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:
+            *  
+            **************************************************************/
+            virtual CmdResult OWReadBlock(uint8_t *rx_buf, uint8_t rx_len);
+            
+            
+            /**********************************************************//**
+            * @brief OWSetSpeed()
+            * 
+            * @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:
+            *
+            **************************************************************/
+            virtual CmdResult OWSetSpeed(OWSpeed new_speed) = 0;
+            
+            
+            /**********************************************************//**
+            * @brief OWSetLevel()
+            *
+            * @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:
+            *
+            **************************************************************/
+            virtual CmdResult OWSetLevel(OWLevel new_level) = 0;
+            
+            
+            /**********************************************************//**
+            * @brief OWTriplet()
+            * 
+            * @details Perform one bit of a 1-Wire search. This command
+            * does two read bits and one write bit. The write bit is either
+            * the default direction (all device have same bit) or in case
+            * of a discrepancy, the 'search_direction' parameter is used.
+            * 
+            * @param[in,out] search_direction
+            * Input with desired direction in case both read bits are zero.
+            * Output with direction taken based on read bits.
+            * 
+            * @param[out] sbr Bit result of first read operation.
+            * @param[out] tsb Bit result of second read operation.
+            **************************************************************/
+            virtual CmdResult OWTriplet(SearchDirection & search_direction, uint8_t & sbr, uint8_t & tsb);
+            
+            /// OWWriteBit()
+            CmdResult OWWriteBitSetLevel(uint8_t sendbit, OWLevel after_level) { return OWTouchBitSetLevel(sendbit, after_level); }
+            
+            /// OWReadBit()
+            CmdResult OWReadBitSetLevel(uint8_t & recvbit, OWLevel after_level) { recvbit = 0x01; return OWTouchBitSetLevel(recvbit, after_level); }
+            
+            // Alternate forms of read and write functions
+            CmdResult OWWriteBit(uint8_t sendbit) { return OWWriteBitSetLevel(sendbit, LEVEL_NORMAL); }
+            CmdResult OWReadBit(uint8_t & recvbit) { return OWReadBitSetLevel(recvbit, LEVEL_NORMAL); }
+            CmdResult OWWriteBitPower(uint8_t sendbit) { return OWWriteBitSetLevel(sendbit, LEVEL_STRONG); }
+            CmdResult OWReadBitPower(uint8_t & recvbit) { return OWReadBitSetLevel(recvbit, LEVEL_STRONG); }
+            CmdResult OWWriteByte(uint8_t sendbyte) { return OWWriteByteSetLevel(sendbyte, LEVEL_NORMAL); }
+            CmdResult OWReadByte(uint8_t & recvbyte) { return OWReadByteSetLevel(recvbyte, LEVEL_NORMAL); }
+            CmdResult OWWriteBytePower(uint8_t sendbyte) { return OWWriteByteSetLevel(sendbyte, LEVEL_STRONG); }
+            CmdResult OWReadBytePower(uint8_t & recvbyte) { return OWReadByteSetLevel(recvbyte, LEVEL_STRONG); }
+            
+            /**********************************************************//**
+            * @brief OWFirst()
+            * 
+            * @details Find the 'first' devices on the 1-Wire network
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            CmdResult OWFirst(SearchState & searchState);
+            
+            /**********************************************************//**
+            * @brief OWNext()
+            * 
+            * @details Find the 'next' devices on the 1-Wire network
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            CmdResult OWNext(SearchState & searchState);
+            
+            /**********************************************************//**
+            * @brief OWVerify()
+            * 
+            * @details Verify the device with the ROM number in ROM_NO buffer 
+            *        is present.
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            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:
+            *
+            **************************************************************/
+            void OWTargetSetup(SearchState & searchState);
+            
+            /**********************************************************//**
+            * @brief OWFamilySkipSetup()
+            * 
+            * @details Setup the search to skip the current device type on the 
+            *          next call to OWNext().
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            void OWFamilySkipSetup(SearchState & searchState);
+            
+            /**********************************************************//**
+            * @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:
+            *
+            **************************************************************/
+            CmdResult OWReadROM(RomId & romId);
+            
+            /**********************************************************//**
+            * @brief OWSkipROM()
+            * 
+            * @details Issue SKIP_ROM command on 1-wire bus
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            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:
+            *
+            **************************************************************/
+            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:
+            *
+            **************************************************************/
+            CmdResult OWOverdriveSkipROM(void);
+            
+            /**********************************************************//**
+            * @brief OWOverdriveMatchROM()
+            * 
+            * @details Issues OVERDRIVE_MATCH rom command.  DS248X OW speed 
+            * is set to SPEED_OVERDRIVE
+            *
+            * On Entry:
+            *
+            * On Exit:
+            *
+            **************************************************************/
+            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:
+            *
+            **************************************************************/
+            CmdResult OWResume(void);
+            
+            /**********************************************************//**
+            * @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:
+            *
+            **************************************************************/
+            CmdResult OWSearch(SearchState & searchState);
+        };
+    }
+}
+
+#endif /*ONEWIREMASTER_H*/