OneWireContainer33 Class Reference

Inherits com::dalsemi::onewire::container::OneWireContainer.

List of all members.


Detailed Description

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

Features

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:

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, 0);
        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

See also:
com.dalsemi.onewire.application.sha.SHAiButtonUser33
Version:
0.00, 19 Dec 2000
Author:
JPE

Public Member Functions

 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.
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.
String getName ()
 Retrieve the Maxim Integrated Products part number of the iButton as a string.
String getAlternateNames ()
 Retrieve the alternate Maxim Integrated Products part numbers or names.
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.
MemoryBankScratchSHAEE getScratchpadMemoryBank ()
 Returns the instance of the Scratchpad memory bank.
MemoryBankSHAEE getStatusPageMemoryBank ()
 Returns the instance of the Status page memory bank.
MemoryBankSHAEE getMemoryBankForPage (int page)
 Returns the instance of the memory bank for a particular page.
void setContainerSecret (byte[] newSecret, int offset)
 Sets the bus master secret for this DS2432.
void getContainerSecret (byte[] secretBuf, int offset)
 Get the secret of this device as an array of bytes.
boolean isContainerSecretSet () throws OneWireIOException, OneWireException
 Get the current status of the secret.
boolean isSecretWriteProtected () throws OneWireIOException, OneWireException
 Get the status of the secret, if it is write protected.
void setChallenge (byte[] challengeset, int offset)
 Sets the challenge for the Read Authenticate Page.
void getChallenge (byte[] get, int offset)
 Get the challenge of this device as an array of bytes.
boolean isWriteProtectAllSet () throws OneWireIOException, OneWireException
 Get the status of all the pages, if they are write protected.
void writeProtectSecret () throws OneWireIOException, OneWireException
 Write protects the secret for the DS2432.
void writeProtectAll () throws OneWireIOException, OneWireException
 Write protect pages 0 to 3.
void setEPROMModePageOne () throws OneWireIOException, OneWireException
 Sets the EPROM mode for page 1.
boolean isPageOneEPROMmode () throws OneWireIOException, OneWireException
 Tells if page one is in EPROM mode.
void writeProtectPageZero () throws OneWireIOException, OneWireException
 Write protect page zero only.
boolean isWriteProtectPageZeroSet () throws OneWireIOException, OneWireException
 Get the status of page zero, if it is write protected.
void computeNextSecret (int pageNum, byte[] partialsecret, int offset) throws OneWireIOException, OneWireException
 Compute Next Secret.
void computeNextSecret (int pageNum) throws OneWireIOException, OneWireException
 Compute Next Secret using the current contents of data page and scratchpad.
boolean loadFirstSecret (byte[] data, int offset) throws OneWireIOException, OneWireException
 Load First Secret.
boolean refreshPage (int page, int offset) throws OneWireException, OneWireIOException
 Refreshes a particular 8-byte set of data on a given page.
boolean refreshPage (int page) throws OneWireException, OneWireIOException
 Refreshes all 32 bytes of data on a given page.
boolean installMasterSecret (int page, byte[] newSecret) throws OneWireIOException, OneWireException
boolean bindSecretToiButton (int pageNum, byte[] bindData) throws OneWireIOException, OneWireException
boolean writeDataPage (int targetPage, byte[] pageData) throws OneWireIOException, OneWireException
boolean writeDataPage (int targetPage, byte[] pageData, int offset) throws OneWireIOException, OneWireException
boolean writeScratchpad (int targetPage, int targetPageOffset, byte[] inputbuffer, int start, int length) throws OneWireIOException, OneWireException
void readScratchpad (byte[] scratchpad, int offset, byte[] extraInfo) throws OneWireIOException, OneWireException
 Read from the Scratch Pad, which is a max of 8 bytes.
boolean copyScratchpad (int targetPage, int targetPageOffset, byte[] copy_auth, int authStart) throws OneWireIOException, OneWireException
 Copy all 8 bytes of the Sratch Pad to a certain page and offset in memory.
boolean copyScratchpad (int targetPage, int targetPageOffset) throws OneWireIOException, OneWireException
 Copy all 8 bytes of the Sratch Pad to a certain page and offset in memory.
boolean readMemoryPage (int page, byte[] pageData, int offset) throws OneWireIOException, OneWireException
 Reads a page of memory.
boolean readAuthenticatedPage (int page, byte[] pagedata, int offset, byte[] computed_mac, int macStart) throws OneWireIOException, OneWireException

Static Public Member Functions

static boolean isMACValid (int addr, byte[] SerNum, byte[] memory, byte[] mac, byte[] challenge, byte[] secret)
 Authenticates page data given a MAC.

Protected Member Functions

boolean adapterSet ()
 Tells whether an adapter has been set.
boolean checkStatus () throws OneWireIOException, OneWireException
 To check the status of the part.

Protected Attributes

boolean secretSet
 Flag to indicate if the secret has been set.
boolean secretProtected
 Flag to indicate if the secret is write protected.
boolean setAdapter
 Flag to indicate if the adapter has been specified.
boolean container_check
 Flag to indicate if the status has been checked.

Static Protected Attributes

static final byte[] ffBlock
 block of 0xFF's used for faster read pre-fill of 1-Wire blocks
static final byte[] zeroBlock
 block of 0xFF's used for faster erase of blocks

Constructor & Destructor Documentation

Default Constructor OneWireContainer33.

Must call setupContainer before using.

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


Member Function Documentation

boolean adapterSet (  )  [protected]

Tells whether an adapter has been set.

Returns:
boolean telling weather an adapter has been set.

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.

Parameters:
sourceAdapter adapter object required to communicate with this iButton.
newAddress address of this 1-Wire device

Reimplemented from OneWireContainer.

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.

Parameters:
sourceAdapter adapter object required to communicate with this iButton.
newAddress address of this 1-Wire device

Reimplemented from OneWireContainer.

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.

Parameters:
sourceAdapter adapter object required to communicate with this iButton.
newAddress address of this 1-Wire device

Reimplemented from OneWireContainer.

String getName (  ) 

Retrieve the Maxim Integrated Products part number of the iButton as a string.

For example 'DS1992'.

Returns:
string represetation of the iButton name.

Reimplemented from OneWireContainer.

String getAlternateNames (  ) 

Retrieve the alternate Maxim Integrated Products part numbers or names.

A 'family' of MicroLAN devices may have more than one part number depending on packaging.

Returns:
the alternate names for this iButton or 1-Wire device

Reimplemented from OneWireContainer.

String getDescription (  ) 

Retrieve a short description of the function of the iButton type.

Returns:
string represetation of the function description.

Reimplemented from OneWireContainer.

int getMaxSpeed (  ) 

Returns the maximum speed this iButton can communicate at.

Returns:
max. communication speed.

Reimplemented from OneWireContainer.

Enumeration getMemoryBanks (  ) 

Get an enumeration of memory bank instances that implement one or more of the following interfaces: MemoryBank, PagedMemoryBank, and OTPMemoryBank.

Returns:
Enumeration of memory banks

Reimplemented from OneWireContainer.

MemoryBankScratchSHAEE getScratchpadMemoryBank (  ) 

Returns the instance of the Scratchpad memory bank.

Contains methods for reading/writing the Scratchpad contents. Also, methods for Load First Secret, Compute Next Secret, and Refresh Scratchpad

Returns:
the instance of the Scratchpad memory bank

MemoryBankSHAEE getStatusPageMemoryBank (  ) 

Returns the instance of the Status page memory bank.

Returns:
the instance of the Status page memory bank

MemoryBankSHAEE getMemoryBankForPage ( int  page  ) 

Returns the instance of the memory bank for a particular page.

Parameters:
page the page for the requested memory bank;
Returns:
the instance of the memory bank for the specified page

void setContainerSecret ( byte[]  newSecret,
int  offset 
)

Sets the bus master secret for this DS2432.

Parameters:
newSecret Secret for this DS2432.
offset index into array to copy the secret from

void getContainerSecret ( byte[]  secretBuf,
int  offset 
)

Get the secret of this device as an array of bytes.

Parameters:
secretBuf array of bytes for holding the container secret
offset index into array to copy the secret to

boolean isContainerSecretSet (  )  throws OneWireIOException, OneWireException

Get the current status of the secret.

Returns:
boolean telling if the secret is set
Exceptions:
OneWireIOException 
OneWireException 

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.
Exceptions:
OneWireIOException 
OneWireException 

void setChallenge ( byte[]  challengeset,
int  offset 
)

Sets the challenge for the Read Authenticate Page.

Parameters:
challengeset Challenge for all the memory banks.

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

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.
Exceptions:
OneWireIOException 
OneWireException 

void setEPROMModePageOne (  )  throws OneWireIOException, OneWireException

Sets the EPROM mode for page 1.

After setting, Page One can only be written to once.

boolean isPageOneEPROMmode (  )  throws OneWireIOException, OneWireException

Tells if page one is in EPROM mode.

Returns:
boolean telling if page one is in EPROM mode.
Exceptions:
OneWireIOException 
OneWireException 

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.
Exceptions:
OneWireIOException 
OneWireException 

void computeNextSecret ( int  pageNum,
byte[]  partialsecret,
int  offset 
) 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.

void computeNextSecret ( int  pageNum  )  throws OneWireIOException, OneWireException

Compute Next Secret using the current contents of data page and scratchpad.

Parameters:
addr address of page to use for the next secret computation.

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

Load First Secret.

Returns:
boolean saying if first secret was loaded
Exceptions:
OneWireIOException 
OneWireException 

boolean refreshPage ( int  page,
int  offset 
) throws OneWireException, OneWireIOException

Refreshes a particular 8-byte set of data on a given page.

This will correct any weakly-programmed EEPROM bits. This feature is only available on the DS1961S, but is safely ignored on the DS2432. The refresh consists of a Refresh Scratchpad command followed by a Load First Secret to the same offset.

Parameters:
page the page number that contains the 8-bytes to refresh.
offset the offset into the page for the 8-bytes to refresh.
Returns:
true if refresh is successful.

boolean refreshPage ( int  page  )  throws OneWireException, OneWireIOException

Refreshes all 32 bytes of data on a given page.

This will correct any weakly-programmed EEPROM bits. This feature is only available on the DS1961S, but is safely ignored on the DS2432. The refresh consists of a Refresh Scratchpad command followed by a Load First Secret to the same offset, for all 8-byte offsets on the page.

Parameters:
page the page number that will be refreshed.
Returns:
true if refresh is successful.

boolean checkStatus (  )  throws OneWireIOException, OneWireException [protected]

To check the status of the part.

Returns:
boolean saying the part has been checked or was checked.

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

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 3 bytes written to the scratch pad used in calculating the mac

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

Installs a secret on a DS1961S/DS2432. The secret is written in partial phrases of 47 bytes (32 bytes to a memory page, 8 bytes to the scratchpad, 7 bytes are discarded (but included for compatibility with DS193S)) and is cumulative until the entire secret is processed.

On TINI, this method will be slightly faster if the secret's length is divisible by 47. However, since secret key generation is a part of initialization, it is probably not necessary.

Parameters:
page the page number used to write the partial secrets to
secret the entire secret, in partial phrases, to be installed
Returns:
true if successful
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter
See also:
bindSecretToiButton(int,byte[])

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

Binds an installed secret to a DS1961S/DS2432 by using well-known binding data and the DS1961S/DS2432's unique address. This makes the secret unique for this iButton.

Parameters:
page the page number that has the master secret already installed
bind_data 32 bytes of binding data used to bind the iButton to the system
Returns:
true if successful
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter
See also:
installMasterSecret(int,byte[])

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

Writes a data page to the DS1961S/DS2432.

Parameters:
page_number page number to write
page_data page data to write (must be at least 32 bytes long)
Returns:
true if successful, false if the operation failed
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

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

Writes a data page to the DS1961S/DS2432.

Parameters:
page_number page number to write
page_data page data to write (must be at least 32 bytes long)
offset the offset to start copying the 32-bytes of page data.
Returns:
true if successful, false if the operation failed
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

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

Writes data to the scratchpad. In order to write to a data page using this method, next call readScratchPad(), and then copyScratchPad(). Note that the addresses passed to this method will be the addresses the data is copied to if the copyScratchPad() method is called afterward.

Also note that if too many bytes are written, this method will truncate the data so that only a valid number of bytes 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 number of bytes to write
Returns:
true if successful, false on a CRC error
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter

void readScratchpad ( byte[]  scratchpad,
int  offset,
byte[]  extraInfo 
) throws OneWireIOException, OneWireException

Read from the Scratch Pad, which is a max of 8 bytes.

Parameters:
scratchpad byte array to place read data into length of array is always pageLength.
offset offset into readBuf to pug data
extraInfo byte array to put extra info read into (TA1, TA2, e/s byte) Can be 'null' if extra info is not needed.
Exceptions:
OneWireIOException 
OneWireException 

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

Copy all 8 bytes of the Sratch Pad to a certain page and offset in memory.

Parameters:
targetPage the page to copy the data to
targetPageOffset the offset into the page to copy to
copy_auth byte[] containing write authorization
authStart the offset into the copy_auth array where the authorization begins.
Exceptions:
OneWireIOException 
OneWireException 

boolean copyScratchpad ( int  targetPage,
int  targetPageOffset 
) throws OneWireIOException, OneWireException

Copy all 8 bytes of the Sratch Pad to a certain page and offset in memory.

The container secret must be set so that the container can produce the correct MAC.

Parameters:
targetPage the page to copy the data to
targetPageOffset the offset into the page to copy to
Exceptions:
OneWireIOException 
OneWireException 

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

Reads a page of memory.

Parameters:
page page number to read packet from
pageData byte array to place read data into
offset offset into readBuf to place data
Exceptions:
OneWireIOException 
OneWireException 

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

Reads and authenticates a page. See readMemoryPage() for a description of page numbers and their contents. This method will also generate a signature for the selected page, used in the authentication of roving (User) iButtons.

Parameters:
pageNum page number to read and authenticate
pagedata array for the page data.
offset offset to copy into the array
computed_mac array for the MAC returned by the device.
macStart offset to copy into the mac array
Returns:
true if successful, false if the operation failed while waiting for the DS1963S's output to alternate
Exceptions:
OneWireIOException on a 1-Wire communication error such as reading an incorrect CRC from a 1-Wire device. This could be caused by a physical interruption in the 1-Wire Network due to shorts or a newly arriving 1-Wire device issuing a 'presence pulse'.
OneWireException on a communication or setup error with the 1-Wire adapter


Member Data Documentation

boolean secretSet [protected]

Flag to indicate if the secret has been set.

boolean secretProtected [protected]

Flag to indicate if the secret is write protected.

boolean setAdapter [protected]

Flag to indicate if the adapter has been specified.

boolean container_check [protected]

Flag to indicate if the status has been checked.


The documentation for this class was generated from the following file:

Generated on Thu Aug 28 15:42:36 2008 for 1-Wire API for .NET by  doxygen 1.5.6