Package com.dalsemi.onewire.container

Class OneWireContainer04

java.lang.Object
com.dalsemi.onewire.container.OneWireContainer
com.dalsemi.onewire.container.OneWireContainer04
All Implemented Interfaces:
ClockContainer, OneWireSensor
public class OneWireContainer04 extends OneWireContainer implements ClockContainer

1-Wire container for 512 byte memory iButton Plus Time, DS1994 and 1-Wire Chip, DS2404. This container encapsulates the functionality of the iButton family type 04 (hex)

This iButton is primarily used as a read/write portable memory device with real-time-clock, timer and expiration features.

Features

  • 4096 bits (512 bytes) of read/write nonvolatile memory
  • 256-bit (32-byte) scratchpad ensures integrity of data transfer
  • Memory partitioned into 256-bit (32-byte) pages for packetizing data
  • Data integrity assured with strict read/write protocols
  • Contains real time clock/calendar in binary format
  • Interval timer can automatically accumulate time when power is applied
  • Programmable cycle counter can accumulate the number of system power-on/off cycles
  • Programmable alarms can be set to generate interrupts for interval timer, real time clock, and/or cycle counter
  • Write protect feature provides tamper-proof time data
  • Programmable expiration date that will limit access to SRAM and timekeeping
  • Clock accuracy is better than @htmlonly invalid input: '&#177' @endhtmlonly 2 minute/ month at 25@htmlonly invalid input: '&#176'C @endhtmlonly
  • Operating temperature range from -40 to +70
  • Over 10 years of data retention

Appended to the clock page data retrieved with 'readDevice' are 4 bytes that represent a bitmap of changed bytes. These bytes are used in the 'writeDevice' method in conjunction with the 'set' methods to only write back the changed clock register bytes. The 'readDevice' method will clear any pending alarms.

WARNING: If write-protect alarm options have been set prior to a call to 'writeDevice' then the operation is non-reversable.

Alternate Names

  • D2504
  • D1427 (family type 84 hex)

Memory

The memory can be accessed through the objects that are returned from the getMemoryBanks method.

The following is a list of the MemoryBank instances that are returned:
  • Scratchpad
    • Implements MemoryBank, PagedMemoryBank
    • Size 32 starting at physical address 0
    • Features Read/Write not-general-purpose volatile
    • Pages 1 pages of length 32 bytes
    • Extra information for each page Target address, offset, length 3
  • Main Memory
    • Implements MemoryBank, PagedMemoryBank
    • Size 512 starting at physical address 0
    • Features Read/Write general-purpose non-volatile
    • Pages 16 pages of length 32 bytes giving 29 bytes Packet data payload
  • Clock/alarm registers
    • Implements MemoryBank, PagedMemoryBank
    • Size 32 starting at physical address 512
    • Features Read/Write not-general-purpose non-volatile
    • Pages 1 pages of length 32 bytes

Clock

The clock methods can be organized into the following categories. Note that methods that are implemented for the ClockContainer interface are marked with (*):

Usage

See the usage examples in ClockContainer for basic clock operations.
See the usage example in OneWireContainer to enumerate the MemoryBanks.
See the usage examples in MemoryBank and PagedMemoryBank for bank specific operations.

DataSheets

http://pdfserv.maxim-ic.com/arpdf/DS1992-DS1994.pdf
http://pdfserv.maxim-ic.com/arpdf/DS2404.pdf
http://pdfserv.maxim-ic.com/arpdf/DS1427.pdf
See Also:

  • Field Details

    • BITMAP_OFFSET

      protected static final int BITMAP_OFFSET
      Offset of BITMAP in array returned from read registers
      See Also:

    • STATUS_OFFSET

      protected static final int STATUS_OFFSET
      Offset of status register from read registers
      See Also:

    • CONTROL_OFFSET

      protected static final int CONTROL_OFFSET
      Offset of control register from read registers
      See Also:

    • RTC_OFFSET

      protected static final int RTC_OFFSET
      Offset of real-time-clock in array returned from read registers
      See Also:

    • INTERVAL_OFFSET

      protected static final int INTERVAL_OFFSET
      Offset of inverval-counter in array returned from read registers
      See Also:

    • COUNTER_OFFSET

      protected static final int COUNTER_OFFSET
      Offset of counter in array returned from read registers
      See Also:

    • RTC_ALARM_OFFSET

      protected static final int RTC_ALARM_OFFSET
      Offset of real-time-clock-alarm in array returned from read registers
      See Also:

    • INTERVAL_ALARM_OFFSET

      protected static final int INTERVAL_ALARM_OFFSET
      Offset of inverval-counter-alarm in array returned from read registers
      See Also:

    • COUNTER_ALARM_OFFSET

      protected static final int COUNTER_ALARM_OFFSET
      Offset of counter-alarm in array returned from read registers
      See Also:

  • Constructor Details

    • OneWireContainer04

      public OneWireContainer04()
      Create an empty container that is not complete until after a call to setupContainer.

      This is one of the methods to construct a container. The others are through creating a OneWireContainer with parameters.

      See Also:

    • OneWireContainer04

      public OneWireContainer04(DSPortAdapter sourceAdapter, byte[] newAddress)
      Create a container with the provided adapter instance 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 instance used to communicate with this iButton
      newAddress - Address of this 1-Wire device
      See Also:

    • OneWireContainer04

      public OneWireContainer04(DSPortAdapter sourceAdapter, long newAddress)
      Create a container with the provided adapter instance 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 instance used to communicate with this 1-Wire device
      newAddress - Address of this 1-Wire device
      See Also:

    • OneWireContainer04

      public OneWireContainer04(DSPortAdapter sourceAdapter, String newAddress)
      Create a container with the provided adapter instance 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 instance used to communicate with this 1-Wire device
      newAddress - Address of this 1-Wire device
      See Also:

  • Method Details

    • getName

      public String getName()
      Get the Maxim Integrated Products part number of the iButton or 1-Wire Device as a string. For example 'DS1992'.
      Overrides:
      getName in class OneWireContainer
      Returns:
      iButton or 1-Wire device name

    • getAlternateNames

      public String getAlternateNames()
      Get 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 String getDescription()
      Get a short description of the function of this iButton or 1-Wire Device type.
      Overrides:
      getDescription in class OneWireContainer
      Returns:
      device description

    • getMemoryBanks

      public Enumeration<MemoryBank> getMemoryBanks()
      Get an enumeration of memory bank instances that implement one or more of the following interfaces: MemoryBank, PagedMemoryBank, and OTPMemoryBank.
      Overrides:
      getMemoryBanks in class OneWireContainer
      Returns:
      Enumeration of memory banks
      See Also:

    • hasClockAlarm

      public boolean hasClockAlarm()
      Query to see if the clock has an alarm feature.
      Specified by:
      hasClockAlarm in interface ClockContainer
      Returns:
      true if the Real-Time clock has an alarm
      See Also:

    • canDisableClock

      public boolean canDisableClock()
      Query to see if the clock can be disabled.
      Specified by:
      canDisableClock in interface ClockContainer
      Returns:
      true if the clock can be enabled and disabled
      See Also:

    • getClockResolution

      public long getClockResolution()
      Query to get the clock resolution in milliseconds
      Specified by:
      getClockResolution in interface ClockContainer
      Returns:
      the clock resolution in milliseconds

    • readDevice

      public byte[] readDevice() throws OneWireIOException, OneWireException
      Retrieves the 1-Wire device sensor state. This state is returned as a byte array. Pass this byte array to the 'get' and 'set' methods. If the device state needs to be changed then call the 'writeDevice' to finalize the changes.
      Specified by:
      readDevice in interface OneWireSensor
      Returns:
      1-Wire device sensor state
      Throws:
      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

    • writeDevice

      public void writeDevice(byte[] state) throws OneWireIOException, OneWireException
      Writes the 1-Wire device sensor state that have been changed by 'set' methods. Only the state registers that changed are updated. This is done by referencing a field information appended to the state data.
      Specified by:
      writeDevice in interface OneWireSensor
      Parameters:
      state - 1-Wire device sensor state
      Throws:
      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

    • getClock

      public long getClock(byte[] state)
      Extracts the Real-Time clock value in milliseconds.
      Specified by:
      getClock in interface ClockContainer
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      the time represented in this clock in milliseconds since 1970
      See Also:

    • getClockAlarm

      public long getClockAlarm(byte[] state) throws OneWireException
      Extracts the clock alarm value for the Real-Time clock.
      Specified by:
      getClockAlarm in interface ClockContainer
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      milliseconds since 1970 that the clock alarm is set to
      Throws:
      OneWireException - if this device does not have clock alarms
      See Also:

    • isClockAlarming

      public boolean isClockAlarming(byte[] state)
      Checks if the clock alarm flag has been set. This will occur when the value of the Real-Time clock equals the value of the clock alarm.
      Specified by:
      isClockAlarming in interface ClockContainer
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the Real-Time clock is alarming
      See Also:

    • isClockAlarmEnabled

      public boolean isClockAlarmEnabled(byte[] state)
      Checks if the clock alarm is enabled.
      Specified by:
      isClockAlarmEnabled in interface ClockContainer
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if clock alarm is enabled
      See Also:

    • isClockRunning

      public boolean isClockRunning(byte[] state)
      Checks if the device's oscillator is enabled. The clock will not increment if the clock oscillator is not enabled.
      Specified by:
      isClockRunning in interface ClockContainer
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the clock is running
      See Also:

    • getIntervalTimer

      public long getIntervalTimer(byte[] state)
      Get the Interval Timer Value in milliseconds.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      time in milliseconds that have occurred since the interval counter was started
      See Also:

    • getCycleCounter

      public long getCycleCounter(byte[] state)
      Get the power cycle count value. This is the total number of power cycles that the DS1994 has seen since the counter was reset.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      power cycle count
      See Also:

    • getIntervalTimerAlarm

      public long getIntervalTimerAlarm(byte[] state)
      Get the Interval Timer Alarm Value.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      time in milliseconds that have the interval timer alarm is set to
      See Also:

    • getCycleCounterAlarm

      public long getCycleCounterAlarm(byte[] state)
      Get the cycle count Alarm Value.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      total number of power cycles that the DS1994 has to to see before the alarm will be triggered
      See Also:

    • isIntervalTimerAlarming

      public boolean isIntervalTimerAlarming(byte[] state)
      Check if the Interval Timer Alarm flag has been set.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if interval timer is alarming
      See Also:

    • isCycleCounterAlarming

      public boolean isCycleCounterAlarming(byte[] state)
      Check if the Cycle Alarm flag has been set.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if cycle counter is alarming
      See Also:

    • isIntervalTimerAlarmEnabled

      public boolean isIntervalTimerAlarmEnabled(byte[] state)
      Check if the Interval Timer Alarm is enabled.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if interval timer alarm is enabled
      See Also:

    • isCycleCounterAlarmEnabled

      public boolean isCycleCounterAlarmEnabled(byte[] state)
      Check if the Cycle Alarm is enabled.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true true if cycle counter alarm is enabled
      See Also:

    • isClockWriteProtected

      public boolean isClockWriteProtected(byte[] state)
      Check if the Real-Time clock/Alarm is write protected.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if real time clock/alarm is write protected
      See Also:

    • isIntervalTimerWriteProtected

      public boolean isIntervalTimerWriteProtected(byte[] state)
      Check if the Interval Timer and Interval Timer Alarm register is write protected.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if interval timer and interval timer alarm is write protected
      See Also:

    • isCycleCounterWriteProtected

      public boolean isCycleCounterWriteProtected(byte[] state)
      Check if the Cycle Counter and Alarm is write protected.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if cycle counter/alarm is write protected
      See Also:

    • canReadAfterExpire

      public boolean canReadAfterExpire(byte[] state)
      Check if the device can be read after a write protected alarm has occurred.
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the device can be read after a write protected alarm has occurred
      See Also:

    • isIntervalTimerAutomatic

      public boolean isIntervalTimerAutomatic(byte[] state)
      Checks if the Interval timer is automatic or manual. If it is automatic then the interval counter will increment while the devices I/O line is high after the delay select period has elapsed (either 3.5 or 123 ms, see the isAutomaticDelayLong() method).
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the interval timer is set to automatic mode
      See Also:

    • isIntervalTimerStopped

      public boolean isIntervalTimerStopped(byte[] state)
      Check if the Interval timer is stopped. This only has meaning if the interval timer is in manual mode (not isIntervalTimerAutomatic).
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the interval timer is stopped
      See Also:

    • isAutomaticDelayLong

      public boolean isAutomaticDelayLong(byte[] state)
      Checks if the automatic delay for the Interval Timer and the Cycle counter is either 3.5ms (regular) or 123ms (long).
      Parameters:
      state - current state of the device returned from readDevice()
      Returns:
      true if the automatic interval/cycle counter delay is in the long (123ms) mode, else it is 3.5ms
      See Also:

    • setClock

      public void setClock(long time, byte[] state)
      Sets the Real-Time clock. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Specified by:
      setClock in interface ClockContainer
      Parameters:
      time - new value for the Real-Time clock, in milliseconds since January 1, 1970
      state - current state of the device returned from readDevice()
      See Also:

    • setClockAlarm

      public void setClockAlarm(long time, byte[] state) throws OneWireException
      Sets the clock alarm. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]). Also note that not all clock devices have alarms. Check to see if this device has alarms first by calling the hasClockAlarm() method.
      Specified by:
      setClockAlarm in interface ClockContainer
      Parameters:
      time - - new value for the Real-Time clock alarm, in milliseconds since January 1, 1970
      state - current state of the device returned from readDevice()
      Throws:
      OneWireException - if this device does not have clock alarms
      See Also:

    • setClockRunEnable

      public void setClockRunEnable(boolean runEnable, byte[] state) throws OneWireException
      Enables or disables the oscillator, turning the clock 'on' and 'off'. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]). Also note that not all clock devices can disable their oscillators. Check to see if this device can disable its oscillator first by calling the canDisableClock() method.
      Specified by:
      setClockRunEnable in interface ClockContainer
      Parameters:
      runEnable - true to enable the clock oscillator
      state - current state of the device returned from readDevice()
      Throws:
      OneWireException - if the clock oscillator cannot be disabled
      See Also:

    • setClockAlarmEnable

      public void setClockAlarmEnable(boolean alarmEnable, byte[] state) throws OneWireException
      Enables or disables the clock alarm. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]). Also note that not all clock devices have alarms. Check to see if this device has alarms first by calling the hasClockAlarm() method.
      Specified by:
      setClockAlarmEnable in interface ClockContainer
      Parameters:
      alarmEnable - true to enable the clock alarm
      state - current state of the device returned from readDevice()
      Throws:
      OneWireException - if this device does not have clock alarms
      See Also:

    • setIntervalTimer

      public void setIntervalTimer(long time, byte[] state)
      Sets the Interval Timer. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      time - interval in milliseconds to set (truncated to 1/256th of second)
      state - current state of the device returned from readDevice()
      See Also:

    • setCycleCounter

      public void setCycleCounter(long cycles, byte[] state)
      Sets power Cycle Counter. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      cycles - initialize cycle counter value
      state - current state of the device returned from readDevice()
      See Also:

    • setIntervalTimerAlarm

      public void setIntervalTimerAlarm(long time, byte[] state)
      Sets the Interval Timer Alarm. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      time - in milliseconds to set the interval timer
      state - current state of the device returned from readDevice()
      See Also:

    • setCycleCounterAlarm

      public void setCycleCounterAlarm(long cycles, byte[] state)
      Sets the power Cycle Count Alarm. This counter holds the number of times the DS1994 must experience power cycles before it generates an alarm. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      cycles - power Cycle Count alarm
      state - current state of the device returned from readDevice()
      See Also:

    • writeProtectClock

      public void writeProtectClock(byte[] state)
      Sets the write protect options for the Real-Time clock/Alarm. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).

      WARNING: after calling this method and then writeDevice the device will be permanently write protected.


      Parameters:
      state - current state of the device returned from readDevice()
      See Also:

    • writeProtectIntervalTimer

      public void writeProtectIntervalTimer(byte[] state)
      Sets the write protect options for Interval Timer and Interval Timer Alarm register. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).

      WARNING: after calling this method and then writeDevice the device will be permanently write protected.


      Parameters:
      state - current state of the device returned from readDevice()
      See Also:

    • writeProtectCycleCounter

      public void writeProtectCycleCounter(byte[] state)
      Sets the write protect options for the Cycle Counter and Alarm register. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).

      WARNING: after calling this method and then writeDevice the device will be permanently write protected.


      Parameters:
      state - current state of the device returned from readDevice()
      See Also:

    • setReadAfterExpire

      public void setReadAfterExpire(boolean readAfter, byte[] state)
      Sets the read state of the device after a write protected alarm has occurred. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      readAfter - true to read device after it expires from a write protected alarm event
      state - current state of the device returned from readDevice()
      See Also:

    • setIntervalTimerAutomatic

      public void setIntervalTimerAutomatic(boolean autoTimer, byte[] state)
      Sets the Interval timer to automatic or manual mode. When in automatic mode, the interval counter will increment while the devices I/O line is high after the delay select period has elapsed (either 3.5 or 123 ms, see the isAutomaticDelayLong() method). The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      autoTimer - true for the interval timer to operate in automatic mode
      state - current state of the device returned from readDevice()
      See Also:

    • setIntervalTimerRunState

      public void setIntervalTimerRunState(boolean runState, byte[] state)
      Sets the Interval timer run/stop mode. This only has meaning if the interval timer is in manual mode (not isIntervalTimerAutomatic()). The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      runState - true to set the interval timer to run
      state - current state of the device returned from readDevice()
      See Also:

    • setAutomaticDelayLong

      public void setAutomaticDelayLong(boolean delayLong, byte[] state)
      Sets the automatic delay for the Interval Timer and the Cycle counter to either 123ms (long) or 3.5ms (regular). The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      delayLong - true to set the interval timer to cycle counter to increment after 123ms or false for 3.5ms
      state - current state of the device returned from readDevice()
      See Also:

    • setIntervalTimerAlarmEnable

      public void setIntervalTimerAlarmEnable(boolean alarmEnable, byte[] state)
      Sets the Interval Timer Alarm enable. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      alarmEnable - true to enable the interval timer alarm
      state - current state of the device returned from readDevice()
      See Also:

    • setCycleCounterAlarmEnable

      public void setCycleCounterAlarmEnable(boolean alarmEnable, byte[] state)
      Sets the Cycle counter Alarm enable. The method writeDevice(byte[]) must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice(byte[]).
      Parameters:
      alarmEnable - true to enable the cycle counter alarm
      state - current state of the device returned from readDevice()
      See Also: