: Class OneWireContainer

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.dalsemi.onewire.container
Class OneWireContainer

    java.lang.Object
      |
      +--com.dalsemi.onewire.container.OneWireContainer

public class OneWireContainer
extends Object

A `OneWireContainer` encapsulates the `DSPortAdapter`, the 1-Wire® network address, and methods to manipulate a specific 1-Wire device. A 1-Wire device may be in the form of a stainless steel armored can, called an iButton®, or in standard IC plastic packaging.

General 1-Wire device container class with basic communication functions. This class should only be used if a device specific class is not available or known. Most `OneWireContainer` classes will extend this basic class.

1-Wire devices with memory can be accessed through the objects that are returned from the `getMemoryBanks` method. See the usage example below.

### Usage

  #### Example 1

  Enumerate memory banks retrieved from the OneWireContainer instance 'owd' and cast to the highest interface. See the interface descriptions `MemoryBank`, `PagedMemoryBank`, and `OTPMemoryBank` for specific examples.

        MemoryBank      mb;
        PagedMemoryBank pg_mb;
        OTPMemoryBank   otp_mb;

        for(Enumeration bank_enum = owd.getMemoryBanks();
                            bank_enum.hasMoreElements(); )
        {
           // get the next memory bank, cast to MemoryBank
           mb = (MemoryBank)bank_enum.nextElement();

           // check if has paged services
           if (mb instanceof PagedMemoryBank)
               pg_mb = (PagedMemoryBank)mb;

           // check if has One-Time-Programable services
           if (mb instanceof OTPMemoryBank)
               otp_mb = (OTPMemoryBank)mb;
        }

See Also:
  `com.dalsemi.onewire.container.MemoryBank`, `com.dalsemi.onewire.container.PagedMemoryBank`, `com.dalsemi.onewire.container.OTPMemoryBank`

Field Summary
`protected DSPortAdapter` | `adapter` Reference to the adapter that is needed to communicate with this iButton or 1-Wire device.
`protected byte[]` | `address` 1-Wire Network Address of this iButton or 1-Wire device.
`protected int` | `speed` Communication speed requested.
`protected boolean` | `speedFallBackOK` Flag to indicate that falling back to a slower speed then requested is OK.

Constructor Summary
`OneWireContainer()` Create an empty container.
`OneWireContainer(DSPortAdapter sourceAdapter, byte[] newAddress)` Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
`OneWireContainer(DSPortAdapter sourceAdapter, long newAddress)` Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
`OneWireContainer(DSPortAdapter sourceAdapter, String newAddress)` Create a container with a provided adapter object and the address of the iButton or 1-Wire device.

Method Summary
`void` | `doSpeed()` Go to the specified speed for this container.
`DSPortAdapter` | `getAdapter()` Retrieves the port adapter object used to create this container.
`byte[]` | `getAddress()` Gets the 1-Wire Network address of this device as an array of bytes.
`long` | `getAddressAsLong()` Gets this device's 1-Wire Network address as a long.
`String` | `getAddressAsString()` Gets this device's 1-Wire Network address as a String.
`String` | `getAlternateNames()` Retrieves the alternate Dallas Semiconductor part numbers or names.
`String` | `getDescription()` Retrieves a short description of the function of the 1-Wire device type.
`int` | `getMaxSpeed()` Returns the maximum speed this iButton or 1-Wire device can communicate at.
`Enumeration` | `getMemoryBanks()` Returns an `Enumeration` of `MemoryBank`.
`String` | `getName()` Retrieves the Dallas Semiconductor part number of the 1-Wire device as a `String`.
`boolean` | `isAlarming()` Verifies that the iButton or 1-Wire device is present on the 1-Wire Network and in an alarm state.
`boolean` | `isPresent()` Verifies that the iButton or 1-Wire device is present on the 1-Wire Network.
`void` | `setSpeed(int newSpeed, boolean fallBack)` Sets the maximum speed for this container.
`void` | `setupContainer(DSPortAdapter sourceAdapter, byte[] newAddress)` Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
`void` | `setupContainer(DSPortAdapter sourceAdapter, long newAddress)` Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
`void` | `setupContainer(DSPortAdapter sourceAdapter, String newAddress)` Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### adapter

    protected DSPortAdapter adapter

  Reference to the adapter that is needed to communicate with this iButton or 1-Wire device.

### address

    protected byte[] address

  1-Wire Network Address of this iButton or 1-Wire device. Family code is byte at offset 0.
  See Also:
    `Address`

### speed

    protected int speed

  Communication speed requested.
  - 0 (SPEED_REGULAR)
  - 1 (SPEED_FLEX)
  - 2 (SPEED_OVERDRIVE)
  - 3 (SPEED_HYPERDRIVE)
  - >3 future speeds
  See Also:
    `DSPortAdapter.setSpeed(int)`

### speedFallBackOK

    protected boolean speedFallBackOK

  Flag to indicate that falling back to a slower speed then requested is OK.

Constructor Detail

### OneWireContainer

    public OneWireContainer()

  Create an empty container. Must call `setupContainer` before using this new container.

  This is one of the methods to construct a container. The others are through creating a OneWireContainer with parameters.

  See Also:
    `OneWireContainer(DSPortAdapter,byte[])`, `OneWireContainer(DSPortAdapter,long)`, `OneWireContainer(DSPortAdapter,String)`, `setupContainer(DSPortAdapter,byte[])`, `setupContainer(DSPortAdapter,long)`, `setupContainer(DSPortAdapter,String)`

### OneWireContainer

    public OneWireContainer(DSPortAdapter sourceAdapter,
                            byte[] newAddress)

  Create a container with a provided adapter object and the address of the iButton or 1-Wire device.

  This is one of the methods to construct a container. The other is through creating a OneWireContainer with NO parameters.

  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton.
    `newAddress` - address of this 1-Wire device
  See Also:
    `OneWireContainer()`, `Address`

### OneWireContainer

    public OneWireContainer(DSPortAdapter sourceAdapter,
                            long newAddress)

  Create a container with a provided adapter object and the address of the iButton or 1-Wire device.

  This is one of the methods to construct a container. The other is through creating a OneWireContainer with NO parameters.

  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton.
    `newAddress` - address of this 1-Wire device
  See Also:
    `OneWireContainer()`, `Address`

### OneWireContainer

    public OneWireContainer(DSPortAdapter sourceAdapter,
                            String newAddress)

  Create a container with a provided adapter object and the address of the iButton or 1-Wire device.

  This is one of the methods to construct a container. The other is through creating a OneWireContainer with NO parameters.

  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton.
    `newAddress` - address of this 1-Wire device
  See Also:
    `OneWireContainer()`, `Address`

Method Detail

### setupContainer

    public void setupContainer(DSPortAdapter sourceAdapter,
                               byte[] newAddress)

  Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this 1-Wire device
  See Also:
    `Address`

### setupContainer

    public void setupContainer(DSPortAdapter sourceAdapter,
                               long newAddress)

  Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this 1-Wire device
  See Also:
    `Address`

### setupContainer

    public void setupContainer(DSPortAdapter sourceAdapter,
                               String newAddress)

  Provides this container with the adapter object used to access this device and the address of the iButton or 1-Wire device.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this 1-Wire device
  See Also:
    `Address`

### getAdapter

    public DSPortAdapter getAdapter()

  Retrieves the port adapter object used to create this container.
  Returns:
    port adapter instance

### getName

    public String getName()

  Retrieves the Dallas Semiconductor part number of the 1-Wire device as a `String`. For example 'Crypto iButton' or 'DS1992'.
  Returns:
    1-Wire device name

### getAlternateNames

    public String getAlternateNames()

  Retrieves the alternate Dallas Semiconductor part numbers or names. A 'family' of 1-Wire Network devices may have more than one part number depending on packaging. There can also be nicknames such as 'Crypto iButton'.
  Returns:
    1-Wire device alternate names

### getDescription

    public String getDescription()

  Retrieves a short description of the function of the 1-Wire device type.
  Returns:
    device functional description

### setSpeed

    public void setSpeed(int newSpeed,
                         boolean fallBack)

  Sets the maximum speed for this container. Note this may be slower then the devices maximum speed. This method can be used by an application to restrict the communication rate due 1-Wire line conditions.

  Parameters:
    `newSpeed` -
    - 0 (SPEED_REGULAR) 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
    `fallBack` - boolean indicating it is OK to fall back to a slower speed if true

### getMaxSpeed

    public int getMaxSpeed()

  Returns the maximum speed this iButton or 1-Wire device can communicate at. Override this method if derived iButton type can go faster then SPEED_REGULAR(0).
  Returns:
    maximum speed
  See Also:
    `DSPortAdapter.setSpeed(int)`

### getAddress

    public byte[] getAddress()

  Gets the 1-Wire Network address of this device as an array of bytes.
  Returns:
    1-Wire address
  See Also:
    `Address`

### getAddressAsString

    public String getAddressAsString()

  Gets this device's 1-Wire Network address as a String.
  Returns:
    1-Wire address
  See Also:
    `Address`

### getAddressAsLong

    public long getAddressAsLong()

  Gets this device's 1-Wire Network address as a long.
  Returns:
    1-Wire address
  See Also:
    `Address`

### getMemoryBanks

    public Enumeration getMemoryBanks()

  Returns an `Enumeration` of `MemoryBank`. Default is no memory banks.
  Returns:
    enumeration of memory banks to read and write memory on this iButton or 1-Wire device
  See Also:
    `MemoryBank`

### isPresent

    public boolean isPresent()
                      throws OneWireIOException,
                             OneWireException

  Verifies that the iButton or 1-Wire device is present on the 1-Wire Network.
  Returns:
    `true` if device present on the 1-Wire Network
  Throws:
    OneWireIOException - on a 1-Wire communication error such as a read back verification fails.
    OneWireException - if adapter is not open

### isAlarming

    public boolean isAlarming()
                       throws OneWireIOException,
                              OneWireException

  Verifies that the iButton or 1-Wire device is present on the 1-Wire Network and in an alarm state. This does not apply to all device types.
  Returns:
    `true` if device present and in alarm condition
  Throws:
    OneWireIOException - on a 1-Wire communication error such as a read back verification fails.
    OneWireException - if adapter is not open

### doSpeed

    public void doSpeed()
                 throws OneWireIOException,
                        OneWireException

  Go to the specified speed for this container. This method uses the containers selected speed (method setSpeed(speed, fallback)) and will optionally fall back to a slower speed if communciation failed. Only call this method once to get the device into the desired speed as long as the device is still responding.
  Throws:
    OneWireIOException - WHEN selected speed fails and fallback is false
    OneWireException - WHEN hypterdrive is selected speed
  See Also:
    `setSpeed(int,boolean)`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD