/*--------------------------------------------------------------------------- * Copyright (C) 1999,2000 Dallas Semiconductor Corporation, 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 DALLAS SEMICONDUCTOR 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 Dallas Semiconductor * shall not be used except as stated in the Dallas Semiconductor * Branding Policy. *--------------------------------------------------------------------------- */ package com.dalsemi.onewire.container; // imports import com.dalsemi.onewire.OneWireException; import com.dalsemi.onewire.adapter.OneWireIOException; /** * 1-Wire Switch interface class for basic switch operations. * This class should be implemented for each switch type * 1-Wire device. * * @version 0.00, 27 August 2000 * @author DS */ public interface SwitchContainer extends OneWireSensor { //-------- //-------- Switch Feature methods //-------- /** * Query to see if the channels of this switch are 'high side' * switches. This indicates that when 'on' or TRUE, the switch output is * connect to the 1-Wire data. If this method returns FALSE * then when the switch is 'on' or TRUE, the switch is connected * to ground. * * @return boolean, true if switch is a 'high side' switch. false * if switch is a 'low side' switch. */ public boolean isHighSideSwitch (); /** * Query to see if the channels of this switch support * activity sensing. If this method returns true then the * method 'getActivity()' can be used. * * @return boolean, true if channels support activity sensing */ public boolean hasActivitySensing (); /** * Query to see if the channels of this switch support * level sensing. If this method returns true then the * method 'getLevel()' can be used. * * @return boolean, true if channels support level sensing */ public boolean hasLevelSensing (); /** * Query to see if the channels of this switch support * smart on. Smart on is the ability to turn on a channel * such that only 1-Wire device on this channel are awake * and ready to do an operation. This greatly reduces the * the time to discover the device down a branch. * If this method returns true then the * method 'setSwitch()' can be used with the 'doSmart' parameter * true. * * @return boolean, true if channels support smart on */ public boolean hasSmartOn (); /** * Query to see if the channels of this switch require that only * channel is on at any one time. If this method returns true then the * method 'setSwitch(channel)' will effect the state of the given * channel but may effect the state of the other channels as well * to insure that only one channel is on at a time. * * @return boolean, true if only 1 channel can be on at a time. */ public boolean onlySingleChannelOn (); //-------- //-------- Switch 'get' Methods //-------- /** * Query to get the number of channels supported by this switch. * Channel specific methods will use a channel number specified * by an integer from [0 to (getNumberChannels() - 1)]. * * @param state - byte array of device state * * @return int containing the number of channels */ public int getNumberChannels (byte[] state); /** * This method checks the sensed level on the indicated channel * from the provided state data retrieved from the * 'readDevice()' method. Note, to avoid an exception, verify * the features of this switch with the method 'hasLevelSensing()'. * * * @param channel * @param state - byte array of device state * * @return boolean<\code> true if level sensed is 'high' * and false if level sensed is 'low'. */ public boolean getLevel (int channel, byte[] state) throws OneWireException; /** * This method checks the latch state of the indicated channel * from the provided state data retrieved from the * 'readDevice()' method. * * * @param channel * @param state - byte array of device state * * @return boolean<\code> true if channel latch is 'on' * or conducting and false if channel latch is 'off' and not * conducting. Note that the actual output then the latch is 'on' * is returned from the 'isHighSideSwitch()' method. */ public boolean getLatchState (int channel, byte[] state); /** * This method checks if the indicated channel had activity * from the provided state data retrieved from the * 'readDevice()' method. Note, to avoid an exception, verify * the features of this switch with the method 'hasActivitySensing()'. * * * @param channel * @param state - byte array of device state * * @return boolean<\code> true if activity was detected * and false if no activity was detected. */ public boolean getSensedActivity (int channel, byte[] state) throws OneWireException; //-------- //-------- Switch 'set' Methods //-------- /** * This method sets the latch state of the indicated channel in the * state data. Use the method 'writeDevice()' with * this data to finalize the change to the device. * * @param channel - integer indicated channel to do operation on * in the range [0 to (getNumberChannels() - 1)] * @param latchState * @param doSmart - if latchState is 'on'/true then doSmart indicates * if a 'smart on' is to be done. To avoid an exception * check the cababilities of the device using the * 'hasSmartOn()' method. * @param state - byte array of device state */ public void setLatchState (int channel, boolean latchState, boolean doSmart, byte[] state); /** * Clears the activity latches the next time possible. For * example, on a DS2406/07, this happens the next time the * status is read. */ public void clearActivity () throws OneWireException; }