Dallas Semiconductor 1-Wire API 1.00 Alpha: Interface MemoryBank

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
Interface MemoryBank

All Known Subinterfaces:
  OTPMemoryBank, PagedMemoryBank

public interface MemoryBank

Memory bank interface class for basic memory communication with iButtons (or 1-Wire devices). The method `getMemoryBanks` in all 1-Wire Containers (`OneWireContainer`) returns an Enumeration of this interface to be used to read or write it's memory. If the 1-Wire device does not have memory or the memory is non-standard, then this enumeration may be empty. A MemoryBank returned from this method may also implement the `PagedMemoryBank`, or `OTPMemoryBank` interfaces, to provide additional functionality.

The MemoryBank methods can be organized into the following categories:

- Information
  - `getBankDescription`
  - `getSize`
  - `getStartPhysicalAddress`
  - `isGeneralPurposeMemory`
  - `isReadWrite`
  - `isWriteOnce`
  - `isReadOnly`
  - `isNonVolatile`
  - `needsProgramPulse`
  - `needsPowerDelivery`
- Options
  - `setWriteVerification`
- I/O
  - `read`
  - `write`

### Usage

  #### Example 1

  Display some features of MemoryBank instance 'mb':

        if (mb.isWriteOnce())
           System.out.println("MemoryBank is write-once");

        if (mb.needsProgramPulse())
           System.out.println("MemoryBank requires program-pulse to write");

  #### Example 2

  Write the entire contents of a MemoryBank instance 'mb' with zeros:

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

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

  #### Example 3

  Read the entire contents of a MemoryBank instance 'mb':

        byte[] read_buf = new byte[mb.getSize()];

        mb.read(0, false, read_buf, 0, read_buf.length);

Version:
  0.00, 28 Aug 2000
See Also:
  `PagedMemoryBank`, `OTPMemoryBank`, `OneWireContainer04`, `OneWireContainer06`, `OneWireContainer08`, `OneWireContainer09`, `OneWireContainer0A`, `OneWireContainer0B`, `OneWireContainer0C`, `OneWireContainer0F`, `OneWireContainer12`, `OneWireContainer13`, `OneWireContainer14`, `OneWireContainer18`, `OneWireContainer1A`, `OneWireContainer1D`, `OneWireContainer20`, `OneWireContainer21`, `OneWireContainer23`

Method Summary
`String` | `getBankDescription()` Gets a string description of this memory bank.
`int` | `getSize()` Gets the size of this memory bank in bytes.
`int` | `getStartPhysicalAddress()` Gets the starting physical address of this bank.
`boolean` | `isGeneralPurposeMemory()` Checks to see if this memory bank is general purpose user memory.
`boolean` | `isNonVolatile()` Checks to see if this memory bank is non-volatile.
`boolean` | `isReadOnly()` Checks to see if this memory bank is read only.
`boolean` | `isReadWrite()` Checks to see if this memory bank is read/write.
`boolean` | `isWriteOnce()` Checks to see if this memory bank is write once such as with EPROM technology.
`boolean` | `needsPowerDelivery()` Checks to see if this memory bank requires 'PowerDelivery' in order to write.
`boolean` | `needsProgramPulse()` Checks to see if this memory bank requires a 'ProgramPulse' in order to write.
`void` | `read(int startAddr, boolean readContinue, byte[] readBuf, int offset, int len)` Reads memory in this bank with no CRC checking (device or data).
`void` | `setWriteVerification(boolean doReadVerf)` Sets or clears write verification for the `write` method.
`void` | `write(int startAddr, byte[] writeBuf, int offset, int len)` Writes memory in this bank.

Method Detail

### getBankDescription

    public String getBankDescription()

  Gets a string description of this memory bank.
  Returns:
    the memory bank description

### isGeneralPurposeMemory

    public boolean isGeneralPurposeMemory()

  Checks to see if this memory bank is general purpose user memory. If it is NOT then it may be Memory-Mapped and writing values to this memory may affect the behavior of the 1-Wire device.
  Returns:
    `true` if this memory bank is general purpose

### getSize

    public int getSize()

  Gets the size of this memory bank in bytes.
  Returns:
    number of bytes in current memory bank

### isReadWrite

    public boolean isReadWrite()

  Checks to see if this memory bank is read/write.
  Returns:
    `true` if this memory bank is read/write

### isWriteOnce

    public boolean isWriteOnce()

  Checks to see if this memory bank is write once such as with EPROM technology.
  Returns:
    `true` if this memory bank can only be written once

### isReadOnly

    public boolean isReadOnly()

  Checks to see if this memory bank is read only.
  Returns:
    `true` if this memory bank can only be read

### isNonVolatile

    public boolean isNonVolatile()

  Checks to see if this memory bank is non-volatile. Memory is non-volatile if it retains its contents even when removed from the 1-Wire network.
  Returns:
    `true` if this memory bank is non volatile

### needsProgramPulse

    public boolean needsProgramPulse()

  Checks to see if this memory bank requires a 'ProgramPulse' in order to write.
  Returns:
    `true` if writing to this memory bank requires a 'ProgramPulse' from the 1-Wire Adapter.
  See Also:
    `DSPortAdapter`

### needsPowerDelivery

    public boolean needsPowerDelivery()

  Checks to see if this memory bank requires 'PowerDelivery' in order to write.
  Returns:
    `true` if writing to this memory bank requires 'PowerDelivery' from the 1-Wire Adapter
  See Also:
    `DSPortAdapter`

### getStartPhysicalAddress

    public int getStartPhysicalAddress()

  Gets the starting physical address of this bank. Physical banks are sometimes sub-divided into logical banks due to changes in attributes. Note that this method is for information only. The read and write methods will automatically calculate the physical address when writing to a logical memory bank.
  Returns:
    physical starting address of this logical bank

### setWriteVerification

    public void setWriteVerification(boolean doReadVerf)

  Sets or clears write verification for the `write` method.
  Parameters:
    `doReadVerf` - `true` (default) verify write in 'write', `false` don't verify write (used on Write-Once bit manipulation)
  See Also:
    `OTPMemoryBank`

### read

    public void read(int startAddr,
                     boolean readContinue,
                     byte[] readBuf,
                     int offset,
                     int len)
              throws OneWireIOException,
                     OneWireException

  Reads memory in this 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 recommended that the data contain some kind of checking (CRC) like in the `readPagePacket` method in the `PagedMemoryBank` interface. Some 1-Wire devices provide thier own CRC as in `readPageCRC` also found in the `PagedMemoryBank` interface. The `readPageCRC` method is not supported on all memory types, see `hasPageAutoCRC` in the same interface. 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 continuous where the last one led off and it is inside a 'beginExclusive/endExclusive' block.

  Parameters:
    `startAddr` - starting address
    `readContinue` - `true` then device read is continued without re-selecting
    `readBuf` - location for data read
    `offset` - offset into readBuf to place data
    `len` - length in bytes to read
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no 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

### write

    public void write(int startAddr,
                      byte[] writeBuf,
                      int offset,
                      int len)
               throws OneWireIOException,
                      OneWireException

  Writes memory in this bank. It is recommended that a structure with some built in error checking is used to provide data integrity on read. The method `writePagePacket` found in the `PagedMemoryBank` interface, which automatically wraps the data in a length and CRC, could be used for this purpose.

  When using on Write-Once devices care must be taken to write into into empty space. If `write` is used to write over an unlocked page on a Write-Once device it will fail. If write verification is turned off with the method `setWriteVerification(false)` then the result will be an 'AND' of the existing data and the new data.

  Parameters:
    `startAddr` - starting address
    `writeBuf` - data to write
    `offset` - offset into writeBuf to get data
    `len` - length in bytes to write
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no device present or a read back verification fails. 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

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