Dallas Semiconductor 1-Wire API 1.00 Alpha: Class OneWireContainer02

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 OneWireContainer02

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

public class OneWireContainer02
extends OneWireContainer

1-Wire® container that encapsulates the functionality of the 1-Wire family type 02 (hex), Dallas Semiconductor part number: DS1991, MultiKey.

This iButton is primarily used as a minimal security read/write portable memory device.

## Features

- Three 384 bit (48 bytes) password protected memory blocks
- 64 bit (8 byte) password per memory block
- 64 bit (8 byte) identification per memory block
- Data integrity assured with strict read/write protocols
- Operating temperature range from -40°C to +70°C
- Over 10 years of data retention

## Memory

All memory is accessed through read/write routines, no `MemoryBank` classes are used.

## Alternate Names

- DS1425 (Family 82)

## DataSheets

http://pdfserv.maxim-ic.com/arpdf/DS1991.pdf
http://pdfserv.maxim-ic.com/arpdf/DS1425.pdf

Version:
  0.00, 28 Aug 2000

Constructor Summary
`OneWireContainer02()` Create an empty container.
`OneWireContainer02(DSPortAdapter sourceAdapter, byte[] newAddress)` Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
`OneWireContainer02(DSPortAdapter sourceAdapter, long newAddress)` Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
`OneWireContainer02(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` | `copyScratchpad(int key, byte[] passwd, int blockNum)` Writes the data from the scratchpad to the specified block or blocks.
`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.
`String` | `getName()` Retrieves the Dallas Semiconductor part number of the 1-Wire device as a `String`.
`byte[]` | `readScratchpad()` Reads the entire scratchpad.
`void` | `readSubkey(byte[] data, int key, byte[] passwd)` Reads the subkey requested with the given key name and password.
`byte[]` | `readSubkey(int key, byte[] passwd)` Reads the subkey requested with the given key name and password.
`void` | `writePassword(int key, byte[] oldName, byte[] newName, byte[] newPasswd)` Writes a new identifier and password to the secure subkey iButton
`void` | `writeScratchpad(int addr, byte[] data)` Writes the data to the scratchpad from the given address.
`void` | `writeSubkey(int key, int addr, byte[] passwd, byte[] data)` Writes new data to the secure subkey

Methods inherited from class com.dalsemi.onewire.container.OneWireContainer
`doSpeed, getAdapter, getAddress, getAddressAsLong, getAddressAsString, getMaxSpeed, getMemoryBanks, isAlarming, isPresent, setSpeed, setupContainer, setupContainer, setupContainer`

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

Constructor Detail

### OneWireContainer02

    public OneWireContainer02()

  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:
    `OneWireContainer02(DSPortAdapter,byte[])`, `OneWireContainer02(DSPortAdapter,long)`, `OneWireContainer02(DSPortAdapter,String)`, `OneWireContainer.setupContainer(DSPortAdapter,byte[])`, `OneWireContainer.setupContainer(DSPortAdapter,long)`, `OneWireContainer.setupContainer(DSPortAdapter,String)`

### OneWireContainer02

    public OneWireContainer02(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:
    `OneWireContainer02()`, `Address`

### OneWireContainer02

    public OneWireContainer02(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:
    `OneWireContainer02()`, `Address`

### OneWireContainer02

    public OneWireContainer02(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:
    `OneWireContainer02()`, `Address`

Method Detail

### getName

    public String getName()

  Description copied from class: `OneWireContainer`
  Retrieves the Dallas Semiconductor part number of the 1-Wire device as a `String`. For example 'Crypto iButton' or 'DS1992'.
  Overrides:
    `getName` in class `OneWireContainer`
  Following copied from class: `com.dalsemi.onewire.container.OneWireContainer`
  Returns:
    1-Wire device name

### getAlternateNames

    public String getAlternateNames()

  Description copied from class: `OneWireContainer`
  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'.
  Overrides:
    `getAlternateNames` in class `OneWireContainer`
  Following copied from class: `com.dalsemi.onewire.container.OneWireContainer`
  Returns:
    1-Wire device alternate names

### getDescription

    public String getDescription()

  Description copied from class: `OneWireContainer`
  Retrieves a short description of the function of the 1-Wire device type.
  Overrides:
    `getDescription` in class `OneWireContainer`
  Following copied from class: `com.dalsemi.onewire.container.OneWireContainer`
  Returns:
    device functional description

### writeScratchpad

    public void writeScratchpad(int addr,
                                byte[] data)
                         throws OneWireIOException,
                                OneWireException,
                                IllegalArgumentException

  Writes the data to the scratchpad from the given address.
  Parameters:
    `addr` - address to begin writing. Must be between 0x00 and 0x3F.
    `data` - data to write.
  Throws:
    `IllegalArgumentException` - If address is out of range, or data is to long for scratchpad
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### readScratchpad

    public byte[] readScratchpad()
                          throws OneWireIOException,
                                 OneWireException

  Reads the entire scratchpad.
  Returns:
    `byte[]` containing the data from the scratchpad; the array will have a length of 64.
  Throws:
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### copyScratchpad

    public void copyScratchpad(int key,
                               byte[] passwd,
                               int blockNum)
                        throws OneWireIOException,
                               OneWireException,
                               IllegalArgumentException

  Writes the data from the scratchpad to the specified block or blocks. Note that the write will erase the data from the scratchpad.
  Parameters:
    `key` - subkey being written
    `passwd` - password for the subkey being written
    `blockNum` - number of the block to be copied (see page 7 of the DS1991 data sheet) block 0-7, or 8 to copy all 64 bytes.
  Throws:
    `IllegalArgumentException` - If key is out of range (0 to 2), or password is not 8 characters, or if blockNum is out of range (0 to 8)
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### readSubkey

    public byte[] readSubkey(int key,
                             byte[] passwd)
                      throws OneWireIOException,
                             OneWireException,
                             IllegalArgumentException

  Reads the subkey requested with the given key name and password. Note that this method allows for reading from the subkey data only which starts at address 0x10 within a key. It does not allow reading from any earlier address within a key because the device cannot be force to allow reading the password. This is why the subkey number is or-ed with 0x10 in creating the address in bytes 1 and 2 of the sendBlock.
  Parameters:
    `key` - number indicating the key to be read: 0, 1, or 2
    `passwd` - password of destination subkey
  Returns:
    byte[] containing the data from the subkey; the array will have a length of 64, since it includes the key identifier, sent password, and 48 bytes of data.
  Throws:
    `IllegalArgumentException` - If key is out of range (0 to 2), or password is not 8 characters, or if data does not have a length of 64
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### readSubkey

    public void readSubkey(byte[] data,
                           int key,
                           byte[] passwd)
                    throws OneWireIOException,
                           OneWireException,
                           IllegalArgumentException

  Reads the subkey requested with the given key name and password. Note that this method allows for reading from the subkey data only which starts at address 0x10 within a key. It does not allow reading from any earlier address within a key because the device cannot be force to allow reading the password. This is why the subkey number is or-ed with 0x10 in creating the address in bytes 1 and 2 of the sendBlock.
  Parameters:
    `data` - buffer of length 64 into which to write the data
    `key` - number indicating the key to be read: 0, 1, or 2
    `passwd` - password of destination subkey
  Throws:
    `IllegalArgumentException` - If key is out of range (0 to 2), or password is not 8 characters, or if data does not have a length of 64
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### writePassword

    public void writePassword(int key,
                              byte[] oldName,
                              byte[] newName,
                              byte[] newPasswd)
                       throws OneWireIOException,
                              OneWireException,
                              IllegalArgumentException

  Writes a new identifier and password to the secure subkey iButton
  Parameters:
    `key` - number indicating the key to be read: 0, 1, or 2
    `oldName` - identifier of the key used to confirm the correct key's password to be changed. Must be exactly length 8.
    `newName` - identifier to be used for the key with the new password. Must be exactly length 8.
    `newPasswd` - new password for destination subkey. Must be exactly length 8.
  Throws:
    `IllegalArgumentException` - If key value is out of range (0 to 2), or if newPasswd, newName, or oldName are not 8 characters
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### writeSubkey

    public void writeSubkey(int key,
                            int addr,
                            byte[] passwd,
                            byte[] data)
                     throws OneWireIOException,
                            OneWireException,
                            IllegalArgumentException

  Writes new data to the secure subkey
  Parameters:
    `key` - number indicating the key to be written: 0, 1, or 2
    `addr` - address to start writing at ( 0x00 to 0x3F )
    `passwd` - passwird for the subkey
    `data` - data to be written
  Throws:
    `IllegalArgumentException` - If key is out of range (0 to 2), or if address is out of range, or if passwd is not 8 characters, or if data length is out of bounds
    `OneWireIOException` - If device is not found on the 1-Wire network
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

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