com.dalsemi.onewire.container
Class OneWireContainer21

java.lang.Object
  |
  +--com.dalsemi.onewire.container.OneWireContainer
        |
        +--com.dalsemi.onewire.container.OneWireContainer21
All Implemented Interfaces:
ClockContainer, OneWireSensor, TemperatureContainer

public class OneWireContainer21
extends OneWireContainer
implements TemperatureContainer, ClockContainer

The DS1921L-F5X Thermochron iButtons are rugged, self-sufficient systems that, once setup for a mission, measure temperature and record the result in a protected memory section. The recording is doneat a user-defined rate, both as a direct storage of temperature values at incrementing memory addresses and as a histogram. Up to 2048 periodic temperature readings may be taken on each mission. If a temperature value leaves a user specified range, the thermochron will record when this happened and how long the condition occured for.

  Example of starting a mission with this container:

       //  ds1921 previously setup as a OneWireContainer21
       ds1921.clearMemory();
       //  read the current state of the device
       byte[] state = ds1921.readDevice();
       //  enable rollover
       ds1921.setFlag(ds1921.CONTROL_REGISTER, ds1921.ROLLOVER_ENABLE_FLAG, true, state);
       //  set the high temperature alarm to 28 C
       ds1921.setTemperatureAlarm(ds1921.ALARM_HIGH, 28.0, state);
       //  set the low temperature alarm to 23 C
       ds1921.setTemperatureAlarm(ds1921.ALARM_LOW, 23.0, state);
       //  set the clock alarm to occur weekly, mondays at 12:30:45 pm
       ds1921.setClockAlarm(12, 30, 45, 2, ds1921.ONCE_PER_WEEK, state);
       //  set the real time clock to the system's current clock
       ds1921.setClock((new Date(System.currentTimeMillis())).getTime(), state);
       //  set the mission to start in 2 minutes
       ds1921.setMissionStartDelay(2,state);
       //  make sure the clock is set to run
       ds1921.setClockRunEnable(true, state);
       //  make sure the clock alarm is enabled
       ds1921.setClockAlarmEnable(true, state);
       //  write all that information out
       ds1921.writeDevice(state);
       //  now enable the mission with a sample rate of 1 minute
       ds1921.enableMission(1);


  

Version:
0.00, 28 Aug 2000

Field Summary
static int CONTROL_REGISTER
          Address of the control register.
static byte MEMORY_CLEAR_ENABLE_FLAG
          CONTROL REGISTER FLAG: Must be enabled to enable the clear memory function.
static byte MEMORY_CLEARED_FLAG
          STATUS REGISTER FLAG: Will read back true if the memory has been cleared.
static byte MISSION_ENABLE_FLAG
          CONTROL REGISTER FLAG: When DISABLED, the mission will start as soon as the sample rate is written.
static byte MISSION_IN_PROGRESS_FLAG
          STATUS REGISTER FLAG: Will read back true when a mission is in progress.
static byte ONCE_PER_DAY
          Alarm frequency setting.
static byte ONCE_PER_HOUR
          Alarm frequency setting.
static byte ONCE_PER_MINUTE
          Alarm frequency setting
static byte ONCE_PER_SECOND
          Alarm frequency setting.
static byte ONCE_PER_WEEK
          Alarm frequency setting.
static byte OSCILLATOR_ENABLE_FLAG
          CONTROL REGISTER FLAG: When DISABLED, the real time clock will start working.
static byte ROLLOVER_ENABLE_FLAG
          CONTROL REGISTER FLAG: When enabled, the device will begin overwriting the earlier temperature measurements when the memory becomes full.
static byte SAMPLE_IN_PROGRESS_FLAG
          STATUS REGISTER FLAG: Will read back true when a mission temperature conversion is in progress To be used with getFlag.
static int STATUS_REGISTER
          Address of the status register.
static byte TEMP_CORE_BUSY_FLAG
          STATUS REGISTER FLAG: Will read back true if a temperature conversion of any kind is in progress.
static byte TEMP_HIGH_SEARCH_FLAG
          CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the high temperature threshold.
static byte TEMP_LOW_SEARCH_FLAG
          CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the low temperature threshold.
static byte TEMPERATURE_HIGH_ALARM
          Type of alarm triggered when the temperature goes above the temperature threshold.
static byte TEMPERATURE_HIGH_FLAG
          STATUS REGISTER FLAG: Will read back true when the temperature during a mission reaches or exceeds the temperature high threshold.
static byte TEMPERATURE_LOW_ALARM
          Type of alarm triggered when temperature goes below the temperature threshold.
static byte TEMPERATURE_LOW_FLAG
          STATUS REGISTER FLAG: Will read back true when a temperature equal to or below the low temperature threshold was detected on a mission.
static byte TIMER_ALARM
          Type of alarm triggered when time reaches that set in alarm clock regs.
static byte TIMER_ALARM_FLAG
          STATUS REGISTER FLAG: Will read back true when a clock alarm has occured.
static byte TIMER_ALARM_SEARCH_FLAG
          CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if a timer alarm has occured.
 
Fields inherited from interface com.dalsemi.onewire.container.TemperatureContainer
ALARM_HIGH, ALARM_LOW
 
Constructor Summary
OneWireContainer21()
          Default constructor
OneWireContainer21(DSPortAdapter sourceAdapter, byte[] newAddress)
          Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
OneWireContainer21(DSPortAdapter sourceAdapter, long newAddress)
          Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
OneWireContainer21(DSPortAdapter sourceAdapter, java.lang.String newAddress)
          Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
 
Method Summary
 boolean canDisableClock()
          Query to see if the clock can be disabled.
 void clearMemory()
          Clears the memory - Must be run before setup for a new mission.
 double decodeTemperature(byte tempByte)
          Convert a temperature from the DS1921 byte format to degrees celcius.
 void disableMission()
          Disable a mission that is in progress.
 void doTemperatureConvert(byte[] state)
          Perform an temperature conversion.
 void enableMission(int sampleRate)
          Tells the DS1921 to begin its mission.
 byte encodeTemperature(double temperature)
          Convert a temperature (degrees celcius) to a byte formatted for the DS1921.
 byte[] getAlarmHistory(byte alarmBit)
          Returns an array containing the alarm log.
 boolean getAlarmStatus(byte alarmBit, byte[] state)
          Returns true if the specified alarm has been triggered.
 java.util.Calendar getAlarmTime(byte[] state)
          Get the alarm clock time settings.
 java.lang.String getAlternateNames()
          Return the alternate Dallas Semiconductor part number or name.
 long getClock(byte[] state)
          This method extracts the Clock Value in milliseconds from the state data retrieved from the 'readDevice()' method.
 long getClockAlarm(byte[] state)
          This method extracts the Clock Alarm Value from the provided state data retrieved from the 'readDevice()' method.
 long getClockResolution()
          Query to get the clock resolution in milliseconds
 java.lang.String getDescription()
          Return a short description of the function of the iButton type.
 int getDeviceSamplesCounter(byte[] state)
          Read the device samples counter and determine the number of samples taken by this device.
 long getFirstLogOffset(byte[] state)
          This method is a convenience method to help determine the times for values in a temperature log.
 boolean getFlag(int register, byte bitMask)
          Get the flag located in the specified register and return its status.
 boolean getFlag(int register, byte bitMask, byte[] state)
          Get the flag located in the specified register and return its status.
 int getMaxSpeed()
          Returns the maximum speed this iButton or 1-Wire device can communicate at.
 double getMaxTemperature()
          Query to get the maximum temperature in degrees C.
 java.util.Enumeration getMemoryBanks()
          Return an enumeration of memory banks.
 double getMinTemperature()
          Query to get the minimum temperature in degrees C.
 int getMissionSamplesCounter(byte[] state)
          Read the Mission Samples Counter and determine the number of samples taken on this mission.
 java.util.Calendar getMissionTimeStamp(byte[] state)
          Returns the date and time that the Mission was first started.
 java.lang.String getName()
          Returns the Dallas Semiconductor part number of the iButton as a string.
 int getSampleRate(byte[] state)
          Return the rate at which the DS1921 takes temperature measurements.
 double getTemperature(byte[] state)
          This method extracts the Temperature Value in degrees C from the state data retrieved from the 'readDevice()' method.
 double getTemperatureAlarm(int alarmType, byte[] state)
          This method extracts the specified Alarm value in degrees C from the state data retrieved from the 'readDevice()' method.
 double getTemperatureAlarmResolution()
          Query to get the high/low resolution in degrees C.
 int[] getTemperatureHistogram()
          Return an array of int values representing the 63 counter bins holding the DS1921 histogram data.
For the temperature histogram the DS1921 provides 63 bins that each consist of a 16-bit non rolling-over binary counter that is incremented each time a temperature value acquired during a mission falls into the range of the bin.
 byte[] getTemperatureLog(byte[] state)
          Return the log of temperature measurements.
 double getTemperatureResolution(byte[] state)
          This method extracts the current resolution in degrees C from the state data retrieved from the 'readDevice()' method.
 double[] getTemperatureResolutions()
          Query to get an array of available resolutions in degrees C.
 boolean hasClockAlarm()
          Query to see if the clock has an alarm feature.
 boolean hasSelectableTemperatureResolution()
          Query to see if this device has selectable resolution.
 boolean hasTemperatureAlarms()
          Query to see if this temperature measuring device has high/low trip alarms.
 boolean isClockAlarmEnabled(byte[] state)
          This method checks if the Clock Alarm is enabled from the provided state data retrieved from the 'readDevice()' method.
 boolean isClockAlarming(byte[] state)
          This method checks if the Clock Alarm flag has been set from the state data retrieved from the 'readDevice()' method.
 boolean isClockRunning(byte[] state)
          This method checks if the device's oscilator is enabled.
 byte readByte(int memAddr)
          Read a single byte from the DS1921.
 byte[] readDevice()
          This method retrieves the 1-Wire device sensor state.
 void setClock(long time, byte[] state)
          This method sets the Clock time in the provided state data Use the method 'writeDevice()' with this data to finalize the change to the device.
 void setClockAlarm(int hours, int minutes, int seconds, int day, int alarmFrequency, byte[] state)
          Set the DS1921's alarm clock's time.
 void setClockAlarm(long time, byte[] state)
          This method sets the Clock Alarm in the provided state data.
 void setClockAlarmEnable(boolean alarmEnable, byte[] state)
          This method sets the Clock Alarm enable.
 void setClockRunEnable(boolean runEnable, byte[] state)
          This method sets the oscillator enable to the specified value.
 void setFlag(int register, byte bitMask, boolean flagValue)
          Set the flag located in the specified register.
 void setFlag(int register, byte bitMask, boolean flagValue, byte[] state)
          Method setFlag
 void setMissionStartDelay(int missionStartDelay, byte[] state)
          Sets the time to wait before starting the mission.
 void setSpeedCheck(boolean doSpeedCheck)
          To ensure that all parts can talk to the onewire bus at their desired speed, each method contains a call to doSpeed().
 void setTemperatureAlarm(int alarmType, double alarmValue, byte[] state)
          This method sets the alarm value in degrees C in the provided state data.
 void setTemperatureResolution(double resolution, byte[] state)
          This method sets the current resolution in degrees C in the provided state data.
 void writeByte(int memAddr, byte source)
          Write a byte of data into the DS1921's memory.
 void writeDevice(byte[] state)
          This method write the 1-Wire device sensor state that have been changed by the 'set' methods.
 
Methods inherited from class com.dalsemi.onewire.container.OneWireContainer
doSpeed, getAdapter, getAddress, getAddressAsLong, getAddressAsString, isAlarming, isPresent, setSpeed, setupContainer, setupContainer, setupContainer
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

STATUS_REGISTER

public static final int STATUS_REGISTER
Address of the status register. Used with getFlag/setFlag to set and check flags indicating the thermochron's status.

CONTROL_REGISTER

public static final int CONTROL_REGISTER
Address of the control register. Used with getFlag/setFlag to set and check flags indicating the thermochron's status.

ONCE_PER_SECOND

public static final byte ONCE_PER_SECOND
Alarm frequency setting.

ONCE_PER_MINUTE

public static final byte ONCE_PER_MINUTE
Alarm frequency setting

ONCE_PER_HOUR

public static final byte ONCE_PER_HOUR
Alarm frequency setting.

ONCE_PER_DAY

public static final byte ONCE_PER_DAY
Alarm frequency setting.

ONCE_PER_WEEK

public static final byte ONCE_PER_WEEK
Alarm frequency setting.

TEMPERATURE_LOW_ALARM

public static final byte TEMPERATURE_LOW_ALARM
Type of alarm triggered when temperature goes below the temperature threshold.

TEMPERATURE_HIGH_ALARM

public static final byte TEMPERATURE_HIGH_ALARM
Type of alarm triggered when the temperature goes above the temperature threshold.

TIMER_ALARM

public static final byte TIMER_ALARM
Type of alarm triggered when time reaches that set in alarm clock regs.

TIMER_ALARM_SEARCH_FLAG

public static final byte TIMER_ALARM_SEARCH_FLAG
CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if a timer alarm has occured. To be used with getFlag/setFlag.

TEMP_HIGH_SEARCH_FLAG

public static final byte TEMP_HIGH_SEARCH_FLAG
CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the high temperature threshold. To be used with getFlag/setFlag.

TEMP_LOW_SEARCH_FLAG

public static final byte TEMP_LOW_SEARCH_FLAG
CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if the temperature has reached the low temperature threshold. To be used with getFlag/setFlag.

ROLLOVER_ENABLE_FLAG

public static final byte ROLLOVER_ENABLE_FLAG
CONTROL REGISTER FLAG: When enabled, the device will begin overwriting the earlier temperature measurements when the memory becomes full. To be used with getFlag/setFlag.

MISSION_ENABLE_FLAG

public static final byte MISSION_ENABLE_FLAG
CONTROL REGISTER FLAG: When DISABLED, the mission will start as soon as the sample rate is written. To be used with getFlag/setFlag.

MEMORY_CLEAR_ENABLE_FLAG

public static final byte MEMORY_CLEAR_ENABLE_FLAG
CONTROL REGISTER FLAG: Must be enabled to enable the clear memory function. Must be set immediately before the command is issued. To be used with getFlag/setFlag.

OSCILLATOR_ENABLE_FLAG

public static final byte OSCILLATOR_ENABLE_FLAG
CONTROL REGISTER FLAG: When DISABLED, the real time clock will start working. Must be disabled for normal operation. To be used with getFlag/setFlag.

TIMER_ALARM_FLAG

public static final byte TIMER_ALARM_FLAG
STATUS REGISTER FLAG: Will read back true when a clock alarm has occured. To be used with getFlag.

TEMPERATURE_HIGH_FLAG

public static final byte TEMPERATURE_HIGH_FLAG
STATUS REGISTER FLAG: Will read back true when the temperature during a mission reaches or exceeds the temperature high threshold. To be used with getFlag.

TEMPERATURE_LOW_FLAG

public static final byte TEMPERATURE_LOW_FLAG
STATUS REGISTER FLAG: Will read back true when a temperature equal to or below the low temperature threshold was detected on a mission. To be used with getFlag.

SAMPLE_IN_PROGRESS_FLAG

public static final byte SAMPLE_IN_PROGRESS_FLAG
STATUS REGISTER FLAG: Will read back true when a mission temperature conversion is in progress To be used with getFlag.

MISSION_IN_PROGRESS_FLAG

public static final byte MISSION_IN_PROGRESS_FLAG
STATUS REGISTER FLAG: Will read back true when a mission is in progress. To be used with getFlag.

MEMORY_CLEARED_FLAG

public static final byte MEMORY_CLEARED_FLAG
STATUS REGISTER FLAG: Will read back true if the memory has been cleared. To be used with getFlag.

TEMP_CORE_BUSY_FLAG

public static final byte TEMP_CORE_BUSY_FLAG
STATUS REGISTER FLAG: Will read back true if a temperature conversion of any kind is in progress. To be used with getFlag.
Constructor Detail

OneWireContainer21

public OneWireContainer21()
Default constructor

OneWireContainer21

public OneWireContainer21(DSPortAdapter sourceAdapter,
                          byte[] newAddress)
Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
Parameters:
sourceAdapter - adapter object required to communicate with this iButton.
newAddress - address of this 1-Wire device

OneWireContainer21

public OneWireContainer21(DSPortAdapter sourceAdapter,
                          long newAddress)
Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
Parameters:
sourceAdapter - adapter object required to communicate with this iButton.
newAddress - address of this 1-Wire device

OneWireContainer21

public OneWireContainer21(DSPortAdapter sourceAdapter,
                          java.lang.String newAddress)
Create a container with a provided adapter object and the address of the iButton or 1-Wire device.
Parameters:
sourceAdapter - adapter object required to communicate with this iButton.
newAddress - address of this 1-Wire device
Method Detail

getMemoryBanks

public java.util.Enumeration getMemoryBanks()
Return an enumeration of memory banks. Look at the MemoryBank, PagedMemoryBank and OTPMemoryBank classes.
Overrides:
getMemoryBanks in class OneWireContainer
Following copied from class: com.dalsemi.onewire.container.OneWireContainer
Returns:
enumeration of memory banks to read and write memory on this iButton or 1-Wire device.

setSpeedCheck

public void setSpeedCheck(boolean doSpeedCheck)
To ensure that all parts can talk to the onewire bus at their desired speed, each method contains a call to doSpeed(). However, this is an expensive operation. You can handle the speed in your application without the expense of the doSpeed call by calling this with false. The default behaviour is to call doSpeed().
Parameters:
doSpeedCheck - True if you want doSpeed() called before every onewire bus access. False to skip this expensive call.

getMaxSpeed

public int getMaxSpeed()
Returns the maximum speed this iButton or 1-Wire device can communicate at.
Overrides:
getMaxSpeed in class OneWireContainer

getName

public java.lang.String getName()
Returns the Dallas Semiconductor part number of the iButton as a string.
Overrides:
getName in class OneWireContainer
Returns:
String representation of the iButton name

getAlternateNames

public java.lang.String getAlternateNames()
Return the alternate Dallas Semiconductor part number or name.
Overrides:
getAlternateNames in class OneWireContainer
Returns:
String representation of the alternate names.

getDescription

public java.lang.String getDescription()
Return a short description of the function of the iButton type.
Overrides:
getDescription in class OneWireContainer
Returns:
String representation of the function description.

decodeTemperature

public double decodeTemperature(byte tempByte)
Convert a temperature from the DS1921 byte format to degrees celcius. The raw temperature readings are just unsigned byte sized values that need to be converted to a valid temperature in degreees celcius.
Parameters:
tempByte - raw DS1921 temperature reading.
Returns:
double representing a temperature, in degrees celcius.

encodeTemperature

public byte encodeTemperature(double temperature)
Convert a temperature (degrees celcius) to a byte formatted for the DS1921.
Parameters:
temperature - the temperature to convert.
Returns:
byte holding the temperature in raw DS1921 format.

writeByte

public void writeByte(int memAddr,
                      byte source)
               throws OneWireIOException,
                      OneWireException
Write a byte of data into the DS1921's memory. Note that writing to the register page while a mission is in progress ends that mission.
Parameters:
memAddr - the address to write the byte at. (Usually in the range of 0x200-0x21F)
source - the data byte to write to memory.
Throws:
OneWireIOException - Data wasnt written properly [ recoverable ]
OneWireException - Part could not be found [ fatal ]

readByte

public byte readByte(int memAddr)
              throws OneWireIOException,
                     OneWireException
Read a single byte from the DS1921.
Parameters:
int - representation of the address to read from.
memAddr - The address to read from. Registers begin at address 0x200 and end at address 0x21F.
Returns:
byte the data byte read.
Throws:
OneWireIOException - Data was not read correctly [ recoverable ]
OneWireException - Could not find the part [ fatal ]

getFlag

public boolean getFlag(int register,
                       byte bitMask)
                throws OneWireIOException,
                       OneWireException
Get the flag located in the specified register and return its status. This method actually communicates with the Thermocron. To improve performance if you intend to make multiple calls to this method, first call readDevice and use the getFlag(int, byte, byte[]) method instead.
Parameters:
register - address of register containing the flag.
Valid parameters: CONTROL_REGISTER, STATUS_REGISTER.
bitMask - bitmask representing the flag. There are 7 valid parameters for each register. See "FIELD SUMMARY" for a listing.
Returns:
boolean indicating the status of the flag. True signifies a "1" and false signifies a "0".
Throws:
OneWireIOException - Data was not read correctly [ recoverable ]
OneWireException - Could not find the part [ fatal ]

getFlag

public boolean getFlag(int register,
                       byte bitMask,
                       byte[] state)
Get the flag located in the specified register and return its status.
Parameters:
register - address of register containing the flag.
Valid parameters: CONTROL_REGISTER, STATUS_REGISTER.
bitMask - bitmask representing the flag. There are 7 valid parameters for each register. See "FIELD SUMMARY" for a listing.
state - State of Thermocron returned from readDevice().
Returns:
boolean indicating the status of the flag. True signifies a "1" and false signifies a "0".

setFlag

public void setFlag(int register,
                    byte bitMask,
                    boolean flagValue)
             throws OneWireIOException,
                    OneWireException
Set the flag located in the specified register. If a mission is in progress a OneWireIOException will be thrown (one cannot write to the registers while a mission is commencing).
Parameters:
register - the address of the target register.

Valid parameters: CONTROL_REGISTER, STATUS_REGISTER.

bitMask - bitmask representing the flag. There are 7 valid parameters for each register. See "FIELD SUMMARY" for details.
flagValue - value to set flag at.
Throws:
OneWireIOException - Data was not written correctly [ recoverable ]
OneWireException - Could not find the part [ fatal ]

setFlag

public void setFlag(int register,
                    byte bitMask,
                    boolean flagValue,
                    byte[] state)
Method setFlag
Parameters:
register -  
bitMask -  
flagValue -  
state -  

enableMission

public void enableMission(int sampleRate)
                   throws OneWireIOException,
                          OneWireException
Tells the DS1921 to begin its mission. If a mission is already in progress, this will throw a OneWireIOException. Note: The mission will wait the number of minutes specified by the mission start delay (use setMissionStartDelay()) before beginning.
Parameters:
sampleRate - the number of minutes to wait in between temp readings.
Throws:
OneWireIOException - Mission was not started [ recoverable ]
OneWireException - Could not find the part [ fatal ]

disableMission

public void disableMission()
                    throws OneWireIOException,
                           OneWireException
Disable a mission that is in progress.
Throws:
OneWireIOException - Mission was not stopped [ recoverable ]
OneWireException - Could not find the part [ fatal ]

setMissionStartDelay

public void setMissionStartDelay(int missionStartDelay,
                                 byte[] state)
Sets the time to wait before starting the mission. The DS1921 will sleep this many minutes after the mission is enabled. If a mission is in progress a OneWireIOException is thrown.
Parameters:
missionStartDelay - specifies the time, in minutes, to delay.
state - State of Thermocron returned from readDevice().

clearMemory

public void clearMemory()
                 throws OneWireIOException,
                        OneWireException
Clears the memory - Must be run before setup for a new mission. If a mission is in progress a OneWireIOException is thrown.
Throws:
OneWireIOException - Memory was not cleared [ recoverable ]
OneWireException - Could not find the part [ fatal ]

getAlarmTime

public java.util.Calendar getAlarmTime(byte[] state)
Get the alarm clock time settings. The alarm settings used by the Thermocron are Hour, Minute, Second, and Day of Week.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
Calendar object holding the alarm clock time and day of the week. The day of the week is stored in the DAY_OF_MONTH element.

setClockAlarm

public void setClockAlarm(int hours,
                          int minutes,
                          int seconds,
                          int day,
                          int alarmFrequency,
                          byte[] state)
Set the DS1921's alarm clock's time. Some of the parameters might be unimportant depending on the alarm frequency setting. For instance, if the alarm frequency setting is ONCE_PER_MINUTE, then the hour argument is irrelevant.
Parameters:
hours - The hour of the day for the clock alarm
minutes - The minute setting for the clock alarm
seconds - The second setting for the clock alarm
day - The day of the week for the clock alarm. The value must be between 1 (Sunday) and 7 (Saturday).
alarmFrequency - representation of the alarm frequency.

Valid parameters are: ONCE_PER_SECOND, ONCE_PER_MINUTE, ONCE_PER_HOUR, ONCE_PER_DAY, ONCE_PER_WEEK.

state - State of Thermocron returned from readDevice().

getSampleRate

public int getSampleRate(byte[] state)
Return the rate at which the DS1921 takes temperature measurements.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
int representing the time, in minutes, between temperature readings.

getMissionSamplesCounter

public int getMissionSamplesCounter(byte[] state)
Read the Mission Samples Counter and determine the number of samples taken on this mission.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
int the number of samples taken on this mission.

getDeviceSamplesCounter

public int getDeviceSamplesCounter(byte[] state)
Read the device samples counter and determine the number of samples taken by this device.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
int the number of measurements, including forced, taken by this device.

getMissionTimeStamp

public java.util.Calendar getMissionTimeStamp(byte[] state)
Returns the date and time that the Mission was first started.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
Calendar object containing the date/time.

getFirstLogOffset

public long getFirstLogOffset(byte[] state)
This method is a convenience method to help determine the times for values in a temperature log. If rollover is enabled, temperature log entries will over-write previous entries once more than 2048 logs are written. This value can be added to the underlying millisecond value of getMissionTimeStamp() to determine the time that the 'first' log entry actually occurred. Take care with Java's Daylight Savings Time offsets when using this function--if you use the Date or Calendar class to print this out, Java may try to automatically format the string to handle Daylight Savings Time, resulting in offset by 1 hour problems.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
Milliseconds between the beginning of the mission and the first log entry's time reported from getTemperatureLog().

getTemperatureLog

public byte[] getTemperatureLog(byte[] state)
                         throws OneWireIOException,
                                OneWireException
Return the log of temperature measurements. Reads through the entire temperature log, and returns an array containing the temperatures recorded.
Parameters:
state - State of Thermocron returned from readDevice().
Returns:
byte[] the DS1921's log. Use decodeTemperature(byte) to get the double value of the encoded temperature. See the DS1921 datasheet for more on the data's encoding scheme. The array's length equals the number of measurements taken thus far.
Throws:
OneWireIOException - Did not read the memory [ recoverable ]
OneWireException - Could not find the part [ fatal ]

getTemperatureHistogram

public int[] getTemperatureHistogram()
                              throws OneWireIOException,
                                     OneWireException
Return an array of int values representing the 63 counter bins holding the DS1921 histogram data.
For the temperature histogram the DS1921 provides 63 bins that each consist of a 16-bit non rolling-over binary counter that is incremented each time a temperature value acquired during a mission falls into the range of the bin. The bin to be updated is determined by cutting off the two least significant bits of the binary temperature value. Thus bin 1 will hold the counter for temperatures ranging from -40 to -38.5 (celcius) and lower. Bin 2 is associated with the range of -38 to 36.5 and so on. Bin 63 is the final bin, and it holds temperature values of 84 degrees and higher.
Returns:
int[] the 63 temperature counters.
Throws:
OneWireIOException - Did not read the memory [ recoverable ]
OneWireException - Could not find the part [ fatal ]

getAlarmStatus

public boolean getAlarmStatus(byte alarmBit,
                              byte[] state)
                       throws OneWireIOException,
                              OneWireException
Returns true if the specified alarm has been triggered.
Parameters:
alarmBit - a bitmask indicating the alarm to check. Acceptable parameters: TEMPERATURE_LOW_ALARM, TEMPERATURE_HIGH_ALARM, TIMER_ALARM.
state - State of Thermocron returned from readDevice().
Returns:
boolean indicating whether the alarm has gone off.

getAlarmHistory

public byte[] getAlarmHistory(byte alarmBit)
                       throws OneWireIOException,
                              OneWireException
Returns an array containing the alarm log. The DS1921 contains two seperate alarm logs. One for the temperature high alarm and one for the temperature low alarm. Each log can store up to 12 log entries and each log entry will record up to 255 consecutive alarm violations.
Parameters:
alarmBit - representing the alarm log to get. Acceptable parameters: TEMPERATURE_LOW_ALARM, TEMPERATURE_HIGH_ALARM.
Returns:
byte[] representing the time/duration of the alarm. Structure of returned array: The number of logs in this alarm history if equal to the array length divided by 4, since each entry is 4 bytes. To extract the starting offset and number of violations from the array: byte[] data = ds1921.getAlarmHistory(TEMPERATURE_HIGH_ALARM); . . . for (int i=0;i < data.length/4; i++) { start_offset = (data [i * 4] & 0x0ff) | ((data [i * 4 + 1] << 8) & 0x0ff00) | ((data [i * 4 + 2] << 16) & 0x0ff0000); violation_count = 0x0ff & data[i*4+3]; . . . // note: you may find it useful to multiply start_offset // by getSampleRate() in order to get the number of // minutes into the mission that the violation occurred // on. You can do the same with violation_count // to determine how long the violation lasted.
Throws:
OneWireIOException - Did not read the memory [ recoverable ]
OneWireException - Could not find the part [ fatal ]

readDevice

public byte[] readDevice()
                  throws OneWireIOException,
                         OneWireException
This method retrieves the 1-Wire device sensor state. This state is returned as a byte array. Pass this byte array to the static query and set methods. If the device state needs to be changed then call the 'writeDevice' to finalize the one or more change.
Specified by:
readDevice in interface OneWireSensor
Returns:
byte[] 1-Wire device sensor state
Throws:
OneWireIOException -  
OneWireException - Could not find the part [ fatal ]

writeDevice

public void writeDevice(byte[] state)
                 throws OneWireIOException,
                        OneWireException
This method write the 1-Wire device sensor state that have been changed by the 'set' methods. It knows which registers have changed by looking at the bitmap fields appended to the state data.
Specified by:
writeDevice in interface OneWireSensor
Parameters:
state - byte array of clock register page contents
Throws:
OneWireIOException -  
OneWireException - Could not find the part [ fatal ]

hasTemperatureAlarms

public boolean hasTemperatureAlarms()
Query to see if this temperature measuring device has high/low trip alarms.
Specified by:
hasTemperatureAlarms in interface TemperatureContainer
Returns:
boolean, true if has high/low trip alarms

hasSelectableTemperatureResolution

public boolean hasSelectableTemperatureResolution()
Query to see if this device has selectable resolution.
Specified by:
hasSelectableTemperatureResolution in interface TemperatureContainer
Returns:
boolean, true if has selectable resolution

getTemperatureResolutions

public double[] getTemperatureResolutions()
Query to get an array of available resolutions in degrees C.
Specified by:
getTemperatureResolutions in interface TemperatureContainer
Returns:
double[], available of resolutions in degrees C

getTemperatureAlarmResolution

public double getTemperatureAlarmResolution()
Query to get the high/low resolution in degrees C.
Specified by:
getTemperatureAlarmResolution in interface TemperatureContainer
Returns:
double, high/low resolution resolution in C

getMaxTemperature

public double getMaxTemperature()
Query to get the maximum temperature in degrees C.
Specified by:
getMaxTemperature in interface TemperatureContainer
Returns:
double, maximum temperature in C

getMinTemperature

public double getMinTemperature()
Query to get the minimum temperature in degrees C.
Specified by:
getMinTemperature in interface TemperatureContainer
Returns:
double, minimum temperature in C

doTemperatureConvert

public void doTemperatureConvert(byte[] state)
                          throws OneWireIOException,
                                 OneWireException
Perform an temperature conversion. Use this state information to calculate the conversion time.
Specified by:
doTemperatureConvert in interface TemperatureContainer
Parameters:
state - byte array of device state
Throws:
OneWireIOException -  
OneWireException - Could not find the part [ fatal ]

getTemperature

public double getTemperature(byte[] state)
This method extracts the Temperature Value in degrees C from the state data retrieved from the 'readDevice()' method.
Specified by:
getTemperature in interface TemperatureContainer
Parameters:
state - byte array of device state
Returns:
double, temperature in degrees C from the last 'doTemperature()'

getTemperatureAlarm

public double getTemperatureAlarm(int alarmType,
                                  byte[] state)
This method extracts the specified Alarm value in degrees C from the state data retrieved from the 'readDevice()' method.
Specified by:
getTemperatureAlarm in interface TemperatureContainer
Parameters:
alarmType - integer, indicating trip type ALARM_HIGH (1) or ALARM_LOW (0)
state - byte array of device state
Returns:
double, alarm trip temperature in degrees C

getTemperatureResolution

public double getTemperatureResolution(byte[] state)
This method extracts the current resolution in degrees C from the state data retrieved from the 'readDevice()' method.
Specified by:
getTemperatureResolution in interface TemperatureContainer
Parameters:
state - byte array of device state
Returns:
double, temperature resolution in degrees C

setTemperatureAlarm

public void setTemperatureAlarm(int alarmType,
                                double alarmValue,
                                byte[] state)
This method sets the alarm value in degrees C in the provided state data. Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setTemperatureAlarm in interface TemperatureContainer
Parameters:
alarmType - integer, indicating trip type ALARM_HIGH (1) or ALARM_LOW (0)
alarmValue - double, high trip value in degrees C
state - byte array of device state

setTemperatureResolution

public void setTemperatureResolution(double resolution,
                                     byte[] state)
                              throws OneWireException,
                                     OneWireIOException
This method sets the current resolution in degrees C in the provided state data. Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setTemperatureResolution in interface TemperatureContainer
Parameters:
resolution - double, temperature resolution in degrees C
state - byte array of device state

hasClockAlarm

public boolean hasClockAlarm()
Query to see if the clock has an alarm feature.
Specified by:
hasClockAlarm in interface ClockContainer
Returns:
boolean, true if real-time-clock has an alarm

canDisableClock

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

getClockResolution

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

getClock

public long getClock(byte[] state)
This method extracts the Clock Value in milliseconds from the state data retrieved from the 'readDevice()' method.
Specified by:
getClock in interface ClockContainer
Parameters:
state - byte array of device state
Returns:
long time - in milliseconds that have occured since 1970.

getClockAlarm

public long getClockAlarm(byte[] state)
This method extracts the Clock Alarm Value from the provided state data retrieved from the 'readDevice()' method. In the case of the thermocron it reports the next time the alarm will go off, since the Thermocron is set to alarm 'every week monday at 4:30' or in some similar manner.
Specified by:
getClockAlarm in interface ClockContainer
Parameters:
state - byte array of device state
Returns:
long time - in milliseconds that have the clock alarm is set to.

isClockAlarming

public boolean isClockAlarming(byte[] state)
This method checks if the Clock Alarm flag has been set from the state data retrieved from the 'readDevice()' method.
Specified by:
isClockAlarming in interface ClockContainer
Parameters:
state - byte array of device state
Returns:
boolean true if clock is alarming

isClockAlarmEnabled

public boolean isClockAlarmEnabled(byte[] state)
This method checks if the Clock Alarm is enabled from the provided state data retrieved from the 'readDevice()' method.
Specified by:
isClockAlarmEnabled in interface ClockContainer
Parameters:
state - byte array of device state
Returns:
boolean true if clock alarm is enabled

isClockRunning

public boolean isClockRunning(byte[] state)
This method checks if the device's oscilator is enabled. The clock will not increment if the clock is not enabled. This value is read from the provided state data retrieved from the 'readDevice()' method.
Specified by:
isClockRunning in interface ClockContainer
Parameters:
state - byte array of device state
Returns:
boolean true

setClock

public void setClock(long time,
                     byte[] state)
This method sets the Clock time in the provided state data Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setClock in interface ClockContainer
Parameters:
time - millisecond value (from 1970) the user wants the Clock set to.
state - byte array of device state

setClockAlarm

public void setClockAlarm(long time,
                          byte[] state)
                   throws OneWireException
This method sets the Clock Alarm in the provided state data. Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setClockAlarm in interface ClockContainer
Parameters:
time - millisecond value (from 1970) the user wants the Clock alarm set to.
state - byte array of device state

setClockRunEnable

public void setClockRunEnable(boolean runEnable,
                              byte[] state)
This method sets the oscillator enable to the specified value. Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setClockRunEnable in interface ClockContainer
Parameters:
runEnable - boolean, true if want the clock oscillator to be enabled.
state - byte array of device state

setClockAlarmEnable

public void setClockAlarmEnable(boolean alarmEnable,
                                byte[] state)
This method sets the Clock Alarm enable. Use the method 'writeDevice()' with this data to finalize the change to the device.
Specified by:
setClockAlarmEnable in interface ClockContainer
Parameters:
alarmEnable - boolean, true to enable the clock alarm
state - byte array of device state