com.dalsemi.onewire.container
Class OneWireContainer24

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

All Implemented Interfaces:

ClockContainer, OneWireSensor

Direct Known Subclasses:

OneWireContainer27

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

• Real-Time Clock with fully compatible 1-Wire MicroLAN interface
• Uses the same binary time/date representation as the DS2404 but with 1 second resolution
• Clock accuracy ± 2 minutes per month at 25°
• Operating temperature range from -40°C to +70°C (iButton), -40°C to +85°C (1-Wire chip)
• Over 10 years of data retention (iButton form factor)
• Low power, 200 nA typical with oscillator running

Alternate Names

• DS2415

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.

DataSheets

http://pdfserv.maxim-ic.com/arpdf/DS1904.pdf

http://pdfserv.maxim-ic.com/arpdf/DS2415.pdf

Version:

1.00, 26 September 2001

Author:

CO,BA

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, equals, getAdapter, getAddress, getAddressAsLong, getAddressAsString, getMaxSpeed, getMemoryBanks, hashCode, isAlarming, isPresent, setSpeed, setupContainer, setupContainer, setupContainer, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, 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[])