PagedMemoryBank Interface Reference

Inherits com::dalsemi::onewire::container::MemoryBank.

Inherited by MemoryBankAD, MemoryBankEE, MemoryBankNV, MemoryBankScratch, MemoryBankSHAEE, and OTPMemoryBank.

List of all members.


Detailed Description

Paged Memory bank interface for iButtons (or 1-Wire devices) with page based memory. This interface extents the base functionality of the super-interface MemoryBank by providing paged based services.

This interface has methods to read and write a packet structure called the UDP (Universal Data Packet). This structure has a length byte, data, and an inverted CRC16. See Maxim Integrated Products Application Note 114 for details: http://dbserv.maxim-ic.com/appnotes.cfm?appnote_number=114

The MemoryBank methods can be organized into the following categories:

Usage

Example 1

Display some features of PagedMemoryBank instance 'pmb':

 
  System.out.print("PagedMemoryBank has: " + pmb.getNumberPages() + " pages of length ");
  System.out.print(pbank.getPageLength() + " bytes ");
  if (bank.isGeneralPurposeMemory())
    System.out.print("giving " + pbank.getMaxPacketDataLength() + " bytes Packet data payload");
  System.out.println();

  if (pbank.hasPageAutoCRC())
    System.out.print("PagedMemoryBank has device generated CRC");
  

Example 2

Write a packet into the first page of a PagedMemoryBank instance 'pmb':

 
  byte[] write_buf = new byte[pmb.getMaxPacketDataLength()];
  for (int i = 0; i < write_buf.length; i++)
      write_buf[i] = (byte)0;

  mb.writePagePacket(0, write_buf, 0, write_buf.length);
  

Example 3

Read all of the pages of a PagedMemoryBank instance 'pmb' with device CRC verification:

 
  byte[] read_buf = new byte[pmb.getPageLength()];

  if (pmb.hasAutoCRC())
  {
     // loop to read each page with CRC 
     for (int pg = 0; pg < pmb.getNumberPages(); pg++)
     {
        // use 'readContinue' arguement to only access device on first page
        pmb.readPageCRC(pg, (pg == 0), read_buf, 0);

        // do something with data in read_buf ... 
     }
  }
  else
     System.out.println("PagedMemoryBank does not support device generated CRC");

  

See also:
com.dalsemi.onewire.container.MemoryBank

com.dalsemi.onewire.container.OTPMemoryBank

com.dalsemi.onewire.container.OneWireContainer04

com.dalsemi.onewire.container.OneWireContainer06

com.dalsemi.onewire.container.OneWireContainer08

com.dalsemi.onewire.container.OneWireContainer09

com.dalsemi.onewire.container.OneWireContainer0A

com.dalsemi.onewire.container.OneWireContainer0B

com.dalsemi.onewire.container.OneWireContainer0C

com.dalsemi.onewire.container.OneWireContainer0F

com.dalsemi.onewire.container.OneWireContainer12

com.dalsemi.onewire.container.OneWireContainer13

com.dalsemi.onewire.container.OneWireContainer14

com.dalsemi.onewire.container.OneWireContainer18

com.dalsemi.onewire.container.OneWireContainer1A

com.dalsemi.onewire.container.OneWireContainer1D

com.dalsemi.onewire.container.OneWireContainer20

com.dalsemi.onewire.container.OneWireContainer21

com.dalsemi.onewire.container.OneWireContainer23

Version:
0.01, 11 Dec 2000
Author:
DS

Public Member Functions

int getNumberPages ()
 Gets the number of pages in this memory bank.
int getPageLength ()
 Gets raw page length in bytes in this memory bank.
int getMaxPacketDataLength ()
 Gets Maximum data page length in bytes for a packet read or written in this memory bank.
boolean hasPageAutoCRC ()
 Checks to see if this memory bank's pages can be read with the contents being verified by a device generated CRC.
boolean haveExtraInfo ()
 Checks to see if this memory bank's pages deliver extra information outside of the normal data space, when read.
boolean hasExtraInfo ()
 Checks to see if this memory bank's pages deliver extra information outside of the normal data space, when read.
int getExtraInfoLength ()
 Gets the length in bytes of extra information that is read when reading a page in this memory bank.
String getExtraInfoDescription ()
 Gets a string description of what is contained in the Extra Information returned when reading pages in this memory bank.
void readPage (int page, boolean readContinue, byte[] readBuf, int offset) throws OneWireIOException, OneWireException
 Reads a page in this memory bank with no CRC checking (device or data).
void readPage (int page, boolean readContinue, byte[] readBuf, int offset, byte[] extraInfo) throws OneWireIOException, OneWireException
 Reads a page in this memory bank with extra information with no CRC checking (device or data).
int readPagePacket (int page, boolean readContinue, byte[] readBuf, int offset) throws OneWireIOException, OneWireException
 Reads a Universal Data Packet.
int readPagePacket (int page, boolean readContinue, byte[] readBuf, int offset, byte[] extraInfo) throws OneWireIOException, OneWireException
 Reads a Universal Data Packet and extra information.
void writePagePacket (int page, byte[] writeBuf, int offset, int len) throws OneWireIOException, OneWireException
 Writes a Universal Data Packet.
void readPageCRC (int page, boolean readContinue, byte[] readBuf, int offset) throws OneWireIOException, OneWireException
 Reads a complete memory page with CRC verification provided by the device.
void readPageCRC (int page, boolean readContinue, byte[] readBuf, int offset, byte[] extraInfo) throws OneWireIOException, OneWireException
 Reads a complete memory page with CRC verification provided by the device with extra information.

Member Function Documentation

int getNumberPages (  ) 

Gets the number of pages in this memory bank.

The page numbers are then always 0 to (getNumberPages() - 1).

Returns:
number of pages in this memory bank

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

int getPageLength (  ) 

Gets raw page length in bytes in this memory bank.

Returns:
page length in bytes in this memory bank

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

int getMaxPacketDataLength (  ) 

Gets Maximum data page length in bytes for a packet read or written in this memory bank.

See the readPagePacket and writePagePacket methods. This method is only usefull if this memory bank is general purpose memory.

Returns:
max packet page length in bytes in this memory bank
See also:
readPagePacket(int,boolean,byte[],int) readPagePacket

readPagePacket(int,boolean,byte[],int,byte[]) readPagePacket(extra)

writePagePacket(int,byte[],int,int) writePagePacket

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

boolean hasPageAutoCRC (  ) 

Checks to see if this memory bank's pages can be read with the contents being verified by a device generated CRC.

This is used to see if the readPageCRC method can be used.

Returns:
true if this memory bank can be read with self generated CRC
See also:
readPageCRC(int,boolean,byte[],int) readPageCRC

readPageCRC(int,boolean,byte[],int,byte[]) readPageCRC(extra)

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

boolean haveExtraInfo (  ) 

Checks to see if this memory bank's pages deliver extra information outside of the normal data space, when read.

Examples of this may be a redirection byte, counter, tamper protection bytes, or SHA-1 result. If this method returns true then the methods with an 'extraInfo' parameter can be used: readPage, readPageCRC, and readPagePacket.

Returns:
true if reading the this memory bank's pages provides extra information
See also:
readPage(int,boolean,byte[],int,byte[]) readPage(extra)

readPageCRC(int,boolean,byte[],int,byte[]) readPageCRC(extra)

readPagePacket(int,boolean,byte[],int,byte[]) readPagePacket(extra)

Deprecated:
As of 1-Wire API 0.01, replaced by hasExtraInfo()

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

boolean hasExtraInfo (  ) 

Checks to see if this memory bank's pages deliver extra information outside of the normal data space, when read.

Examples of this may be a redirection byte, counter, tamper protection bytes, or SHA-1 result. If this method returns true then the methods with an 'extraInfo' parameter can be used: readPage, readPageCRC, and readPagePacket.

Returns:
true if reading the this memory bank's pages provides extra information
See also:
readPage(int,boolean,byte[],int,byte[]) readPage(extra)

readPageCRC(int,boolean,byte[],int,byte[]) readPageCRC(extra)

readPagePacket(int,boolean,byte[],int,byte[]) readPagePacket(extra)

Since:
1-Wire API 0.01

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

int getExtraInfoLength (  ) 

Gets the length in bytes of extra information that is read when reading a page in this memory bank.

Returns:
number of bytes in Extra Information read when reading pages from this memory bank
See also:
hasExtraInfo() hasExtraInfo

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

String getExtraInfoDescription (  ) 

Gets a string description of what is contained in the Extra Information returned when reading pages in this memory bank.

Returns:
extra information description.
See also:
hasExtraInfo() hasExtraInfo

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

void readPage ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset 
) throws OneWireIOException, OneWireException

Reads a page in this memory bank with no CRC checking (device or data).

The resulting data from this API may or may not be what is on the 1-Wire device. It is recommends that the data contain some kind of checking (CRC) like in the readPagePacket method or have the 1-Wire device provide the CRC as in readPageCRC. However device CRC generation is not supported on all memory types, see hasPageAutoCRC. If neither is an option then this method could be called more then once to at least verify that the same data is read consistently.

The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read packet from
readContinue  true then device read is continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
Exceptions:
OneWireIOException on a 1-Wire communication error such as no 1-Wire device present. 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

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankNVCRC, MemoryBankScratch, and MemoryBankSHAEE.

void readPage ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset,
byte[]  extraInfo 
) throws OneWireIOException, OneWireException

Reads a page in this memory bank with extra information with no CRC checking (device or data).

The resulting data from this API may or may not be what is on the 1-Wire device. It is recommends that the data contain some kind of checking (CRC) like in the readPagePacket method or have the 1-Wire device provide the CRC as in readPageCRC. However device CRC generation is not supported on all memory types, see hasPageAutoCRC. If neither is an option then this method could be called more then once to at least verify that the same data is read consistently.The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read packet from
readContinue  true then device read is continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
extraInfo location for extra info read
Exceptions:
OneWireIOException on a 1-Wire communication error such as no 1-Wire device present. 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:
hasExtraInfo() hasExtraInfo

getExtraInfoLength() getExtraInfoLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankNVCRC, MemoryBankScratch, and MemoryBankSHAEE.

int readPagePacket ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset 
) throws OneWireIOException, OneWireException

Reads a Universal Data Packet.

The Universal Data Packet always starts on page boundaries but can end anywhere in the page. The structure specifies the length of data bytes not including the length byte and the CRC16 bytes. There is one length byte. The CRC16 is first initialized to the page number. This provides a check to verify the page that was intended is being read. The CRC16 is then calculated over the length and data bytes. The CRC16 is then inverted and stored low byte first followed by the high byte. The structure is used by this method to verify the data but only the data payload is returned. The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

See Maxim Integrated Products Application Note 114 for details: http://dbserv.maxim-ic.com/appnotes.cfm?appnote_number=114

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read packet from
readContinue  true true then device read is continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
Returns:
number of data bytes read from the device and saved to readBuf at the provided offset
Exceptions:
OneWireIOException on a 1-Wire communication error such as an invalid CRC16 or length found in the packet. 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'. It could also be caused due to the device page not containing a valid packet.
OneWireException on a communication or setup error with the 1-Wire adapter
See also:
getMaxPacketDataLength() getMaxPacketDataLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

int readPagePacket ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset,
byte[]  extraInfo 
) throws OneWireIOException, OneWireException

Reads a Universal Data Packet and extra information.

See the method readPagePacket for a description of the packet structure. The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read packet from
readContinue  true then device read is continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
extraInfo location for extra info read
Returns:
number of data bytes read from the device and written to readBuf at the offset.
Exceptions:
OneWireIOException on a 1-Wire communication error such as an invalid CRC16 or length found in the packet. 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'. It could also be caused due to the device page not containing a valid packet.
OneWireException on a communication or setup error with the 1-Wire adapter
See also:
hasExtraInfo() hasExtraInfo

getExtraInfoLength() getExtraInfoLength

getMaxPacketDataLength() getMaxPacketDataLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankNVCRC, MemoryBankScratch, and MemoryBankSHAEE.

void writePagePacket ( int  page,
byte[]  writeBuf,
int  offset,
int  len 
) throws OneWireIOException, OneWireException

Writes a Universal Data Packet.

See the method readPagePacket for a description of the packet structure.

Parameters:
page page number to write packet to
writeBuf data to write
offset offset into writeBuf where data to write is
len number of bytes to write with a max of getMaxPacketDataLength elements
Exceptions:
OneWireIOException on a 1-Wire communication error such as read verification error on write. 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'. It could also be caused due to the device page being write protected.
OneWireException on a communication or setup error with the 1-Wire adapter
See also:
getMaxPacketDataLength() getMaxPacketDataLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankScratch, and MemoryBankSHAEE.

void readPageCRC ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset 
) throws OneWireIOException, OneWireException

Reads a complete memory page with CRC verification provided by the device.

Not supported by all devices. The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read
readContinue  true true then device read is continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
Exceptions:
OneWireIOException on a 1-Wire communication error such as an invalid CRC read from 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:
hasPageAutoCRC() hasPageAutoCRC

getPageLength() getPageLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankNVCRC, MemoryBankScratch, MemoryBankScratchCRC, MemoryBankScratchCRCPW, MemoryBankScratchSHAEE, and MemoryBankSHAEE.

void readPageCRC ( int  page,
boolean  readContinue,
byte[]  readBuf,
int  offset,
byte[]  extraInfo 
) throws OneWireIOException, OneWireException

Reads a complete memory page with CRC verification provided by the device with extra information.

Not supported by all devices. The readContinue parameter is used to eliminate the overhead in re-accessing a part already being read from. For example, if pages 0 - 4 are to be read, readContinue would be set to false for page 0 and would be set to true for the next four calls.

Note: Using readContinue = true can only be used if the new read continues where the last one left off and it is inside a 'beginExclusive/endExclusive' block.

Parameters:
page page number to read
readContinue  true true then device read is issued without continued without re-selecting
readBuf location for data read
offset offset into readBuf to place data
extraInfo location for extra info read
Exceptions:
OneWireIOException on a 1-Wire communication error such as an invalid CRC read from 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:
hasExtraInfo() hasExtraInfo

getExtraInfoLength() getExtraInfoLength

hasPageAutoCRC() hasPageAutoCRC

getPageLength() getPageLength

Implemented in MemoryBankAD, MemoryBankAppReg, MemoryBankEE, MemoryBankEEPROM, MemoryBankEEPROMblock, MemoryBankEPROM, MemoryBankNV, MemoryBankNVCRC, MemoryBankNVCRCPW, MemoryBankScratch, MemoryBankScratchCRC, MemoryBankScratchCRCPW, MemoryBankScratchSHAEE, and MemoryBankSHAEE.


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

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