Dallas Semiconductor 1-Wire API 1.00 Alpha: Class OneWireContainer21

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

1-Wire® container for a Thermocron iButton, DS1921. This container encapsulates the functionality of the 1-Wire family type 21 (hex).

### Features

- Logs up to 2048 consecutive temperature measurements in nonvolatile, read-only memory
- Real-Time clock with programmable alarm
- Programmable high and low temperature alarms
- Alarm violation times and durations recorded in nonvolatile, read-only memory
- Automatically 'wakes up' and logs temperature at user-programmable intervals
- 4096 bits of general-purpose read/write nonvolatile memory
- 256-bit scratchpad ensures integrity of data transfer
- On-chip 16-bit CRC generator to verify read operations
- Long-term histogram with 2° C resolution

### 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 with CRC
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 32 starting at physical address 0
  - Features Read/Write not-general-purpose volatile
  - Pages 1 page of length 32 bytes
  - Page Features page-device-CRC
  - 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
  - Page Features page-device-CRC
- Register control
  - 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
  - Page Features page-device-CRC
- Alarm time stamps
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 96 starting at physical address 544
  - Features Read-only not-general-purpose non-volatile
  - Pages 3 pages of length 32 bytes
  - Page Features page-device-CRC
- Temperature histogram
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 128 starting at physical address 2048
  - Features Read-only not-general-purpose non-volatile
  - Pages 4 pages of length 32 bytes
  - Page Features page-device-CRC
- Temperature log
  - Implements `MemoryBank`, `PagedMemoryBank`
  - Size 2048 starting at physical address 4096
  - Features Read-only not-general-purpose non-volatile
  - Pages 64 pages of length 32 bytes
  - Page Features page-device-CRC

### Usage

The code below starts a mission with the following characteristics:

- Rollover flag enabled. This means if more than 2048 samples are taken, the newer samples overwrite the oldest samples in the temperature log.
- High alarm of 28.0° and a low alarm of 23.0° C. If the alarm is violated, the Temperature Alarm log will record when and for how long the violation occurred.
- The clock alarm enabled to Mondays at 12:30:45 pm.
- Sets the Thermocron's Real-Time Clock to the host system's clock.
- The mission will start in 2 minutes.
- A sample rate of 1 minute.

This code also ensures that the Thermocron's clock is set to run, and that the clock alarm is enabled.

           // "ID" is a byte array of size 8 with an address of a part we
           // have already found with family code 12 hex
           // "access" is a DSPortAdapter
           OneWireContainer21 ds1921 = (OneWireContainer21) access.getDeviceContainer(ID);
           ds1921.setupContainer(access,ID);
           //  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);

The following code processes the temperature log:

`

           byte[] state = ds1921.readDevice();
           byte[] log = ds1921.getTemperatureLog(state);
           Calendar time_stamp = ds1921.getMissionTimeStamp(state);
           long time = time_stamp.getTime().getTime() + ds1921.getFirstLogOffset(state);
           int sample_rate = ds1921.getSampleRate(state);

           System.out.println("TEMPERATURE LOG");

           for (int i=0;i < log.length;i++)
           {
               System.out.println("- Temperature recorded at  : "+(new Date(time)));
               System.out.println("-                     was  : "+ds1921.decodeTemperature(log[i])+" C");
               time += sample_rate * 60 * 1000;
           }

`

The following code processes the alarm histories:

`

           byte[] high_history = ds1921.getAlarmHistory(ds1921.TEMPERATURE_HIGH_ALARM);
           byte[] low_history = ds1921.getAlarmHistory(ds1921.TEMPERATURE_LOW_ALARM);
           int sample_rate = ds1921.getSampleRate(state);
           int start_offset, violation_count;
           System.out.println("ALARM HISTORY");
           if (low_history.length==0)
           {
               System.out.println("- No violations against the low temperature alarm.");
               System.out.println("-");
           }
           for (int i=0;i < low_history.length/4; i++)
           {
               start_offset = (low_history [i * 4] & 0x0ff)
                         | ((low_history [i * 4 + 1] << 8) & 0x0ff00)
                         | ((low_history [i * 4 + 2] << 16) & 0x0ff0000);
               violation_count = 0x0ff & low_history[i*4+3];
               System.out.println("- Low alarm started at     : "+(start_offset * sample_rate));
               System.out.println("-                          : Lasted "+(violation_count * sample_rate)+" minutes");
           }
           if (high_history.length==0)
           {
               System.out.println("- No violations against the high temperature alarm.");
               System.out.println("-");
           }
           for (int i=0;i < high_history.length/4; i++)
           {
               start_offset = (high_history [i * 4] & 0x0ff)
                         | ((high_history [i * 4 + 1] << 8) & 0x0ff00)
                         | ((high_history [i * 4 + 2] << 16) & 0x0ff0000);
               violation_count = 0x0ff & high_history[i*4+3];
               System.out.println("- High alarm started at    : "+(start_offset * sample_rate));
               System.out.println("-                          : Lasted "+(violation_count * sample_rate)+" minutes");
           }

`

The following code processes the temperature histogram:

`

           int[] histogram = ds1921.getTemperatureHistogram();
           int start = -40;
           System.out.println("TEMPERATURE HISTOGRAM");
           for (int i=0;i < histogram.length;i++)
           {
               System.out.println("- Histogram entry          : "+histogram[i]+
                           " at temperature "+((double)start)+ " to "+
                           ((double)start+1.5)+" C");
               start += 2;
           }

`

Also see the usage examples in the `TemperatureContainer` and `ClockContainer` interfaces.

For examples regarding memory operations,

- See the usage example in `OneWireContainer` to enumerate the MemoryBanks.
- See the usage examples in `MemoryBank` and `PagedMemoryBank` for bank specific operations.

### DataSheet

  http://pdfserv.maxim-ic.com/arpdf/DS1921L-F5X.pdf

Also visit http://www.ibutton.com/ibuttons/thermochron.html for links to more sources on the DS1921 Thermocron.

Version:
  0.00, 28 Aug 2000
See Also:
  `OneWireSensor`, `SwitchContainer`, `TemperatureContainer`

Field Summary
`static int` | `CONTROL_REGISTER` Address of the control register.
`static byte` | `MEMORY_CLEAR_ENABLE_FLAG` CONTROL REGISTER FLAG: Must be enabled to allow a 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 for the `setClockAlarm()` method.
`static byte` | `ONCE_PER_HOUR` Alarm frequency setting for the `setClockAlarm()` method.
`static byte` | `ONCE_PER_MINUTE` Alarm frequency setting for the `setClockAlarm()` method.
`static byte` | `ONCE_PER_SECOND` Alarm frequency setting for the `setClockAlarm()` method.
`static byte` | `ONCE_PER_WEEK` Alarm frequency setting for the `setClockAlarm()` method.
`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 temperature log memory becomes full.
`static byte` | `SAMPLE_IN_PROGRESS_FLAG` STATUS REGISTER FLAG: Will read back true when a mission temperature conversion is in progress
`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` High temperature alarm value for the methods `getAlarmStatus()`, `getAlarmHistory()`, and `setTemperatureAlarm()`.
`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` Low temperature alarm value for the methods `getAlarmStatus()`, `getAlarmHistory()`, and `setTemperatureAlarm()`.
`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` Clock alarm value for the methods `getAlarmStatus()` and `isClockAlarming()`.
`static byte` | `TIMER_ALARM_FLAG` STATUS REGISTER FLAG: Will read back true when a clock alarm has occurred.
`static byte` | `TIMER_ALARM_SEARCH_FLAG` CONTROL REGISTER FLAG: When enabled, the device will respond to conditional search command if a timer alarm has occurred.

Fields inherited from interface com.dalsemi.onewire.container.TemperatureContainer
`ALARM_HIGH, ALARM_LOW`

Constructor Summary
`OneWireContainer21()` Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
`OneWireContainer21(DSPortAdapter sourceAdapter, byte[] newAddress)` Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
`OneWireContainer21(DSPortAdapter sourceAdapter, long newAddress)` Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
`OneWireContainer21(DSPortAdapter sourceAdapter, String newAddress)` Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.

Method Summary
`boolean` | `canDisableClock()` Checks to see if the clock can be disabled.
`void` | `clearMemory()` Clears the memory of any previous mission.
`double` | `decodeTemperature(byte tempByte)` Converts a temperature from the DS1921 `byte` encoded format to degrees Celsius.
`void` | `disableMission()` Ends this DS1921's running mission.
`void` | `doTemperatureConvert(byte[] state)` Performs a temperature conversion.
`void` | `enableMission(int sampleRate)` Begins this DS1921's mission.
`byte` | `encodeTemperature(double temperature)` Converts a temperature in degrees Celsius 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.
`Calendar` | `getAlarmTime(byte[] state)` Gets the clock alarm time settings.
`String` | `getAlternateNames()` Retrieves 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()` Gets the clock resolution in milliseconds
`String` | `getDescription()` Gets a short description of the function of this iButton or 1-Wire Device type.
`int` | `getDeviceSamplesCounter(byte[] state)` Determines the total number of samples taken by this Thermocron.
`long` | `getFirstLogOffset(byte[] state)` Helps determine the times for values in a temperature log.
`boolean` | `getFlag(int register, byte bitMask)` Gets the status of the specified flag from the specified register.
`boolean` | `getFlag(int register, byte bitMask, byte[] state)` Gets the status of the specified flag from the specified register.
`int` | `getMaxSpeed()` Returns the maximum speed this iButton device can communicate at.
`double` | `getMaxTemperature()` Gets the maximum temperature in Celsius.
`Enumeration` | `getMemoryBanks()` Gets an enumeration of memory bank instances that implement one or more of the following interfaces: `MemoryBank`, `PagedMemoryBank`, and `OTPMemoryBank`.
`double` | `getMinTemperature()` Gets the minimum temperature in Celsius.
`int` | `getMissionSamplesCounter(byte[] state)` Determines the number of samples taken on this mission.
`Calendar` | `getMissionTimeStamp(byte[] state)` Returns the date and time that the last mission was started.
`String` | `getName()` Gets the Dallas Semiconductor part number of the iButton or 1-Wire Device as a `java.lang.String`.
`int` | `getSampleRate(byte[] state)` Returns the rate at which the DS1921 takes temperature samples.
`double` | `getTemperature(byte[] state)` Gets the temperature value in Celsius from the `state` data retrieved from the `readDevice()` method.
`double` | `getTemperatureAlarm(int alarmType, byte[] state)` Gets the specified temperature alarm value in Celsius from the `state` data retrieved from the `readDevice()` method.
`double` | `getTemperatureAlarmResolution()` Gets the temperature alarm resolution in Celsius.
`int[]` | `getTemperatureHistogram()` Returns an array of the 63 counter bins holding the DS1921 histogram data.
`byte[]` | `getTemperatureLog(byte[] state)` Returns the log of temperature measurements.
`double` | `getTemperatureResolution(byte[] state)` Gets the current temperature resolution in Celsius from the `state` data retrieved from the `readDevice()` method.
`double[]` | `getTemperatureResolutions()` Get an array of available temperature resolutions in Celsius.
`boolean` | `hasClockAlarm()` Checks to see if the clock has an alarm feature.
`boolean` | `hasSelectableTemperatureResolution()` Checks to see if this device has selectable temperature resolution.
`boolean` | `hasTemperatureAlarms()` Checks to see if this temperature measuring device has high/low trip alarms.
`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` | `readByte(int memAddr)` Reads a single byte from the DS1921.
`byte[]` | `readDevice()` Retrieves the 1-Wire device sensor state.
`void` | `setClock(long time, byte[] state)` Sets the Real-Time clock.
`void` | `setClockAlarm(int hours, int minutes, int seconds, int day, int alarmFrequency, byte[] state)` Set the DS1921's alarm 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` | `setFlag(int register, byte bitMask, boolean flagValue)` Sets the status of the specified flag in the specified register.
`void` | `setFlag(int register, byte bitMask, boolean flagValue, byte[] state)` Sets the status of the specified flag in the specified register.
`void` | `setMissionStartDelay(int missionStartDelay, byte[] state)` Sets the time to wait before starting the mission.
`void` | `setSpeedCheck(boolean doSpeedCheck)` Directs the container to avoid the calls to doSpeed() in methods that communicate with the Thermocron.
`void` | `setTemperatureAlarm(int alarmType, double alarmValue, byte[] state)` Sets the temperature alarm value in Celsius in the provided `state` data.
`void` | `setTemperatureResolution(double resolution, byte[] state)` Sets the current temperature resolution in Celsius in the provided `state` data.
`void` | `writeByte(int memAddr, byte source)` Writes a byte of data into the DS1921's memory.
`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, 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 the `getFlag` and `setFlag` methods to set and check flags indicating the Thermochron's status.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### CONTROL_REGISTER

    public static final int CONTROL_REGISTER

  Address of the control register. Used with the `getFlag` and `setFlag` methods to set and check flags indicating the Thermochron's status.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### ONCE_PER_SECOND

    public static final byte ONCE_PER_SECOND

  Alarm frequency setting for the `setClockAlarm()` method. If the DS1921 Thermocron alarm is enabled and is not alarming, it will alarm on the next Real-Time Clock second.
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`

### ONCE_PER_MINUTE

    public static final byte ONCE_PER_MINUTE

  Alarm frequency setting for the `setClockAlarm()` method. If the DS1921 Thermocron alarm is enabled and is not alarming, it will alarm the next time the Real-Time Clock's 'second' value is equal to the Alarm Clock's 'second' value.
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`

### ONCE_PER_HOUR

    public static final byte ONCE_PER_HOUR

  Alarm frequency setting for the `setClockAlarm()` method. If the DS1921 Thermocron alarm is enabled and is not alarming, it will alarm the next time the Real-Time Clock's 'second' and 'minute' values are equal to the Alarm Clock's 'second' and 'minute' values.
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`

### ONCE_PER_DAY

    public static final byte ONCE_PER_DAY

  Alarm frequency setting for the `setClockAlarm()` method. If the DS1921 Thermocron alarm is enabled and is not alarming, it will alarm the next time the Real-Time Clock's 'second', 'minute', and 'hour' values are equal to the Alarm Clock's 'second', 'minute', and 'hour' values.
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`

### ONCE_PER_WEEK

    public static final byte ONCE_PER_WEEK

  Alarm frequency setting for the `setClockAlarm()` method. If the DS1921 Thermocron alarm is enabled and is not alarming, it will alarm the next time the Real-Time Clock's 'second', 'minute', 'hour', and 'day of week' values are equal to the Alarm Clock's 'second', 'minute', 'hour', and 'day of week' values
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`

### TEMPERATURE_LOW_ALARM

    public static final byte TEMPERATURE_LOW_ALARM

  Low temperature alarm value for the methods `getAlarmStatus()`, `getAlarmHistory()`, and `setTemperatureAlarm()`.
  See Also:
    `getAlarmStatus(byte,byte[])`, `getAlarmHistory(byte)`, `setTemperatureAlarm(int,double,byte[])`

### TEMPERATURE_HIGH_ALARM

    public static final byte TEMPERATURE_HIGH_ALARM

  High temperature alarm value for the methods `getAlarmStatus()`, `getAlarmHistory()`, and `setTemperatureAlarm()`.
  See Also:
    `getAlarmStatus(byte,byte[])`, `getAlarmHistory(byte)`, `setTemperatureAlarm(int,double,byte[])`

### TIMER_ALARM

    public static final byte TIMER_ALARM

  Clock alarm value for the methods `getAlarmStatus()` and `isClockAlarming()`.
  See Also:
    `getAlarmStatus(byte,byte[])`, `isClockAlarming(byte[])`

### 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 occurred.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### 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 temperature log memory becomes full.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### MEMORY_CLEAR_ENABLE_FLAG

    public static final byte MEMORY_CLEAR_ENABLE_FLAG

  CONTROL REGISTER FLAG: Must be enabled to allow a clear memory function. Must be set immediately before the command is issued.
  See Also:
    `clearMemory()`, `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`, `setFlag(int,byte,boolean)`, `setFlag(int,byte,boolean,byte[])`

### TIMER_ALARM_FLAG

    public static final byte TIMER_ALARM_FLAG

  STATUS REGISTER FLAG: Will read back true when a clock alarm has occurred.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### 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
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### MEMORY_CLEARED_FLAG

    public static final byte MEMORY_CLEARED_FLAG

  STATUS REGISTER FLAG: Will read back true if the memory has been cleared.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

### 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.
  See Also:
    `getFlag(int,byte,byte[])`, `getFlag(int,byte)`

Constructor Detail

### OneWireContainer21

    public OneWireContainer21()

  Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton. Note that the method `setupContainer(DSPortAdapter,byte[])` must be called to set the correct `DSPortAdapter` device address.
  See Also:
    `setupContainer(DSPortAdapter,byte[])`, `OneWireContainer21(DSPortAdapter,byte[])`, `OneWireContainer21(DSPortAdapter,long)`, `OneWireContainer21(DSPortAdapter,String)`

### OneWireContainer21

    public OneWireContainer21(DSPortAdapter sourceAdapter,
                              byte[] newAddress)

  Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this DS1921
  See Also:
    `OneWireContainer21()`, `OneWireContainer21(DSPortAdapter,long)`, `OneWireContainer21(DSPortAdapter,String)`

### OneWireContainer21

    public OneWireContainer21(DSPortAdapter sourceAdapter,
                              long newAddress)

  Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this DS1921
  See Also:
    `OneWireContainer21()`, `OneWireContainer21(DSPortAdapter,byte[])`, `OneWireContainer21(DSPortAdapter,String)`

### OneWireContainer21

    public OneWireContainer21(DSPortAdapter sourceAdapter,
                              String newAddress)

  Creates a new `OneWireContainer` for communication with a DS1921 Thermocron iButton.
  Parameters:
    `sourceAdapter` - adapter object required to communicate with this iButton
    `newAddress` - address of this DS1921
  See Also:
    `OneWireContainer21()`, `OneWireContainer21(DSPortAdapter,long)`, `OneWireContainer21(DSPortAdapter,String)`

Method Detail

### getMemoryBanks

    public Enumeration getMemoryBanks()

  Gets 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

### getMaxSpeed

    public int getMaxSpeed()

  Returns the maximum speed this iButton device can communicate at.
  Overrides:
    `getMaxSpeed` in class `OneWireContainer`
  Returns:
    maximum speed
  See Also:
    `DSPortAdapter.setSpeed(int)`

### getName

    public String getName()

  Gets the Dallas Semiconductor part number of the iButton or 1-Wire Device as a `java.lang.String`. For example "DS1992".
  Overrides:
    `getName` in class `OneWireContainer`
  Returns:
    iButton or 1-Wire device name

### getAlternateNames

    public String getAlternateNames()

  Retrieves the alternate Dallas Semiconductor part numbers or names. A 'family' of MicroLAN 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:
    the alternate names for this iButton or 1-Wire device

### getDescription

    public String getDescription()

  Gets a short description of the function of this iButton or 1-Wire Device type.
  Overrides:
    `getDescription` in class `OneWireContainer`
  Returns:
    device description

### setSpeedCheck

    public void setSpeedCheck(boolean doSpeedCheck)

  Directs the container to avoid the calls to doSpeed() in methods that communicate with the Thermocron. To ensure that all parts can talk to the 1-Wire bus at their desired speed, each method contains a call to `doSpeed()`. However, this is an expensive operation. If a user manages the bus speed in an application, call this method with `doSpeedCheck` as `false`. The default behavior is to call `doSpeed()`.
  Parameters:
    `doSpeedCheck` - `true` for `doSpeed()` to be called before every 1-Wire bus access, `false` to skip this expensive call
  See Also:
    `OneWireContainer.doSpeed()`

### decodeTemperature

    public double decodeTemperature(byte tempByte)

  Converts a temperature from the DS1921 `byte` encoded format to degrees Celsius. The raw temperature readings are unsigned `byte` values, representing a 2.0 degree accuracy.
  Parameters:
    `tempByte` - raw DS1921 temperature reading
  Returns:
    temperature in degrees Celsius
  See Also:
    `encodeTemperature(double)`

### encodeTemperature

    public byte encodeTemperature(double temperature)

  Converts a temperature in degrees Celsius to a `byte` formatted for the DS1921.
  Parameters:
    `temperature` - the temperature (Celsius) to convert
  Returns:
    the temperature in raw DS1921 format
  See Also:
    `decodeTemperature(byte)`

### writeByte

    public void writeByte(int memAddr,
                          byte source)
                   throws OneWireIOException,
                          OneWireException

  Writes 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. Also note that the preferred way to write a page is through the `MemoryBank` objects returned from the `getMemoryBanks()` method.
  Parameters:
    `memAddr` - the address for writing (in the range of 0x200-0x21F)
    `source` - the data `byte` to write
  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
  See Also:
    `readByte(int)`, `getMemoryBanks()`

### readByte

    public byte readByte(int memAddr)
                  throws OneWireIOException,
                         OneWireException

  Reads a single byte from the DS1921. Note that the preferred manner of reading from the DS1921 Thermocron is through the `readDevice()` method or through the `MemoryBank` objects returned in the `getMemoryBanks()` method.
  Parameters:
    `memAddr` - the address to read from (in the range of 0x200-0x21F)
  Returns:
    the data byte read
  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
  See Also:
    `writeByte(int,byte)`, `readDevice()`, `getMemoryBanks()`

### getFlag

    public boolean getFlag(int register,
                           byte bitMask)
                    throws OneWireIOException,
                           OneWireException

  Gets the status of the specified flag from the specified register. 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.

  The DS1921 Thermocron has two sets of flags. One set belongs to the control register. When reading from the control register, valid values for `bitMask` are:

  - `TIMER_ALARM_SEARCH_FLAG`
  - `TEMP_HIGH_SEARCH_FLAG`
  - `TEMP_LOW_SEARCH_FLAG`
  - `ROLLOVER_ENABLE_FLAG`
  - `MISSION_ENABLE_FLAG`
  - `MEMORY_CLEAR_ENABLE_FLAG`
  - `OSCILLATOR_ENABLE_FLAG`

  When reading from the status register, valid values for `bitMask` are:

  - `TIMER_ALARM_FLAG`
  - `TEMPERATURE_HIGH_FLAG`
  - `TEMPERATURE_LOW_FLAG`
  - `SAMPLE_IN_PROGRESS_FLAG`
  - `MISSION_IN_PROGRESS_FLAG`
  - `MEMORY_CLEARED_FLAG`
  - `TEMP_CORE_BUSY_FLAG`
  Parameters:
    `register` - address of register containing the flag (valid values are `CONTROL_REGISTER` and `STATUS_REGISTER`)
    `bitMask` - the flag to read (see above for available options)
  Returns:
    the status of the flag, where `true` signifies a "1" and `false` signifies a "0"
  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
  See Also:
    `getFlag(int,byte,byte[])`, `readDevice()`, `setFlag(int,byte,boolean)`, `TIMER_ALARM_SEARCH_FLAG`, `TEMP_HIGH_SEARCH_FLAG`, `TEMP_LOW_SEARCH_FLAG`, `ROLLOVER_ENABLE_FLAG`, `MISSION_ENABLE_FLAG`, `MEMORY_CLEAR_ENABLE_FLAG`, `OSCILLATOR_ENABLE_FLAG`, `TIMER_ALARM_FLAG`, `TEMPERATURE_HIGH_FLAG`, `TEMPERATURE_LOW_FLAG`, `SAMPLE_IN_PROGRESS_FLAG`, `MISSION_IN_PROGRESS_FLAG`, `MEMORY_CLEARED_FLAG`, `TEMP_CORE_BUSY_FLAG`

### getFlag

    public boolean getFlag(int register,
                           byte bitMask,
                           byte[] state)

  Gets the status of the specified flag from the specified register. This method is the preferred manner of reading the control and status flags.

  For more information on valid values for the `bitMask` parameter, see the `getFlag(int,byte)` method.

  Parameters:
    `register` - address of register containing the flag (valid values are `CONTROL_REGISTER` and `STATUS_REGISTER`)
    `bitMask` - the flag to read (see `getFlag(int,byte)` for available options)
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the status of the flag, where `true` signifies a "1" and `false` signifies a "0"
  See Also:
    `getFlag(int,byte)`, `readDevice()`, `setFlag(int,byte,boolean,byte[])`

### setFlag

    public void setFlag(int register,
                        byte bitMask,
                        boolean flagValue)
                 throws OneWireIOException,
                        OneWireException

  Sets the status of the specified flag 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). This method actually communicates with the DS1921 Thermocron. To improve performance if you intend to make multiple calls to this method, first call `readDevice()` and use the `setFlag(int,byte,boolean,byte[])` method instead.

  For more information on valid values for the `bitMask` parameter, see the `getFlag(int,byte)` method.

  Parameters:
    `register` - address of register containing the flag (valid values are `CONTROL_REGISTER` and `STATUS_REGISTER`)
    `bitMask` - the flag to read (see `getFlag(int,byte)` for available options)
    `flagValue` - new value for the flag (`true` is logic "1")
  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'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter
  See Also:
    `getFlag(int,byte)`, `getFlag(int,byte,byte[])`, `setFlag(int,byte,boolean,byte[])`, `readDevice()`

### setFlag

    public void setFlag(int register,
                        byte bitMask,
                        boolean flagValue,
                        byte[] state)

  Sets the status of the specified flag 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). This method is the preferred manner of setting the DS1921 status and control flags. The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`.

  For more information on valid values for the `bitMask` parameter, see the `getFlag(int,byte)` method.

  Parameters:
    `register` - address of register containing the flag (valid values are `CONTROL_REGISTER` and `STATUS_REGISTER`)
    `bitMask` - the flag to read (see `getFlag(int,byte)` for available options)
    `flagValue` - new value for the flag (`true` is logic "1")
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `getFlag(int,byte)`, `getFlag(int,byte,byte[])`, `setFlag(int,byte,boolean)`, `readDevice()`, `writeDevice(byte[])`

### enableMission

    public void enableMission(int sampleRate)
                       throws OneWireIOException,
                              OneWireException

  Begins this DS1921's mission. If a mission is already in progress, this will throw a `OneWireIOException`. The mission will wait the number of minutes specified by the mission start delay (use `setMissionStartDelay()`) before beginning.

  Note that this method actually communicates with the DS1921 Thermocron. No call to `writeDevice()` is required to finalize mission enabling. However, some flags (such as the mission start delay) may need to be set with a call to `writeDevice()` before the mission is enabled. See the usage section above for an example of starting a mission.

  Parameters:
    `sampleRate` - the number of minutes to wait in between temperature samples (valid values are 1 to 255)
  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'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter
  See Also:
    `disableMission()`, `setMissionStartDelay(int,byte[])`, `writeDevice(byte[])`

### disableMission

    public void disableMission()
                        throws OneWireIOException,
                               OneWireException

  Ends this DS1921's running mission. Note that this method actually communicates with the DS1921 Thermocron. No additional call to `writeDevice(byte[])` is required.
  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
  See Also:
    `enableMission(int)`

### setMissionStartDelay

    public void setMissionStartDelay(int missionStartDelay,
                                     byte[] state)

  Sets the time to wait before starting the mission. The DS1921 will sleep `missionStartDelay` minutes after the mission is enabled with `enableMission(int)`, then begin taking samples. Only the least significant 16 bits of `missionStartDelay` are relevant.

  The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`.

  Parameters:
    `missionStartDelay` - the time in minutes to delay the first sample
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `readDevice()`, `writeDevice(byte[])`, `enableMission(int)`

### clearMemory

    public void clearMemory()
                     throws OneWireIOException,
                            OneWireException

  Clears the memory of any previous mission. The memory must be cleared before setting up a new mission. If a mission is in progress a `OneWireIOException` is thrown.

  The Clear Memory command clears the Thermocron's memory at address 220h and higher. It also clears the sample rate, mission start delay, mission time stamp, and mission samples counter.

  Note that this method actually communicates with the DS1921 Thermocron. No call to `writeDevice(byte[])` is necessary to finalize this activity.

  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'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter
  See Also:
    `enableMission(int)`, `writeDevice(byte[])`

### getAlarmTime

    public Calendar getAlarmTime(byte[] state)

  Gets the clock alarm time settings. The alarm settings used by the Thermocron are Hour, Minute, Second, and Day of Week. Note that not all values in the returned `java.util.Calendar` object are valid. Only four values in the `Calendar` should be used. The field names for these values are:

            Calendar.DAY_OF_MONTH
            Calendar.HOUR
            Calendar.MINUTE
            Calendar.SECOND

  To access these fields, use the method `Calendar.get(Calendar.HOUR)`. The hour is reported in 24-hour format. Use the method `getClockAlarm(byte[])` to find out the next time an alarm event will occur.

  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the alarm clock time and day of the week
  See Also:
    `setClockAlarm(int,int,int,int,int,byte[])`, `readDevice()`, `getClockAlarm(byte[])`

### setClockAlarm

    public void setClockAlarm(int hours,
                              int minutes,
                              int seconds,
                              int day,
                              int alarmFrequency,
                              byte[] state)

  Set the DS1921's alarm clock. 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.

  Valid values for `alarmFrequency` are:

          ONCE_PER_SECOND
          ONCE_PER_MINUTE
          ONCE_PER_HOUR
          ONCE_PER_DAY
          ONCE_PER_WEEK

  The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`.

  Parameters:
    `hours` - the hour of the day (0-23)
    `minutes` - the minute setting (0-59)
    `seconds` - the second setting (0-59)
    `day` - the day of the week (1-7, 1==Sunday)
    `alarmFrequency` - frequency that the alarm should occur at
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `readDevice()`, `writeDevice(byte[])`, `getClockAlarm(byte[])`, `ONCE_PER_SECOND`, `ONCE_PER_MINUTE`, `ONCE_PER_HOUR`, `ONCE_PER_DAY`, `ONCE_PER_WEEK`

### getSampleRate

    public int getSampleRate(byte[] state)

  Returns the rate at which the DS1921 takes temperature samples. This rate is set when the mission is enabled (in the method `enableMission(int)`.
  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the time, in minutes, between temperature readings
  See Also:
    `enableMission(int)`, `readDevice()`

### getMissionSamplesCounter

    public int getMissionSamplesCounter(byte[] state)

  Determines the number of samples taken on this mission. Only the last 2048 samples appear in the Thermocron's log, though all readings from the current mission are logged in the histogram.
  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the number of samples taken in the current mission
  See Also:
    `readDevice()`, `getDeviceSamplesCounter(byte[])`

### getDeviceSamplesCounter

    public int getDeviceSamplesCounter(byte[] state)

  Determines the total number of samples taken by this Thermocron. This includes samples taken in past missions. It also includes 'forced' readings. A 'forced' reading refers to a reading taken when the Thermocron does not have a running mission and is instructed to read the current temperature.

  The DS1921 Thermocron is tested to last for 1 million temperature readings.

  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the total number of measurements taken by this Thermocron
  See Also:
    `readDevice()`, `getMissionSamplesCounter(byte[])`

### getMissionTimeStamp

    public Calendar getMissionTimeStamp(byte[] state)

  Returns the date and time that the last mission was started. The values in the `java.util.Calendar` object are fully specified. In other words, the year, month, date, hour, minute, and second are all valid in the returned object.
  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the date and time that the last mission was started
  See Also:
    `readDevice()`

### getFirstLogOffset

    public long getFirstLogOffset(byte[] state)

  Helps 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. The returned value can be added to the underlying millisecond value of `getMissionTimeStamp()` to determine the time that the 'first' log entry actually occurred.

            //ds1921 is a OneWireContainer21
            byte[] state = ds1921.readDevice();
            Calendar c = ds1921.getMissionTimeStamp(state);
            //find the time for the first log entry
            long first_entry = c.getTime().getTime();
            first_entry += ds1921.getFirstLogOffset(state);
            . . .

  Be cautious of 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 `java.lang.String` to handle Daylight Savings Time, resulting in offset by 1 hour problems.

  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    milliseconds between the beginning of the mission and the time of the first log entry reported from `getTemperatureLog()`
  See Also:
    `readDevice()`, `getMissionTimeStamp(byte[])`, `getTemperatureLog(byte[])`

### getTemperatureLog

    public byte[] getTemperatureLog(byte[] state)
                             throws OneWireIOException,
                                    OneWireException

  Returns the log of temperature measurements. Each `byte` in the returned array is an independent sample. Use the method `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. The temperature log can be read while a mission is still in progress.

  Note that although this method takes the device state as a parameter, this method still must communicate directly with the Thermocron to read the log.

  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the DS1921's encoded temperature log
  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
  See Also:
    `decodeTemperature(byte)`, `readDevice()`, `getFirstLogOffset(byte[])`, `getMissionTimeStamp(byte[])`

### getTemperatureHistogram

    public int[] getTemperatureHistogram()
                                  throws OneWireIOException,
                                         OneWireException

  Returns an array of 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 0 will hold the counter for temperatures ranging from -40 to -38.5 (Celsius) and lower. Bin 1 is associated with the range of -38 to 36.5 and so on. Bin 62 is the final bin, and it holds temperature values of 84 degrees and higher. The temperature histogram can be read while a mission is still in progress.

  Returns:
    the 63 temperature counters
  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

### getAlarmStatus

    public boolean getAlarmStatus(byte alarmBit,
                                  byte[] state)

  Returns `true` if the specified alarm has been triggered. Valid values for the `alarmBit` parameter are:`

           TEMPERATURE_LOW_ALARM
           TEMPERATURE_HIGH_ALARM
           TIMER_ALARM

  `
  Parameters:
    `alarmBit` - the alarm to check
    `state` - current state of the device returned from `readDevice()`
  Returns:
    if the specified alarm has been triggered
  See Also:
    `TEMPERATURE_LOW_ALARM`, `TEMPERATURE_HIGH_ALARM`, `TIMER_ALARM`, `readDevice()`, `getAlarmHistory(byte)`

### getAlarmHistory

    public byte[] getAlarmHistory(byte alarmBit)
                           throws OneWireIOException,
                                  OneWireException

  Returns an array containing the alarm log. The DS1921 contains two separate alarm logs. One for the high temperature alarm and one for the low temperature alarm. Each log can store up to 12 log entries and each log entry will record up to 255 consecutive alarm violations.

  The returned array is not altered from its representation on the DS1921 Thermocron. It is therefore up to the caller to interpret the data. The number of logs in this alarm history is equal to the array length divided by 4, since each entry is 4 bytes. The first three bytes are the number of samples into the mission that the alarm occurred. The fourth byte is the number of consecutive samples that violated the alarm. To extract the starting offset and number of violations from the array:

  `

             byte[] data = ds1921.getAlarmHistory(OneWireContainer21.TEMPERATURE_HIGH_ALARM);
             int start_offset;
             int violation_count;
             . . .
             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.
             }

  `

  Acceptable values for the `alarmBit` parameter are:

           TEMPERATURE_LOW_ALARM
           TEMPERATURE_HIGH_ALARM

  Parameters:
    `alarmBit` - the alarm log to get
  Returns:
    the time/duration of the alarm (see above for the structure of the array)
  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
  See Also:
    `getAlarmStatus(byte,byte[])`

### 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

### hasTemperatureAlarms

    public boolean hasTemperatureAlarms()

  Checks to see if this temperature measuring device has high/low trip alarms.
  Specified by:
    `hasTemperatureAlarms` in interface `TemperatureContainer`
  Returns:
    `true` if this `TemperatureContainer` has high/low trip alarms
  See Also:
    `getTemperatureAlarm(int, byte[])`, `setTemperatureAlarm(int, double, byte[])`

### hasSelectableTemperatureResolution

    public boolean hasSelectableTemperatureResolution()

  Checks to see if this device has selectable temperature resolution.
  Specified by:
    `hasSelectableTemperatureResolution` in interface `TemperatureContainer`
  Returns:
    `true` if this `TemperatureContainer` has selectable temperature resolution
  See Also:
    `getTemperatureResolution(byte[])`, `getTemperatureResolutions()`, `setTemperatureResolution(double, byte[])`

### getTemperatureResolutions

    public double[] getTemperatureResolutions()

  Get an array of available temperature resolutions in Celsius.
  Specified by:
    `getTemperatureResolutions` in interface `TemperatureContainer`
  Returns:
    byte array of available temperature resolutions in Celsius with minimum resolution as the first element and maximum resolution as the last element
  See Also:
    `hasSelectableTemperatureResolution()`, `getTemperatureResolution(byte[])`, `setTemperatureResolution(double, byte[])`

### getTemperatureAlarmResolution

    public double getTemperatureAlarmResolution()

  Gets the temperature alarm resolution in Celsius.
  Specified by:
    `getTemperatureAlarmResolution` in interface `TemperatureContainer`
  Returns:
    temperature alarm resolution in Celsius for this 1-wire device
  See Also:
    `hasTemperatureAlarms()`, `getTemperatureAlarm(int, byte[])`, `setTemperatureAlarm(int, double, byte[])`

### getMaxTemperature

    public double getMaxTemperature()

  Gets the maximum temperature in Celsius.
  Specified by:
    `getMaxTemperature` in interface `TemperatureContainer`
  Returns:
    maximum temperature in Celsius for this 1-wire device
  See Also:
    `getMinTemperature()`

### getMinTemperature

    public double getMinTemperature()

  Gets the minimum temperature in Celsius.
  Specified by:
    `getMinTemperature` in interface `TemperatureContainer`
  Returns:
    minimum temperature in Celsius for this 1-wire device
  See Also:
    `getMaxTemperature()`

### doTemperatureConvert

    public void doTemperatureConvert(byte[] state)
                              throws OneWireIOException,
                                     OneWireException

  Performs a temperature conversion. Use the `state` information to calculate the conversion time.
  Specified by:
    `doTemperatureConvert` in interface `TemperatureContainer`
  Parameters:
    `state` - byte array with device state information
  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'. In the case of the DS1921 Thermocron, this could also be due to a currently running mission.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter

### getTemperature

    public double getTemperature(byte[] state)

  Gets the temperature value in Celsius from the `state` data retrieved from the `readDevice()` method.
  Specified by:
    `getTemperature` in interface `TemperatureContainer`
  Parameters:
    `state` - byte array with device state information
  Returns:
    temperature in Celsius from the last `doTemperatureConvert()`

### getTemperatureAlarm

    public double getTemperatureAlarm(int alarmType,
                                      byte[] state)

  Gets the specified temperature alarm value in Celsius from the `state` data retrieved from the `readDevice()` method.
  Specified by:
    `getTemperatureAlarm` in interface `TemperatureContainer`
  Parameters:
    `alarmType` - valid value: `ALARM_HIGH` or `ALARM_LOW`
    `state` - byte array with device state information
  Returns:
    temperature alarm trip values in Celsius for this 1-wire device
  See Also:
    `hasTemperatureAlarms()`, `setTemperatureAlarm(int, double, byte[])`

### getTemperatureResolution

    public double getTemperatureResolution(byte[] state)

  Gets the current temperature resolution in Celsius from the `state` data retrieved from the `readDevice()` method.
  Specified by:
    `getTemperatureResolution` in interface `TemperatureContainer`
  Parameters:
    `state` - byte array with device state information
  Returns:
    temperature resolution in Celsius for this 1-wire device
  See Also:
    `hasSelectableTemperatureResolution()`, `getTemperatureResolutions()`, `setTemperatureResolution(double, byte[])`

### setTemperatureAlarm

    public void setTemperatureAlarm(int alarmType,
                                    double alarmValue,
                                    byte[] state)

  Sets the temperature alarm value in Celsius 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` - valid value: `ALARM_HIGH` or `ALARM_LOW`
    `alarmValue` - alarm trip value in Celsius
    `state` - byte array with device state information
  See Also:
    `hasTemperatureAlarms()`, `getTemperatureAlarm(int, byte[])`

### setTemperatureResolution

    public void setTemperatureResolution(double resolution,
                                         byte[] state)
                                  throws OneWireException

  Sets the current temperature resolution in Celsius 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` - temperature resolution in Celsius
    `state` - byte array with device state information
  Throws:
    `OneWireException` - if the device does not support selectable temperature resolution
  See Also:
    `hasSelectableTemperatureResolution()`, `getTemperatureResolution(byte[])`, `getTemperatureResolutions()`

### hasClockAlarm

    public boolean hasClockAlarm()

  Checks 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()

  Checks 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()

  Gets the clock resolution in milliseconds
  Specified by:
    `getClockResolution` in interface `ClockContainer`
  Returns:
    the clock resolution in milliseconds

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

### getClockAlarm

    public long getClockAlarm(byte[] state)

  Extracts the clock alarm value for the Real-Time clock. In the case of the DS1921 Thermocron, this is the time that the next periodic alarm event will occur.
  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
  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()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`.
  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:
    `OneWireSensor.writeDevice(byte[])`, `getClock(byte[])`

### setClockAlarm

    public void setClockAlarm(long time,
                              byte[] state)
                       throws OneWireException

  Sets the clock alarm. The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`. 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[])`

### setClockRunEnable

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

  Enables or disables the oscillator, turning the clock 'on' and 'off'. The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`. 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[])`

### setClockAlarmEnable

    public void setClockAlarmEnable(boolean alarmEnable,
                                    byte[] state)

  Enables or disables the clock alarm. The method `writeDevice()` must be called to finalize changes to the device. Note that multiple 'set' methods can be called before one call to `writeDevice()`. 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()`
  See Also:
    `OneWireSensor.writeDevice(byte[])`, `hasClockAlarm()`, `isClockAlarmEnabled(byte[])`, `getClockAlarm(byte[])`, `setClockAlarm(long,byte[])`, `isClockAlarming(byte[])`

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