Implementation of 1-Wire with added Alarm Search Functionality
Dependents: Max32630_One_Wire_Interface
Diff: Masters/OneWireMaster.h
- Revision:
- 73:2cecc1372acc
- Parent:
- 72:6892702709ee
- Child:
- 74:23be10c32fa3
diff -r 6892702709ee -r 2cecc1372acc Masters/OneWireMaster.h --- /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*/