Dallas Semiconductor 1-Wire API 1.00 Alpha: Class OneWireContainer33

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 OneWireContainer33

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

public class OneWireContainer33
extends OneWireContainer

1-Wire® container for the '1K-Bit protected 1-Wire EEPROM with SHA-1 Engine' family type 33 (hex), Dallas Semiconductor part number: DS1961S,DS2432.

### Features

- 1128 bits of 5V EEPROM memory partitioned into four pages of 256 bits, a 64-bit write-only secret and up to 5 general purpose read/write registers.
- On-chip 512-bit SHA-1 engine to compute 160-bit Message Authentication Codes (MAC) and to generate secrets.
- Write access requires knowledge of the secret and the capability of computing and transmitting a 160-bit MAC as authorization.
- Secret and data memory can be write-protected (all or page 0 only) or put in EPROM-emulation mode ("write to 0", page0)
- unique, fatory-lasered and tested 64-bit registration number (8-bit family code + 48-bit serial number + 8-bit CRC tester) assures absolute traceablity because no two parts are alike.
- Built-in multidrop controller ensures compatibility with other 1-Wire net products.
- Reduces control, address, data and power to a single data pin.
- Directly connects to a single port pin of a microprocessor and communicates at up to 16.3k bits per second.
- Overdrive mode boosts communication speed to 142k bits per second.
- 8-bit family code specifies DS2432 communication requirements to reader.
- Presence detector acknowledges when reader first applies voltage.
- Low cost 6-lead TSOC surface mount package, or solder-bumped chip scale package.
- Reads and writes over a wide voltage range of 2.8V to 5.25V from -40C to +85C.

The memory can also be accessed through the objects that are returned from the `getMemoryBanks` method.

The following is a list of the MemoryBank instances that are returned:

- Page Zero with write protection
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 32 starting at physical address 0
  - Features Read/Write general-purpose non-volatile
  - Page 1 page of length 32 bytes giving 29 bytes Packet data payload
  - Page Features page-device-CRC and write protection.
- Page One with EPROM mode and write protection
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 32 starting at physical address 32
  - Features Read/Write general-purpose non-volatile
  - Page 1 page of length 32 bytes giving 29 bytes Packet data payload
  - Page Features page-device-CRC, EPROM mode and write protection.
- Page Two and Three with write protection
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 64 starting at physical address 64
  - Features Read/Write general-purpose non-volatile
  - Pages 2 pages of length 32 bytes giving 29 bytes Packet data payload
  - Page Features page-device-CRC and write protection.
- Status Page that contains the secret and the status.
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 24 starting at physical address 128
  - Page Features Contains secret and status for the iButton.

  #### Example 1

  Display some features of isMACValid where owd is an instanceof OneWireContainer33 and bank is an instanceof PagedMemoryBank:

        byte[] read_buf  = new byte [bank.getPageLength()];
        byte[] extra_buf = new byte [bank.getExtraInfoLength()];
        byte[] challenge = new byte [8];

        // read a page (use the most verbose and secure method)
        if (bank.hasPageAutoCRC())
        {
           System.out.println("Using device generated CRC");

           if (bank.hasExtraInfo())
           {
              bank.readPageCRC(pg, false, read_buf, 0, extra_buf);

              owd.getChallenge(challenge,0);
              owd.getContainerSecret(secret);
              sernum = owd.getAddress();
              macvalid = owd.isMACValid(bank.getStartPhysicalAddress()+pg*bank.getPageLength(),
                                        sernum,read_buf,extra_buf,challenge,secret);
           }
           else
              bank.readPageCRC(pg, false, read_buf, 0);
        }
        else
        {
           if (bank.hasExtraInfo())
              bank.readPage(pg, false, read_buf, 0, extra_buf);
           else
              bank.readPage(pg, false, read_buf, 0);
        }

  ### DataSheet

    http://pdfserv.maxim-ic.com/arpdf/DS2432.pdf

  Version:
    0.00, 19 Dec 2000
  See Also:
    `SHAiButtonUser33`

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

  Method Summary
  `boolean` | `bindSecretToiButton(int pageNum, byte[] bindData)`
  `void` | `computeNextSecret(int pageNum, byte[] partialsecret)` Compute Next Secret
  `boolean` | `copyScratchpad(int targetPage, int targetPageOffset, byte[] copy_auth, int authStart)`
  `String` | `getAlternateNames()` Retrieve the alternate Dallas Semiconductor part numbers or names.
  `void` | `getChallenge(byte[] get, int offset)` Get the challenge of this device as an array of bytes.
  `void` | `getContainerSecret(byte[] get)` Get the secret of this device as an array of bytes.
  `String` | `getDescription()` Retrieve a short description of the function of the iButton type.
  `int` | `getMaxSpeed()` Returns the maximum speed this iButton can communicate at.
  `Enumeration` | `getMemoryBanks()` Get an enumeration of memory bank instances that implement one or more of the following interfaces: `MemoryBank`, `PagedMemoryBank`, and `OTPMemoryBank`.
  `String` | `getName()` Retrieve the Dallas Semiconductor part number of the iButton as a string.
  `boolean` | `installMasterSecret(int page, byte[] newSecret)`
  `boolean` | `isContainerSecretSet()` Get the current status of the secret.
  `static boolean` | `isMACValid(int addr, byte[] SerNum, byte[] memory, byte[] mac, byte[] challenge, byte[] secret)` Authenticates page data given a MAC.
  `boolean` | `isPageOneEPROMmode()` Tells if page one is in EPROM mode.
  `boolean` | `isSecretWriteProtected()` Get the status of the secret, if it is write protected.
  `boolean` | `isWriteProtectAllSet()` Get the status of all the pages, if they are write protected.
  `boolean` | `isWriteProtectPageZeroSet()` Get the status of page zero, if it is write protected.
  `boolean` | `loadFirstSecret(byte[] data)` Load First Secret
  `boolean` | `readAuthenticatedPage(int page, byte[] pagedata, int offset, byte[] computed_mac, int macStart)`
  `boolean` | `readMemoryPage(int page, byte[] pageData, int offset)`
  `void` | `setChallenge(byte[] challengeset, int offset)` Sets the challenge for the Read Authenticate Page
  `void` | `setContainerSecret(byte[] newSecret)` Sets the bus master secret for this DS2432.
  `void` | `setEPROMModePageOne()` Sets the EPROM mode for page 1.
  `void` | `setupContainer(DSPortAdapter sourceAdapter, byte[] newAddress)` Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
  `void` | `setupContainer(DSPortAdapter sourceAdapter, long newAddress)` Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
  `void` | `setupContainer(DSPortAdapter sourceAdapter, String newAddress)` Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
  `boolean` | `writeDataPage(int targetPage, byte[] pageData)`
  `boolean` | `writeDataPage(int targetPage, byte[] pageData, int offset)`
  `void` | `writeProtectAll()` Write protect pages 0 to 3
  `void` | `writeProtectPageZero()` Write protect page zero only.
  `void` | `writeProtectSecret()` Write protects the secret for the DS2432.
  `boolean` | `writeScratchpad(int targetPage, int targetPageOffset, byte[] inputbuffer, int start, int length)`

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

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

  Constructor Detail

  ### OneWireContainer33

      public OneWireContainer33()

    Default Constructor OneWireContainer33. Must call setupContainer before using.

  ### OneWireContainer33

      public OneWireContainer33(DSPortAdapter sourceAdapter,
                                byte[] newAddress)

    Create a container with a provided adapter object 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

  ### OneWireContainer33

      public OneWireContainer33(DSPortAdapter sourceAdapter,
                                long newAddress)

    Create a container with a provided adapter object 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

  ### OneWireContainer33

      public OneWireContainer33(DSPortAdapter sourceAdapter,
                                String newAddress)

    Create a container with a provided adapter object 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

  Method Detail

  ### setupContainer

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

    Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
    Overrides:
      `setupContainer` in class `OneWireContainer`
    Parameters:
      `sourceAdapter` - adapter object required to communicate with this iButton.
      `newAddress` - address of this 1-Wire device

  ### setupContainer

      public void setupContainer(DSPortAdapter sourceAdapter,
                                 long newAddress)

    Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
    Overrides:
      `setupContainer` in class `OneWireContainer`
    Parameters:
      `sourceAdapter` - adapter object required to communicate with this iButton.
      `newAddress` - address of this 1-Wire device

  ### setupContainer

      public void setupContainer(DSPortAdapter sourceAdapter,
                                 String newAddress)

    Provide this container the adapter object used to access this device and provide the address of this iButton or 1-Wire device.
    Overrides:
      `setupContainer` in class `OneWireContainer`
    Parameters:
      `sourceAdapter` - adapter object required to communicate with this iButton.
      `newAddress` - address of this 1-Wire device

  ### getName

      public String getName()

    Retrieve the Dallas Semiconductor part number of the iButton as a string. For example 'DS1992'.
    Overrides:
      `getName` in class `OneWireContainer`
    Returns:
      string represetation of the iButton name.

  ### getAlternateNames

      public String getAlternateNames()

    Retrieve the alternate Dallas Semiconductor part numbers or names. A 'family' of MicroLAN devices may have more than one part number depending on packaging.
    Overrides:
      `getAlternateNames` in class `OneWireContainer`
    Returns:
      the alternate names for this iButton or 1-Wire device

  ### getDescription

      public String getDescription()

    Retrieve a short description of the function of the iButton type.
    Overrides:
      `getDescription` in class `OneWireContainer`
    Returns:
      string represetation of the function description.

  ### getMaxSpeed

      public int getMaxSpeed()

    Returns the maximum speed this iButton can communicate at.
    Overrides:
      `getMaxSpeed` in class `OneWireContainer`
    Returns:
      max. communication speed.

  ### getMemoryBanks

      public Enumeration getMemoryBanks()

    Get an enumeration of memory bank instances that implement one or more of the following interfaces: `MemoryBank`, `PagedMemoryBank`, and `OTPMemoryBank`.
    Overrides:
      `getMemoryBanks` in class `OneWireContainer`
    Returns:
      `Enumeration` of memory banks

  ### setContainerSecret

      public void setContainerSecret(byte[] newSecret)

    Sets the bus master secret for this DS2432.
    Parameters:
      `newSecret` - Secret for this DS2432.

  ### getContainerSecret

      public void getContainerSecret(byte[] get)

    Get the secret of this device as an array of bytes.
    Parameters:
      `get` - array of bytes containing the iButton secret

  ### isContainerSecretSet

      public boolean isContainerSecretSet()
                                   throws OneWireIOException,
                                          OneWireException

    Get the current status of the secret.
    Returns:
      boolean telling if the secret is set
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### isSecretWriteProtected

      public boolean isSecretWriteProtected()
                                     throws OneWireIOException,
                                            OneWireException

    Get the status of the secret, if it is write protected.
    Returns:
      boolean telling if the secret is write protected.
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### setChallenge

      public void setChallenge(byte[] challengeset,
                               int offset)

    Sets the challenge for the Read Authenticate Page
    Parameters:
      `challengeset` - Challenge for all the memory banks.

  ### getChallenge

      public void getChallenge(byte[] get,
                               int offset)

    Get the challenge of this device as an array of bytes.
    Parameters:
      `get` - array of bytes containing the iButton challenge

  ### isWriteProtectAllSet

      public boolean isWriteProtectAllSet()
                                   throws OneWireIOException,
                                          OneWireException

    Get the status of all the pages, if they are write protected.
    Returns:
      boolean telling if all the pages are write protected.
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### writeProtectSecret

      public void writeProtectSecret()
                              throws OneWireIOException,
                                     OneWireException

    Write protects the secret for the DS2432.

  ### writeProtectAll

      public void writeProtectAll()
                           throws OneWireIOException,
                                  OneWireException

    Write protect pages 0 to 3

  ### setEPROMModePageOne

      public void setEPROMModePageOne()
                               throws OneWireIOException,
                                      OneWireException

    Sets the EPROM mode for page 1. After setting, Page One can only be written to once.

  ### isPageOneEPROMmode

      public boolean isPageOneEPROMmode()
                                 throws OneWireIOException,
                                        OneWireException

    Tells if page one is in EPROM mode.
    Returns:
      boolean telling if page one is in EPROM mode.
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### writeProtectPageZero

      public void writeProtectPageZero()
                                throws OneWireIOException,
                                       OneWireException

    Write protect page zero only.

  ### isWriteProtectPageZeroSet

      public boolean isWriteProtectPageZeroSet()
                                        throws OneWireIOException,
                                               OneWireException

    Get the status of page zero, if it is write protected.
    Returns:
      boolean telling if page zero is write protected.
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### computeNextSecret

      public void computeNextSecret(int pageNum,
                                    byte[] partialsecret)
                             throws OneWireIOException,
                                    OneWireException

    Compute Next Secret
    Parameters:
      `addr` - address of page to use for the next secret computation.
      `parialsecret` - the data to put into the scrathpad in computing next secret.

  ### loadFirstSecret

      public boolean loadFirstSecret(byte[] data)
                              throws OneWireIOException,
                                     OneWireException

    Load First Secret
    Returns:
      boolean saying if first secret was loaded
    Throws:
      `OneWireIOException` -
      `OneWireException` -

  ### isMACValid

      public static boolean isMACValid(int addr,
                                       byte[] SerNum,
                                       byte[] memory,
                                       byte[] mac,
                                       byte[] challenge,
                                       byte[] secret)

    Authenticates page data given a MAC.
    Parameters:
      `addr` - address of the data to be read
      `memory` - the memory read from the page
      `mac` - the MAC calculated for this function given back as the extra info
      `challenge` - the 8 bytes of the scratch pad used in calculating the mac

  ### installMasterSecret

      public boolean installMasterSecret(int page,
                                         byte[] newSecret)
                                  throws OneWireIOException,
                                         OneWireException

  ### bindSecretToiButton

      public boolean bindSecretToiButton(int pageNum,
                                         byte[] bindData)
                                  throws OneWireIOException,
                                         OneWireException

  ### writeDataPage

      public boolean writeDataPage(int targetPage,
                                   byte[] pageData)
                            throws OneWireIOException,
                                   OneWireException

  ### writeDataPage

      public boolean writeDataPage(int targetPage,
                                   byte[] pageData,
                                   int offset)
                            throws OneWireIOException,
                                   OneWireException

  ### writeScratchpad

      public boolean writeScratchpad(int targetPage,
                                     int targetPageOffset,
                                     byte[] inputbuffer,
                                     int start,
                                     int length)
                              throws OneWireIOException,
                                     OneWireException

  ### copyScratchpad

      public boolean copyScratchpad(int targetPage,
                                    int targetPageOffset,
                                    byte[] copy_auth,
                                    int authStart)
                             throws OneWireIOException,
                                    OneWireException

  ### readMemoryPage

      public boolean readMemoryPage(int page,
                                    byte[] pageData,
                                    int offset)
                             throws OneWireIOException,
                                    OneWireException

  ### readAuthenticatedPage

      public boolean readAuthenticatedPage(int page,
                                           byte[] pagedata,
                                           int offset,
                                           byte[] computed_mac,
                                           int macStart)
                                    throws OneWireIOException,
                                           OneWireException

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