Package com.dalsemi.onewire.container

Class OneWireContainer02

  • public class OneWireContainer02
extends OneWireContainer

    1-Wire® container that encapsulates the functionality of the 1-Wire family type 02 (hex), Maxim Integrated Products 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 to +70
    • 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

    • Constructor Detail

      • 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,
                          java.lang.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 java.lang.String getName()
        Description copied from class: OneWireContainer
        Retrieves the Maxim Integrated Products part number of the 1-Wire device as a String. For example 'Crypto iButton' or 'DS1992'.
        Overrides:
        getName in class OneWireContainer
        Returns:
        1-Wire device name

      • getAlternateNames

        public java.lang.String getAlternateNames()
        Description copied from class: OneWireContainer
        Retrieves the alternate Maxim Integrated Products 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
        Returns:
        1-Wire device alternate names

      • getDescription

        public java.lang.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
        Returns:
        device functional description

      • writeScratchpad

        public void writeScratchpad​(int addr,
                            byte[] data)
                     throws OneWireIOException,
                            OneWireException,
                            java.lang.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:
        java.lang.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,
                           java.lang.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:
        java.lang.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,
                         java.lang.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:
        java.lang.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,
                       java.lang.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:
        java.lang.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,
                          java.lang.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:
        java.lang.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,
                        java.lang.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 - password for the subkey
        data - data to be written
        Throws:
        java.lang.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