com.ibutton.tmex.adapter
Interface DSPortAdapter

All Known Implementing Classes:
TINISerialAdapter
public abstract interface DSPortAdapter

The DSPortAdapter class is the interface base class of all port adapter objects. An implementation class of this type is therefore independent of the adapter type.

Method Summary
 boolean adapterDetected()
          Retrieve a list of the platform apropriate port names for this adapter.
 void addBusPowerStateListener(BusPowerStateListener listener)
          The following method is used to notify interested applications of the change in Bus Power state.
 void addMicroLanActivityListener(MicroLanActivityListener listener)
          The following method is used to notify interested applications of the change in Bus Power state.
 void beginExclusive()
          Gets exclusive use of the bus to communicate with an iButton.
 boolean beginExclusiveNonBlocking()
          Gets exclusive use of the bus to communicate with an iButton.
 boolean canDeliverPower()
          Returns whether adapter can physically support strong 5 volt power mode.
 boolean canDeliverSmartPower()
          Returns whether adapter can physically support "smart" strong 5 volt power mode.
 boolean canHyperdrive()
          Returns whether adapter can physically support hyperdrive mode.
 boolean canOverdrive()
          Returns whether adapter can physically support overdrive mode.
 boolean canProgram()
          Returns whether adapter can physically support 12 volt power mode.
 char[] dataBlock(char[] dataBlock, int off, int len)
          Sends a block of data and returns the data received in the same array.
 void endExclusive()
          Relinquishes exclusive control of the MicroLan.
 void excludeFamily(int FamilyID)
          Takes an integer to selectively avoid searching for this family.
 void excludeFamily(int[] FamilyID)
          Takes an array of ints to selectively avoid finding iButtons several acceptable family codes.
 void freePort()
          Free ownership of the selected port if it is currently owned.
 java.lang.String getAdapterID()
          Retrieve the ID number of the adapter if it has one.
 java.lang.String getAdapterName()
          Retrieve the name of the port adapter as a string.
 java.lang.String getAdapterVersion()
          Retrieve the version of the adapter
 java.util.Enumeration getAlliButtons()
          Returns an enumeration of iButtonContainer objects corresponding to all of the iButton found on the MicroLan.
 boolean getBit()
          Gets a bit from the MicroLan.
 char[] getBlock(int len)
          Get a block of data and return it in an array.
 char getByte()
          Gets a byte from the MicroLan.
 java.lang.String getClassVersion()
          Retrieve a version string for this class
 iButtonContainer getFirstiButton()
          Returns an iButtonContainer object corresponding to the first iButton found on the MicroLan.
 iButtonContainer getNextiButton()
          Returns an iButtonContainer object corresponding to the next iButton found.
 java.lang.String getPortName()
          Retrieve the name of the selected port as a string.
 java.util.Enumeration getPortNames()
          Retrieve a list of the platform apropriate port names for this adapter.
 java.lang.String getPortTypeDescription()
          Retrieve a description of the port required by this port adapter.
 int getSpeed()
          This method returns the current data transfer speed through a port to a MicroLan.
 boolean isAlarming(iButtonContainer ibutton)
          Verifies that the iButton specified is present on the MicroLAN and in an alarm state.
 boolean isPresent(iButtonContainer ibutton)
          Verifies that the iButton specified is present on the MicroLAN.
 iButtonContainer newContainer()
          Constucts a blank iButtonContainer object attached to this port.
 boolean portOwned()
          Query to see if the selected port is currently owned by this class
 void putBit(boolean bitValue)
          Sends a bit to the MicroLan.
 void putByte(char byteValue)
          Sends a byte to the MicroLan.
 void removeBusPowerStateListener(BusPowerStateListener listener)
          The following method is used to remove notification of the Bus Power state changes.
 void removeMicroLanActivityListener(MicroLanActivityListener listener)
          The following method is used to remove notification of MicroLan activity.
 int reset()
          Sends a Reset to the MicroLan.
 boolean select(iButtonContainer ibutton)
          Selects the specified iButton by broadcasting the serial number ID.
 boolean selectPort(java.lang.String portName)
          Specify a platform apropriate port name for this adapter.
 void setBusPowerNormal()
          Sets the MicroLan voltage to normal level.
 void setPowerDuration(int timeFactor)
          Sets the MicroLan voltage to supply power duration.
 void setProgramPulseDuration(int timeFactor)
          Sets the MicroLan voltage to supply power duration.
 void setSearchAlliButtons()
          Set the Button search to find all iButtons whether they are in an 'Alarm' state or not.
 void setSearchOnlyAlarmingiButtons()
          Set the Button search to find only iButtons that are in an 'Alarm' state that signals a need for attention.
 void setSpeed(int desiredSpeed)
          This method takes an int representing the desired speed of data transfer on the MicroLan.
 void startBusBreak()
          Sets the MicroLan voltage to 0 volts.
 boolean startPowerDelivery(int changeCondition)
          Sets the MicroLan voltage to supply power to an iButton device.
 boolean startProgramPulse(int changeCondition)
          Sets the MicroLan voltage to eprom programming level.
 void targetAllFamilies()
          Removes any selectivity during a search for iButtons by family type.
 void targetFamily(int familyID)
          Takes an integer to selectively search for this desired family type.
 void targetFamily(int[] familyID)
          Takes an array of ints to selectively search for several acceptable family codes.
 

Method Detail

getAdapterName

public java.lang.String getAdapterName()
Retrieve the name of the port adapter as a string. The 'Adapter' is a device that connects to a 'port' that allows one to communicate with an iButton. As example of this is 'DS9097U'.
Returns:
string represetation of the port adapter.

getPortTypeDescription

public java.lang.String getPortTypeDescription()
Retrieve a description of the port required by this port adapter. An example of a 'Port' would 'serial communication port'.
Returns:
string description of the port type required.

getClassVersion

public java.lang.String getClassVersion()
Retrieve a version string for this class
Returns:
version string

getPortNames

public java.util.Enumeration getPortNames()
Retrieve a list of the platform apropriate port names for this adapter. A port must be selected with the method 'selectPort' before any other communication methods can be used. Using a communcation method before 'selectPort' will result in a 'PortNotSelectedException' exception.
Returns:
enumeration of type String that contains the port names

selectPort

public boolean selectPort(java.lang.String portName)
                   throws PortInUseException
Specify a platform apropriate port name for this adapter. Note that even though the port has been selected, it's ownership may be relinquished if it is not currently held in a 'exclusive' block. This class will then try to re-aquire the port when needed. If the port cannot be re-aquired then the exception 'PortInUseException' will be thrown.
Parameters:
portName - name of the target port, retrieved from getPortNames()
Returns:
'true' if the port was aquired, 'false' if the port is not available.
Throws:
PortInUseException -  

getPortName

public java.lang.String getPortName()
                             throws PortNotSelectedException
Retrieve the name of the selected port as a string.
Returns:
string of selected port
Throws:
PortNotSelectedException -  

freePort

public void freePort()
              throws PortNotSelectedException
Free ownership of the selected port if it is currently owned. Call this method at the end of your application's use of the port.
Throws:
PortNotSelectedException -  

portOwned

public boolean portOwned()
                  throws PortNotSelectedException
Query to see if the selected port is currently owned by this class
Returns:
'true' if selected port is currently owned by this class
Throws:
PortNotSelectedException -  

adapterDetected

public boolean adapterDetected()
                        throws PortNotSelectedException,
                               PortInUseException
Retrieve a list of the platform apropriate port names for this adapter.
Returns:
'true' if the adapter is confirmed to be connected to the selected port, 'false' the adapter is not connected.
Throws:
PortNotSelectedException -  
PortInUseException -  

getAdapterVersion

public java.lang.String getAdapterVersion()
                                   throws PortNotSelectedException,
                                          PortInUseException,
                                          AdapterNotDetectedException,
                                          MicroLanIOException
Retrieve the version of the adapter
Returns:
string of the adapter version. It will return "" if the adapter version is not or cannot be known.
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

getAdapterID

public java.lang.String getAdapterID()
                              throws PortNotSelectedException,
                                     PortInUseException,
                                     AdapterNotDetectedException,
                                     MicroLanIOException
Retrieve the ID number of the adapter if it has one.
Returns:
string of the adapter ID. It will return "" if the adapter does not have an ID. The ID is a string representation of an iButton ID number.
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

canOverdrive

public boolean canOverdrive()
                     throws PortNotSelectedException,
                            PortInUseException,
                            AdapterNotDetectedException
Returns whether adapter can physically support overdrive mode.
Returns:
'true' if this port adapter can do OverDrive else 'false'
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  

canHyperdrive

public boolean canHyperdrive()
                      throws PortNotSelectedException,
                             PortInUseException,
                             AdapterNotDetectedException
Returns whether adapter can physically support hyperdrive mode.
Returns:
'true' if this port adapter can do HyperDrive else 'false'
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  

canProgram

public boolean canProgram()
                   throws PortNotSelectedException,
                          PortInUseException,
                          AdapterNotDetectedException
Returns whether adapter can physically support 12 volt power mode.
Returns:
'true' if this port adapter can do Program voltage else 'false'
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  

canDeliverPower

public boolean canDeliverPower()
                        throws PortNotSelectedException,
                               PortInUseException,
                               AdapterNotDetectedException
Returns whether adapter can physically support strong 5 volt power mode.
Returns:
'true' if this port adapter can do strong 5 volt mode else 'false'
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  

canDeliverSmartPower

public boolean canDeliverSmartPower()
                             throws PortNotSelectedException,
                                    PortInUseException,
                                    AdapterNotDetectedException
Returns whether adapter can physically support "smart" strong 5 volt power mode. "smart" power delivery is the ability to deliver power until it is no longer needed. The current drop it detected and power delivery is stopped.
Returns:
'true' if this port adapter can do "smart" strong 5 volt mode else 'false'
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  

getAlliButtons

public java.util.Enumeration getAlliButtons()
                                     throws PortNotSelectedException,
                                            PortInUseException,
                                            AdapterNotDetectedException,
                                            MicroLanIOException
Returns an enumeration of iButtonContainer objects corresponding to all of the iButton found on the MicroLan. If no iButtons are found, then a null reference will be returned. All further communication with the button is done through the iButton.
Returns:
enumeration of iButtonContainer objects found on the MicroLan
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

getFirstiButton

public iButtonContainer getFirstiButton()
                                 throws PortNotSelectedException,
                                        PortInUseException,
                                        AdapterNotDetectedException,
                                        MicroLanIOException
Returns an iButtonContainer object corresponding to the first iButton found on the MicroLan. If no iButtons are found, then a null reference will be returned. All further communication with the button is done through the iButton.
Returns:
the first iButtonContainer object found on the MicroLan
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

getNextiButton

public iButtonContainer getNextiButton()
                                throws PortNotSelectedException,
                                       PortInUseException,
                                       AdapterNotDetectedException,
                                       MicroLanIOException
Returns an iButtonContainer object corresponding to the next iButton found. If no more iButtons are found then a null reference will be returned.
Returns:
the next iButtonContainer object found on the MicroLan
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

isPresent

public boolean isPresent(iButtonContainer ibutton)
                  throws PortNotSelectedException,
                         PortInUseException,
                         AdapterNotDetectedException,
                         MicroLanIOException
Verifies that the iButton specified is present on the MicroLAN.
Parameters:
ibutton - iButton to verify is present
Returns:
'TRUE' if device is present else 'FALSE'.
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

isAlarming

public boolean isAlarming(iButtonContainer ibutton)
                   throws PortNotSelectedException,
                          PortInUseException,
                          AdapterNotDetectedException,
                          MicroLanIOException
Verifies that the iButton specified is present on the MicroLAN and in an alarm state.
Parameters:
ibutton - iButton to verify is present and alarming
Returns:
'TRUE' if device is present and alarming else 'FALSE'.
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

select

public boolean select(iButtonContainer ibutton)
               throws PortNotSelectedException,
                      PortInUseException,
                      AdapterNotDetectedException,
                      MicroLanIOException
Selects the specified iButton by broadcasting the serial number ID. Warning, this does not verify that the device is currenly present on the MicroLAN (See isPresent).
Parameters:
ibutton - iButton to select
Returns:
'TRUE' if device ID was sent else 'FALSE'.
Throws:
PortNotSelectedException -  
PortInUseException -  
AdapterNotDetectedException -  
MicroLanIOException -  

addMicroLanActivityListener

public void addMicroLanActivityListener(MicroLanActivityListener listener)
                                 throws HardwareOptionNotAvailException
The following method is used to notify interested applications of the change in Bus Power state. This notification includes the following events:

The activityOnMicroLan() method of the "listener" registered using this method will be called when unsolicited activity on the MicroLan is detected.
Parameters:
listener - the class that implements the 'MicroLanActivityListener' interface

removeMicroLanActivityListener

public void removeMicroLanActivityListener(MicroLanActivityListener listener)
The following method is used to remove notification of MicroLan activity.

The addMicroLanActivityListener() method must have been called previously.

Parameters:
listener - the class that implements the 'MicroLanActivityListener' interface

setSearchOnlyAlarmingiButtons

public void setSearchOnlyAlarmingiButtons()
Set the Button search to find only iButtons that are in an 'Alarm' state that signals a need for attention. Not all iButton types have this feature. Some that do (DS1994, DS1920, DS2407)

setSearchAlliButtons

public void setSearchAlliButtons()
Set the Button search to find all iButtons whether they are in an 'Alarm' state or not.

targetAllFamilies

public void targetAllFamilies()
Removes any selectivity during a search for iButtons by family type. The unique ID for each iButton contians a family descriptor that indicates the capabilities of the iButton.

targetFamily

public void targetFamily(int familyID)
Takes an integer to selectively search for this desired family type. If this method is used, then no iButtons of other families will be found by getFirstButton() & getNextButton().
Parameters:
familyID - the code of the family type to target for searches

targetFamily

public void targetFamily(int[] familyID)
Takes an array of ints to selectively search for several acceptable family codes. If used, only iButtons with family codes in this array will be found by getFirstButton() & getNextButton().
Parameters:
familyID - array of family code of the family types to target for searches

excludeFamily

public void excludeFamily(int FamilyID)
Takes an integer to selectively avoid searching for this family. If this method is used, then no iButtons of this family will be found by getFirstButton() & getNextButton().
Parameters:
familyID - the code of the family type to NOT target in searches

excludeFamily

public void excludeFamily(int[] FamilyID)
Takes an array of ints to selectively avoid finding iButtons several acceptable family codes. If used, then no iButtons with family codes in this array will be found by getFirstButton() & getNextButton().
Parameters:
familyID - array of family code of the family types to NOT target for searches

beginExclusive

public void beginExclusive()
                    throws PortInUseException
Gets exclusive use of the bus to communicate with an iButton. This method should be used for critical sections of code where a sequence of commands must not be interrupted by communication of threads with other iButtons, and it is permissible to sustain a delay in the special case that another thread has already been granted exclusive access and this access has not yet been relinquished.

It can be called through the iButtonContainer class by the end application if they want to ensure exclusive use. If it is not called around several methods then it will be called inside each method.

Throws:
PortInUseException -  

beginExclusiveNonBlocking

public boolean beginExclusiveNonBlocking()
                                  throws PortInUseException
Gets exclusive use of the bus to communicate with an iButton. This method should be used for critical sections of code where a sequence of commands must not be interrupted by communication of threads with other iButtons, and it is not permissible to sustain a delay in the special case that another thread has already been granted exclusive access and this access has not yet been relinquished.
Returns:
'true' if exclusive access to the port was aquired else 'false'
Throws:
PortInUseException -  

endExclusive

public void endExclusive()
Relinquishes exclusive control of the MicroLan. This command dynamically marks the end of a critical section and should be used when exclusive control is no longer needed.

putBit

public void putBit(boolean bitValue)
            throws MicroLanIOException
Sends a bit to the MicroLan.
Parameters:
bitValue - the bit value to send to the MicroLan.
Throws:
MicroLanIOException -  

getBit

public boolean getBit()
               throws MicroLanIOException
Gets a bit from the MicroLan.
Returns:
the bit value recieved from the the MicroLan.
Throws:
MicroLanIOException -  

putByte

public void putByte(char byteValue)
             throws MicroLanIOException
Sends a byte to the MicroLan.
Parameters:
byteValue - the byte value to send to the MicroLan.
Throws:
MicroLanIOException -  

getByte

public char getByte()
             throws MicroLanIOException
Gets a byte from the MicroLan.
Returns:
the byte value to be recieved from the the MicroLan.
Throws:
MicroLanIOException -  

getBlock

public char[] getBlock(int len)
                throws MicroLanIOException
Get a block of data and return it in an array.
Parameters:
len - length of data bytes receive
Throws:
MicroLanIOException -  

dataBlock

public char[] dataBlock(char[] dataBlock,
                        int off,
                        int len)
                 throws MicroLanIOException
Sends a block of data and returns the data received in the same array. It starts sending data from the index at offset 'off' for length 'len'.
Parameters:
dataBlock - array of data (ints) to transfer to and from the MicroLan. Only the least significant 8 bits of each array element is used.
off - offset into the array of data to start
len - length of data to send / receive starting at 'off'
Returns:
the result block
Throws:
MicroLanIOException -  

reset

public int reset()
          throws MicroLanIOException
Sends a Reset to the MicroLan.
Returns:
the result of the reset. Potential results are:
  • 0 no devices present on the MicroLan.
  • 1 normal presence pulse detected on the MicroLan indicating there is a device present.
  • 2 alarming presence pulse detected on the MicroLan indicating there is a device present and it is in the alarm condition.
Throws:
MicroLanIOException -  

addBusPowerStateListener

public void addBusPowerStateListener(BusPowerStateListener listener)
The following method is used to notify interested applications of the change in Bus Power state. This notification includes the following events:

The busPowerStateChange() method of the "listener" registered using this method will be called with one of the above events.
Parameters:
listener - the class that implements the 'BusPowerStateListener' interface that wants to get these events

removeBusPowerStateListener

public void removeBusPowerStateListener(BusPowerStateListener listener)
The following method is used to remove notification of the Bus Power state changes.

The addBusPowerStateListener() method must have been called previously.

Parameters:
listener - the class that implements the 'BusPowerStateListener' interface that wants to remove notification

setPowerDuration

public void setPowerDuration(int timeFactor)
                      throws HardwareOptionNotAvailException
Sets the MicroLan voltage to supply power duration. This method takes a time parameter that indicates whether the power delivery should be done immediately, or after certain conditions have been met.

Note: to avoid getting the HardwareOptionNotAvailException exception, use the canDeliverPower() and canDeliverSmartPower() method to check it's availability.

Parameters:
timeFactor -
  • 0 (DELIVERY_HALF_SECOND) provide power for 1/2 second.
  • 1 (DELIVERY_ONE_SECOND) provide power for 1 second.
  • 2 (DELIVERY_TWO_SECONDS) provide power for 2 seconds.
  • 3 (DELIVERY_FOUR_SECONDS) provide power for 4 seconds.
  • 4 (DELIVERY_SMART_DONE) provide power until the the device is no longer drawing significant power.
  • 5 (DELIVERY_INFINITE) provide power until the setBusNormal() method is called.
Throws:
HardwareOptionNotAvailException -  

startPowerDelivery

public boolean startPowerDelivery(int changeCondition)
                           throws MicroLanIOException,
                                  HardwareOptionNotAvailException
Sets the MicroLan voltage to supply power to an iButton device. This method takes a time parameter that indicates whether the power delivery should be done immediately, or after certain conditions have been met.

Note: to avoid getting the HardwareOptionNotAvailException exception, use the canDeliverPower() and canDeliverSmartPower() method to check it's availability.

Parameters:
changeCondition -
  • 0 (CONDITION_NOW) operation should occur immediately.
  • 1 (CONDITION_AFTER_BIT) operation should be pending execution immediately after the next bit is sent.
  • 2 (CONDITION_AFTER_BYTE) operation should be pending execution immediately after next byte is sent.
Returns:
'true' if the voltage change was successful else 'false'
Throws:
HardwareOptionNotAvailException -  
MicroLanIOException -  

setProgramPulseDuration

public void setProgramPulseDuration(int timeFactor)
Sets the MicroLan voltage to supply power duration. This method takes a time parameter that indicates whether the power delivery should be done immediately, or after certain conditions have been met.

Note: to avoid getting the HardwareOptionNotAvailException exception, use the canDeliverPower() method to check it's availability.

Parameters:
timeFactor -
  • 6 (DELIVERY_EPROM) provide program pulse for 480 microseconds
  • 5 (DELIVERY_INFINITE) provide power until the setBusNormal() method is called.

startProgramPulse

public boolean startProgramPulse(int changeCondition)
                          throws MicroLanIOException,
                                 HardwareOptionNotAvailException
Sets the MicroLan voltage to eprom programming level. This method takes a time parameter that indicates whether the power delivery should be done immediately, or after certain conditions have been met.

Note: to avoid getting the HardwareOptionNotAvailException exception, use the canProgram() method to check it's availability.

Parameters:
changeCondition -
  • 0 (CONDITION_NOW) operation should occur immediately.
  • 1 (CONDITION_AFTER_BIT) operation should be pending execution immediately after the next bit is sent.
  • 2 (CONDITION_AFTER_BYTE) operation should be pending execution immediately after next byte is sent.
Returns:
'true' if the voltage change was successful else 'false'
Throws:
HardwareOptionNotAvailException -  
MicroLanIOException -  

startBusBreak

public void startBusBreak()
                   throws MicroLanIOException,
                          HardwareOptionNotAvailException
Sets the MicroLan voltage to 0 volts. This method is used rob all MicroLan devices of parasite power delivery to force them into a hard reset.
Throws:
HardwareOptionNotAvailException -  
MicroLanIOException -  

setBusPowerNormal

public void setBusPowerNormal()
                       throws MicroLanIOException
Sets the MicroLan voltage to normal level. This method is used to disable bus conditions created by startPowerDelivery and startProgramPulse. This method will automatically be called if a communication method is called while an outstanding power command is taking place.
Throws:
MicroLanIOException -  

setSpeed

public void setSpeed(int desiredSpeed)
              throws HardwareOptionNotAvailException
This method takes an int representing the desired speed of data transfer on the MicroLan.

Parameters:
desiredSpeed -
  • 0 (SPEED_NORMAL) set to normal communciation speed
  • 1 (SPEED_FLEX) set to flexible communciation speed used for long lines
  • 2 (SPEED_OVERDRIVE) set to normal communciation speed to overdrive
  • 3 (SPEED_HYPERDRIVE) set to normal communciation speed to hyperdrive
  • >3 future speeds
Throws:
HardwareOptionNotAvailException -  

getSpeed

public int getSpeed()
This method returns the current data transfer speed through a port to a MicroLan.

Returns:
  • 0 (SPEED_NORMAL) set to normal communciation speed
  • 1 (SPEED_FLEX) set to flexible communciation speed used for long lines
  • 2 (SPEED_OVERDRIVE) set to normal communciation speed to overdrive
  • 3 (SPEED_HYPERDRIVE) set to normal communciation speed to hyperdrive
  • >3 future speeds

newContainer

public iButtonContainer newContainer()
Constucts a blank iButtonContainer object attached to this port. Since no regular constructor is provided for the iButtonContainer class, a method is provided through the DSPortAdapter which will both construct a family specify iButtonContainer cooresponding to the current iButton's family type or as a default a general purpose iButtonContainer. It will be attached to this associated DSPortAdapter.
Returns:
the iButtonContainer object