com.dalsemi.onewire.container
Class OneWireContainer18

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

public class OneWireContainer18
extends OneWireContainer

OneWire container for iButton family type 18 (hex), DS1963S.

This container makes use of several optimizations to help it run fast on TINI. These optimizations do little for the PC, but they do not slow down the PC. Most methods are synchronized because they all access an instance byte array. This is less expensive than creating new byte arrays for every method, because in virtually all cases there should not be contention for the resources in this container between threads. Threads should use the DSPortAdapter methods beginExclusive and endExclusive to synchronize on the OneWire port.

This container provides the functionality to use the raw power of the DS1963S. It does not immediately implement transactions and authentication. The class com.dalsemi.onewire.container.SHAiButton does these. The SHAiButton class exists on top of this class, making higher level calls to implement transactions.

Notice that for maximum performance, you should call the method setSpeedCheck() with an argument false before any other methods that access the OneWire. A program that calls this function is assumed to understand and control the speed of communication. If not called, a call to the function OneWireContainer.doSpeed() will occur in almost every function. While this should guarantee that you never have the bus at an unknown speed, it will slow down your throughput considerably.

Version:
0.00, 28 Aug 2000
See Also:
SHAiButton

Field Summary
static byte AUTH_HOST
          Field AUTH_HOST
static byte COMPUTE_CHALLENGE
          Field COMPUTE_CHALLENGE
static byte COMPUTE_FIRST_SECRET
          Field COMPUTE_FIRST_SECRET
static byte COMPUTE_NEXT_SECRET
          Field COMPUTE_NEXT_SECRET
static byte COMPUTE_SHA
          Field COMPUTE_SHA
static byte COPY_SCRATCHPAD
          Field COPY_SCRATCHPAD
static byte ERASE_SCRATCHPAD
          Field ERASE_SCRATCHPAD
 byte ES
          Field TA1, TA2, ES
static byte MATCH_SCRATCHPAD
          Field MATCH_SCRATCHPAD
static byte READ_AUTHENTICATED_PAGE
          Field READ_AUTHENTICATED_PAGE
static byte READ_MEMORY
          Field READ_MEMORY
static byte READ_SCRATCHPAD
          Field READ_SCRATCHPAD
static byte RESUME
          Field RESUME
static byte SIGN_DATA_PAGE
          Field SIGN_DATA_PAGE
 byte TA1
          Field TA1, TA2, ES
 byte TA2
          Field TA1, TA2, ES
static byte VALIDATE_DATA_PAGE
          Field VALIDATE_DATA_PAGE
static byte WRITE_SCRATCHPAD
          Field WRITE_SCRATCHPAD
 
Constructor Summary
OneWireContainer18()
          Default constructor
OneWireContainer18(DSPortAdapter sourceAdapter, byte[] newAddress)
          Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
OneWireContainer18(DSPortAdapter sourceAdapter, long newAddress)
          Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
OneWireContainer18(DSPortAdapter sourceAdapter, java.lang.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 page, byte[] bind_data, byte[] bind_code, int secret_number)
          Binds an installed secret to a DS1963S byte using well-known binding data and the DS1963S's unique identification number.
 boolean copyScratchPad()
          Copies the contents of the scratchpad to the target destination that was specified in a call to write scratchpad or erase scratchpad.
 boolean eraseScratchPad(int page)
          Erases the scratchpad of the DS1963S.
 java.lang.String getAlternateNames()
          Retrieve the alternate Dallas Semiconductor part numbers or names.
 java.lang.String getDescription()
          Retrieve a short description of the function of the iButton type.
 int getMaxSpeed()
          Returns the maximum speed this iButton can communicate at.
 java.util.Enumeration getMemoryBanks()
          Return an enumeration of memory banks.
 java.lang.String getName()
          Retrieve the Dallas Semiconductor part number of the iButton as a string.
 boolean installMasterSecret(int page, byte[] secret, int secret_number)
          Installs a secret on a DS1963S.
 boolean matchScratchPad(byte[] mac)
          After a Validate command, the scratchpad contains a signature that cannot be read, but must be checked against another signature.
 boolean readAuthenticatedPage(int pageNum, byte[] data, int start)
          Reads and authenticates a page.
 void readMemoryPage(int pageNum, byte[] data, int start)
          Reads a memory page from the DS1963S.
 int readScratchPad(byte[] data, int start)
          Read the contents of the scratchpad.
 void setSpeedCheck(boolean doSpeedCheck)
          To ensure that all parts can talk to the onewire bus at their desired speed, each method contains a call to doSpeed().
 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.
 boolean SHAFunction(byte function)
          Performs one of the DS1963S's SHA functions (see the datasheet for more on these functions).
 boolean SHAFunction(byte function, int T)
          Performs one of the DS1963S's SHA functions (see the datasheet for more on these functions).
 void useResume(boolean set)
          Tells the OneWireContainer18 whether it can use the resume command.
 boolean waitForSuccessfulFinish()
          Waits for the DS1963S's output to alternate.
 boolean writeDataPage(int page_number, byte[] page_data)
          Writes a data page on the DS1963S.
 boolean writeScratchPad(int targetPage, int targetPageOffset, byte[] inputbuffer, int start, int length)
          Write to the scratchpad.
 
Methods inherited from class com.dalsemi.onewire.container.OneWireContainer
doSpeed, getAdapter, getAddress, getAddressAsLong, getAddressAsString, isAlarming, isPresent, setSpeed, setupContainer, setupContainer
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TA1

public byte TA1
Field TA1, TA2, ES

TA2

public byte TA2
Field TA1, TA2, ES

ES

public byte ES
Field TA1, TA2, ES

READ_MEMORY

public static final byte READ_MEMORY
Field READ_MEMORY

WRITE_SCRATCHPAD

public static final byte WRITE_SCRATCHPAD
Field WRITE_SCRATCHPAD

MATCH_SCRATCHPAD

public static final byte MATCH_SCRATCHPAD
Field MATCH_SCRATCHPAD

ERASE_SCRATCHPAD

public static final byte ERASE_SCRATCHPAD
Field ERASE_SCRATCHPAD

READ_SCRATCHPAD

public static final byte READ_SCRATCHPAD
Field READ_SCRATCHPAD

READ_AUTHENTICATED_PAGE

public static final byte READ_AUTHENTICATED_PAGE
Field READ_AUTHENTICATED_PAGE

COPY_SCRATCHPAD

public static final byte COPY_SCRATCHPAD
Field COPY_SCRATCHPAD

COMPUTE_SHA

public static final byte COMPUTE_SHA
Field COMPUTE_SHA

COMPUTE_FIRST_SECRET

public static final byte COMPUTE_FIRST_SECRET
Field COMPUTE_FIRST_SECRET

COMPUTE_NEXT_SECRET

public static final byte COMPUTE_NEXT_SECRET
Field COMPUTE_NEXT_SECRET

VALIDATE_DATA_PAGE

public static final byte VALIDATE_DATA_PAGE
Field VALIDATE_DATA_PAGE

SIGN_DATA_PAGE

public static final byte SIGN_DATA_PAGE
Field SIGN_DATA_PAGE

COMPUTE_CHALLENGE

public static final byte COMPUTE_CHALLENGE
Field COMPUTE_CHALLENGE

AUTH_HOST

public static final byte AUTH_HOST
Field AUTH_HOST

RESUME

public static final byte RESUME
Field RESUME
Constructor Detail

OneWireContainer18

public OneWireContainer18()
Default constructor

OneWireContainer18

public OneWireContainer18(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

OneWireContainer18

public OneWireContainer18(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

OneWireContainer18

public OneWireContainer18(DSPortAdapter sourceAdapter,
                          java.lang.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. Override the OneWireContainer method because it has a malloc in it. This just makes it a little faster for TINI.
Overrides:
setupContainer in class OneWireContainer
Parameters:
sourceAdapter - adapter object required to communicate with this iButton.
newAddress - address of this 1-Wire device

getName

public java.lang.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 java.lang.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. There can also be nicknames such as 'Crypto iButton'.
Overrides:
getAlternateNames in class OneWireContainer
Returns:
string represetation of the alternate names.

getDescription

public java.lang.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

getMemoryBanks

public java.util.Enumeration getMemoryBanks()
Return an enumeration of memory banks. Look at the MemoryBank, PagedMemoryBank and OTPMemoryBank classes.
Overrides:
getMemoryBanks in class OneWireContainer
Following copied from class: com.dalsemi.onewire.container.OneWireContainer
Returns:
enumeration of memory banks to read and write memory on this iButton or 1-Wire device.

setSpeedCheck

public void setSpeedCheck(boolean doSpeedCheck)
To ensure that all parts can talk to the onewire bus at their desired speed, each method contains a call to doSpeed(). However, this is an expensive operation and the functions that talk to the DS1963S must be fast. Therefore, you can handle the speed in your application without the expense of the doSpeed call by calling this with false. The default behaviour is to call doSpeed().
Parameters:
doSpeedCheck - True if you want doSpeed() called before every onewire bus access. False to skip this expensive call.

useResume

public void useResume(boolean set)
Tells the OneWireContainer18 whether it can use the resume command. If it uses the resume command, the entire 9 byte select sequence is abandoned for a one byte resume command. If you talk to another device, you must turn resume to false, select the part again, and then set resume to true.
Parameters:
set - True means use the resume command instead of the select command.

eraseScratchPad

public boolean eraseScratchPad(int page)
                        throws OneWireIOException,
                               OneWireException
Erases the scratchpad of the DS1963S. This must be used to do any normal memory operations, as the cryptographic features of the button leave the memory in 'hidden' mode, so that you cannot read the scratchpad, copy to normal memory space, or write the scratchpad. Fills the scratchpad with 0x0ff.
Parameters:
page - The target page number. Normally this does not matter, but in cases where you would like to erase a memory page, you would call this method with the page number, then read scratchpad to read back the registers, then copy scratchpad to erase the page.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

waitForSuccessfulFinish

public boolean waitForSuccessfulFinish()
                                throws OneWireIOException,
                                       OneWireException
Waits for the DS1963S's output to alternate. Several operations must wait for the DS1963S to stop sending 0x0ff's and begin alternating its bits. This method reads until it finds a non-0x0ff byte or until it reaches a specified number of tries, indicating failure.
Returns:
True if the DS1963S completed its operation successfully. False if the DS1963S failed its operation. See the datasheet for which operations function in this way.
Throws:
OneWireIOException -  
OneWireException -  

readMemoryPage

public void readMemoryPage(int pageNum,
                           byte[] data,
                           int start)
                    throws OneWireIOException,
                           OneWireException
Reads a memory page from the DS1963S. Pages 0-15 are normal memory pages. Pages 16 and 17 are the secrets, so 0x0ff's are returned by the iButton. Page 18 is the scratchpad--the data is returned if the part is not in hidden mode (else 0x0ff's are returned). Pages 19 and 20 are the write cycle counters. Page 21 contains the counter for the pseudo random number generator.
Parameters:
pageNum - Page number to read.
data - Byte array for the return of the data. This array must be AT LEAST 32 bytes long.
start - Location in the byte array to start copying page data to.
Throws:
OneWireIOException -  
OneWireException -  

readAuthenticatedPage

public boolean readAuthenticatedPage(int pageNum,
                                     byte[] data,
                                     int start)
                              throws OneWireIOException,
                                     OneWireException
Reads and authenticates a page. See readMemoryPage for a description of page numbers. This method will also generate a signature for the selected page, used in the authentication of roaming (User) iButtons. Extra data is returned with the page as well--such as the write cycle counter for the page and the write cycle counter of the selected secret page.
Parameters:
pageNum - Page number to read and authenticate.
data - Byte array for the page data plus extra information (2 write cycle coutnersof 4 bytes each, one 2 byte CRC, appended after 32 bytes of the data page). This byte array must be AT LEAST 42 bytes long.
start - Offset to copy into the array data.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

writeScratchPad

public boolean writeScratchPad(int targetPage,
                               int targetPageOffset,
                               byte[] inputbuffer,
                               int start,
                               int length)
                        throws OneWireIOException,
                               OneWireException
Write to the scratchpad. Note that the addresses passed to this method will be the addresses the data is copied to if the copy function is called afterward. Also note that if too many bytes are tried to write, this method will truncate the data so that only valid data will be sent.
Parameters:
targetPage - The page number this data will eventually be copied to.
targetPageOffset - The offset on the page to copy this data to.
inputbuffer - The data that will be copied into the scratchpad.
start - Offset into the input buffer for the data to write.
length - The number of bytes to write.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

matchScratchPad

public boolean matchScratchPad(byte[] mac)
                        throws OneWireIOException,
                               OneWireException
After a Validate command, the scratchpad contains a signature that cannot be read, but must be checked against another signature. This method allows you to pass in an outside signature to see if it equals the hidden signature in the DS1963S's scratchpad.
Parameters:
mac - Byte array containing the signature. Must be at least 20 bytes long, and the signature must start at offset 0.
Returns:
True if the signature matches.
Throws:
OneWireIOException -  
OneWireException -  

readScratchPad

public int readScratchPad(byte[] data,
                          int start)
                   throws OneWireIOException,
                          OneWireException
Read the contents of the scratchpad. If the part is in hidden mode, 0x0ff's will be returned.
Parameters:
data - Byte array to hold the contents of the scratchpad. Up to 32 bytes will be copied. Fewer bytes may be copied if the target address stored inside the DS1963S is not a multiple of 32.
start - Offset into the byte array to copy the scratchpad data.
Returns:
The number of bytes read, or -1 if there was a failure.
Throws:
OneWireIOException -  
OneWireException -  

copyScratchPad

public boolean copyScratchPad()
                       throws OneWireIOException,
                              OneWireException
Copies the contents of the scratchpad to the target destination that was specified in a call to write scratchpad or erase scratchpad. You must call read scratchpad before this method to verify the target address registers in the DS1963S.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

installMasterSecret

public boolean installMasterSecret(int page,
                                   byte[] secret,
                                   int secret_number)
                            throws OneWireIOException,
                                   OneWireException
Installs a secret on a DS1963S. The secret is written in partial phrases of 47 bytes (32 bytes to a memory page, 15 bytes to the scratchpad) and is cumulative until the entire secret is processed.
Parameters:
page - The page number used to write the partial secrets to. In most cases, this should be equal to secret_number or secret_number+8.
secret - A byte array containing the entire secret to be installed. This method will be faster if this byte array's length is a multiple of 47, however--installing master secrets should be a part of initialization, so a slight speed increase is probably not very important in most cases.
secret_number - The secret 'page' to use. Secrets are stored across pages 16 and 17, in 8 byte chunks (there are 8 secrets). This should be a number between 0 and 8.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

bindSecretToiButton

public boolean bindSecretToiButton(int page,
                                   byte[] bind_data,
                                   byte[] bind_code,
                                   int secret_number)
                            throws OneWireIOException,
                                   OneWireException
Binds an installed secret to a DS1963S byte using well-known binding data and the DS1963S's unique identification number. This makes the secret unique for this iButton. Coprocessor iButtons use this function to recreate the iButton's secret to verify authentication.
Parameters:
page - The page number that has the master secret installed. In this case, the page number does not need to be equivalent to the secret_number modulo 8. The new secret (installed secret + binding secret) is generated from this page but can be copied into another secret. User iButtons should bind to the same page the secret was installed on. Coprocessor iButtons must copy to a new secret to preserve the general system authentication secret.
bind_data - 32 bytes of binding data used to bind the iButton to the system.
bind_code - This byte array can be of two lengths. A 15-length byte array is unaltered and placed in the scratchpad for the binding. A 7-length byte array is combined with the page number and DS1963S unique ID and then placed in the scratchpad. Coprocessors should use a pre-formatted 15-length byte array. User iButtons should let the method format for them (i.e. use the 7-length byte array option)
secret_number - Secret number to copy the resulting secret to. See the discussion on page number.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

writeDataPage

public boolean writeDataPage(int page_number,
                             byte[] page_data)
                      throws OneWireIOException,
                             OneWireException
Writes a data page on the DS1963S. This method is the equivalent of calling: eraseScratchpad writeScratchpad readScratchpad copyScratchpad with a few optimizations.
Parameters:
page_number - Page number to write.
page_data - Byte array with the page data to write. This array must be at least 32 bytes long.
Returns:
True if successful.
Throws:
OneWireIOException -  
OneWireException -  

SHAFunction

public boolean SHAFunction(byte function)
                    throws OneWireIOException,
                           OneWireException
Performs one of the DS1963S's SHA functions (see the datasheet for more on these functions).
Parameters:
function - The function code to use (i.e. COMPUTE_NEXT_SECRET)
Returns:
True if the function successfully completed.
Throws:
OneWireIOException -  
OneWireException -  

SHAFunction

public boolean SHAFunction(byte function,
                           int T)
                    throws OneWireIOException,
                           OneWireException
Performs one of the DS1963S's SHA functions (see the datasheet for more on these functions).
Parameters:
function - The function code to use (i.e. COMPUTE_NEXT_SECRET)
T - The address to use (page number).
Returns:
True if the function successfully completed.
Throws:
OneWireIOException -  
OneWireException -