RomCommands.h

00001 /// @file RomCommands.h
00002 /******************************************************************//**
00003 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved.
00004 *
00005 * Permission is hereby granted, free of charge, to any person obtaining a
00006 * copy of this software and associated documentation files (the "Software"),
00007 * to deal in the Software without restriction, including without limitation
00008 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
00009 * and/or sell copies of the Software, and to permit persons to whom the
00010 * Software is furnished to do so, subject to the following conditions:
00011 *
00012 * The above copyright notice and this permission notice shall be included
00013 * in all copies or substantial portions of the Software.
00014 *
00015 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
00016 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
00017 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
00018 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
00019 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
00020 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
00021 * OTHER DEALINGS IN THE SOFTWARE.
00022 *
00023 * Except as contained in this notice, the name of Maxim Integrated
00024 * Products, Inc. shall not be used except as stated in the Maxim Integrated
00025 * Products, Inc. Branding Policy.
00026 *
00027 * The mere transfer of this software does not imply any licenses
00028 * of trade secrets, proprietary technology, copyrights, patents,
00029 * trademarks, maskwork rights, or any other form of intellectual
00030 * property whatsoever. Maxim Integrated Products, Inc. retains all
00031 * ownership rights.
00032 **********************************************************************/
00033 
00034 #ifndef OneWire_RomCommands
00035 #define OneWire_RomCommands
00036 
00037 #include <stdint.h>
00038 #include "RomId/RomId.h"
00039 #include "Masters/OneWireMaster.h"
00040 
00041 namespace OneWire
00042 {
00043     /// Procedural 1-Wire ROM Commands for enumerating and selecting devices.
00044     namespace RomCommands
00045     {
00046         /// State used by all ROM ID search functions.
00047         struct SearchState
00048         {
00049             RomId romId;
00050             uint8_t last_discrepancy;
00051             uint8_t last_family_discrepancy;
00052             bool last_device_flag;
00053 
00054             /// Reset to the search state to start at the beginning.
00055             void reset();
00056             
00057             /// Setup the search to find the device type 'family_code'
00058             /// on the next call to OWNext() if it is present.
00059             void findFamily(uint8_t familyCode);
00060 
00061             /// Setup the search to skip the current device type on the
00062             /// next call to OWNext().
00063             void skipCurrentFamily();
00064 
00065             SearchState() { reset(); }
00066         };
00067         
00068         ///Find the 'first' devices on the 1-Wire bus.
00069         OneWireMaster::CmdResult OWFirst(OneWireMaster & master, SearchState & searchState);
00070 
00071         /// Find the 'next' devices on the 1-Wire bus.
00072         OneWireMaster::CmdResult OWNext(OneWireMaster & master, SearchState & searchState);
00073 
00074         /// Verify that the device with the specified ROM ID is present.
00075         OneWireMaster::CmdResult OWVerify(OneWireMaster & master, const RomId & romId);
00076 
00077         /// Use Read ROM command to read ROM ID from device on bus.
00078         /// @note Only use this command with a single drop bus, data
00079         ///       collisions will occur if more than 1 device on bus.
00080         /// @param[out] romId ROM ID read from device.
00081         OneWireMaster::CmdResult OWReadRom(OneWireMaster & master, RomId & romId);
00082 
00083         /// Issue Skip ROM command on bus.
00084         /// @note Only use this command with a single drop bus, data
00085         ///       collisions will occur if more than 1 device on bus.
00086         OneWireMaster::CmdResult OWSkipRom(OneWireMaster & master);
00087 
00088         /// Use the Match ROM command to select the device by its known ID.
00089         /// @note This command causes all devices supporting Overdrive
00090         ///       mode to switch to Overdrive timing.
00091         /// @param[in] romId ROM ID of device to select.
00092         OneWireMaster::CmdResult OWMatchRom(OneWireMaster & master, const RomId & romId);
00093 
00094         /// Issue Overdrive Skip ROM command on bus.
00095         /// @note This command causes all devices supporting Overdrive
00096         ///       mode to switch to Overdrive timing.
00097         /// @note Only use this command with a single drop bus, data
00098         ///       collisions will occur if more than 1 device on bus.
00099         OneWireMaster::CmdResult OWOverdriveSkipRom(OneWireMaster & master);
00100 
00101         /// Use the Overdrive Match ROM command to select the device by its known ID.
00102         /// @param[in] romId ROM ID of device to select.
00103         OneWireMaster::CmdResult OWOverdriveMatchRom(OneWireMaster & master, const RomId & romId);
00104 
00105         /// Perform a Resume ROM command on bus.
00106         /// @details Resumes communication with the last device selected
00107         ///          though a Match ROM or Search ROM operation.
00108         OneWireMaster::CmdResult OWResume(OneWireMaster & master);
00109 
00110         /// Find device on the 1-Wire bus.
00111         /// @details This command uses the Search ROM command to enumerate all 1-Wire devices in sequence.
00112         ///          Begin with a new search state and continue using the same search state until the last
00113         ///          device flag is set which indicates that all devices have been discovered.
00114         OneWireMaster::CmdResult OWSearch(OneWireMaster & master, SearchState & searchState);
00115         
00116         /// Find Alarming Devices on 1-Wire bus.
00117         /// @details This command uses the Alarm Search ROM command to enumerate all 1-Wire devices with active alarms
00118         ///          Begin with a new search state and continue using the same search state until the last
00119         ///          device flag is set which indicates that all devices have been discovered.          
00120         OneWireMaster::CmdResult OWAlarmSearch(OneWireMaster & master, SearchState & searchState);
00121         
00122         /// Find the first Alarming device on the 1-Wire bus.
00123         /// @details This command resets the SearchState and uses the Alarm Search command to enumerate the first actively alarming device on the bus, in numerical order by ROM ID.
00124         OneWireMaster::CmdResult OWFirstAlarm(OneWireMaster & master, SearchState & searchState);
00125         
00126         /// Find the next Alarming Device on the 1-Wire bus.
00127         /// @details This command  uses the Alarm Search command to enumerate the next actively alarming device on the bus, which is determined by the current searchState.
00128         OneWireMaster::CmdResult OWNextAlarm(OneWireMaster & master, SearchState & searchState);
00129         
00130         /// Helper function for the above search functions
00131         OneWireMaster::CmdResult OWSearchAll(OneWireMaster & master, SearchState & searchState, bool alarmSearch);
00132 
00133     }
00134 }
00135 
00136 #endif