Dallas Semiconductor 1-Wire API 1.00 Alpha: Class OneWireContainer24

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
Class OneWireContainer24

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

All Implemented Interfaces:
  ClockContainer, OneWireSensor

public class OneWireContainer24
extends OneWireContainer
implements ClockContainer

1-Wire container for Real-Time-Clock (RTC) iButton, DS1904 and 1-Wire Chip, DS2415. This container encapsulates the functionality of the iButton family type 24 (hex)

This iButton is used as a portable real-time-clock.

### Features

- Data integrity assured with strict read/write protocols
- Contains real time clock/calendar in binary format with 1 second resolution.
- Clock accuracy is better than ±2 minute/ month at 25°C
- Operating temperature range from -40°C to +70°C
- Over 10 years of data retention
- Low power, 200 nA typical when oscillator running

### Alternate Names

- D2415

### Clock

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

- Information
  - `hasClockAlarm` *
  - `canDisableClock` *
  - `getClockResolution` *
- Read
  - Clock
    - `getClock` *
    - `getClockAlarm` *
    - `isClockAlarming` *
    - `isClockAlarmEnabled` *
    - `isClockRunning` *
  - Misc
    - `readDevice` *
- Write
  - Clock
    - `setClock` *
    - `setClockAlarm` *
    - `setClockRunEnable` *
    - `setClockAlarmEnable` *
  - Misc
    - `writeDevice` *

### 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/DS1904.pdf
  http://pdfserv.maxim-ic.com/arpdf/DS2415.pdf

Version:
  0.00, 15 Aug 2001
See Also:
  `MemoryBank`, `PagedMemoryBank`, `ClockContainer`

Constructor Summary
`OneWireContainer24()` Create an empty container that is not complete until after a call to `setupContainer`.
`OneWireContainer24(DSPortAdapter sourceAdapter, byte[] newAddress)` Create a container with the provided adapter instance and the address of the iButton or 1-Wire device.
`OneWireContainer24(DSPortAdapter sourceAdapter, long newAddress)` Create a container with the provided adapter instance and the address of the iButton or 1-Wire device.
`OneWireContainer24(DSPortAdapter sourceAdapter, String newAddress)` Create a container with the provided adapter instance and the address of the iButton or 1-Wire device.

Method Summary
`boolean` | `canDisableClock()` Query to see if the clock can be disabled.
`String` | `getAlternateNames()` Get the alternate Dallas Semiconductor part numbers or names.
`long` | `getClock(byte[] state)` Extracts the Real-Time clock value in milliseconds.
`long` | `getClockAlarm(byte[] state)` Extracts the clock alarm value for the Real-Time clock.
`long` | `getClockResolution()` Query to get the clock resolution in milliseconds
`String` | `getDescription()` Get a short description of the function of this iButton or 1-Wire Device type.
`String` | `getName()` Get the Dallas Semiconductor part number of the iButton or 1-Wire Device as a string.
`boolean` | `hasClockAlarm()` Query to see if the clock has an alarm feature.
`boolean` | `isClockAlarmEnabled(byte[] state)` Checks if the clock alarm is enabled.
`boolean` | `isClockAlarming(byte[] state)` Checks if the clock alarm flag has been set.
`boolean` | `isClockRunning(byte[] state)` Checks if the device's oscillator is enabled.
`byte[]` | `readDevice()` Retrieves the five byte state over the 1-Wire bus.
`void` | `setClock(long time, byte[] state)` Sets the Real-Time clock.
`void` | `setClockAlarm(long time, byte[] state)` Sets the clock alarm.
`void` | `setClockAlarmEnable(boolean alarmEnable, byte[] state)` Enables or disables the clock alarm.
`void` | `setClockRunEnable(boolean runEnable, byte[] state)` Enables or disables the oscillator, turning the clock 'on' and 'off'.
`void` | `writeDevice(byte[] state)` Writes the 1-Wire device sensor state that have been changed by 'set' methods.

Methods inherited from class com.dalsemi.onewire.container.OneWireContainer
`doSpeed, getAdapter, getAddress, getAddressAsLong, getAddressAsString, getMaxSpeed, getMemoryBanks, isAlarming, isPresent, setSpeed, setupContainer, setupContainer, setupContainer`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### OneWireContainer24

    public OneWireContainer24()

  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:
    `super.setupContainer()`

### OneWireContainer24

    public OneWireContainer24(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:
    `OneWireContainer24`, `utils.Address`

### OneWireContainer24

    public OneWireContainer24(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:
    `OneWireContainer24`, `utils.Address`

### OneWireContainer24

    public OneWireContainer24(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:
    `OneWireContainer24`, `utils.Address`

Method Detail

### getName

    public String getName()

  Get the Dallas Semiconductor 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 Dallas Semiconductor 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

### 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:
    `getClockAlarm(byte[])`, `isClockAlarmEnabled(byte[])`, `isClockAlarming(byte[])`, `setClockAlarm(long,byte[])`, `setClockAlarmEnable(boolean,byte[])`

### 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:
    `isClockRunning(byte[])`, `setClockRunEnable(boolean,byte[])`

### 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 five byte state over the 1-Wire bus. This state array must be passed to the Get/Set methods as well as the WriteDevice method.
  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 some reference time, as chosen by the user (ie. 12:00am, Jan 1st 1970)
  See Also:
    `OneWireSensor.readDevice()`, `setClock(long,byte[])`

### 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:
    `OneWireSensor.readDevice()`, `hasClockAlarm()`, `isClockAlarmEnabled(byte[])`, `isClockAlarming(byte[])`, `setClockAlarm(long,byte[])`, `setClockAlarmEnable(boolean,byte[])`

### 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:
    `OneWireSensor.readDevice()`, `hasClockAlarm()`, `isClockAlarmEnabled(byte[])`, `getClockAlarm(byte[])`, `setClockAlarm(long,byte[])`, `setClockAlarmEnable(boolean,byte[])`

### 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:
    `OneWireSensor.readDevice()`, `hasClockAlarm()`, `isClockAlarming(byte[])`, `getClockAlarm(byte[])`, `setClockAlarm(long,byte[])`, `setClockAlarmEnable(boolean,byte[])`

### 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:
    `OneWireSensor.readDevice()`, `canDisableClock()`, `setClockRunEnable(boolean,byte[])`

### 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 some reference time (ie. 12:00am, January 1st, 1970)
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `OneWireSensor.writeDevice(byte[])`, `getClock(byte[])`

### 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:
    `OneWireSensor.writeDevice(byte[])`, `hasClockAlarm()`, `isClockAlarmEnabled(byte[])`, `getClockAlarm(byte[])`, `isClockAlarming(byte[])`, `setClockAlarmEnable(boolean,byte[])`

### 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:
    `OneWireSensor.writeDevice(byte[])`, `hasClockAlarm()`, `isClockAlarmEnabled(byte[])`, `getClockAlarm(byte[])`, `setClockAlarm(long,byte[])`, `isClockAlarming(byte[])`

### setClockRunEnable

    public void setClockRunEnable(boolean runEnable,
                                  byte[] state)

  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()`
  See Also:
    `OneWireSensor.writeDevice(byte[])`, `canDisableClock()`, `isClockRunning(byte[])`

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