Dallas Semiconductor 1-Wire API 1.00 Alpha: Interface TemperatureContainer

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

All Superinterfaces:
  OneWireSensor

All Known Implementing Classes:
  OneWireContainer21, OneWireContainer10, OneWireContainer30, OneWireContainer22, OneWireContainer26, OneWireContainer28

public interface TemperatureContainer
extends OneWireSensor

1-Wire temperature interface class for basic temperature measuring operations. This class should be implemented for each temperature type 1-Wire device.

The TemperatureContainer methods can be organized into the following categories:

- Information
  - `getMaxTemperature`
  - `getMinTemperature`
  - `getTemperature`
  - `getTemperatureAlarm`
  - `getTemperatureAlarmResolution`
  - `getTemperatureResolution`
  - `getTemperatureResolutions`
  - `hasSelectableTemperatureResolution`
  - `hasTemperatureAlarms`
- Options
  - `doTemperatureConvert`
  - `setTemperatureAlarm`
  - `setTemperatureResolution`
- I/O
  - `readDevice`
  - `writeDevice`

### Usage

  #### Example 1

  Display some features of TemperatureContainer instance '`tc`':

         // Read High and Low Alarms
         if (!tc.hasTemperatureAlarms())
            System.out.println("Temperature alarms not supported");
         else
         {
            byte[] state     = tc.readDevice();
            double alarmLow  = tc.getTemperatureAlarm(TemperatureContainer.ALARM_LOW, state);
            double alarmHigh = tc.getTemperatureAlarm(TemperatureContainer.ALARM_HIGH, state);
            System.out.println("Alarm: High = " + alarmHigh + ", Low = " + alarmLow);
         }             }

  #### Example 2

  Gets temperature reading from a TemperatureContainer instance '`tc`':

         double lastTemperature;

         // get the current resolution and other settings of the device (done only once)
         byte[] state = tc.readDevice();

         do // loop to read the temp
         {
            // perform a temperature conversion
            tc.doTemperatureConvert(state);

            // read the result of the conversion
            state = tc.readDevice();

            // extract the result out of state
            lastTemperature = tc.getTemperature(state);
            ...

         }while (!done);

  The reason the conversion and the reading are separated is that one may want to do a conversion without reading the result. One could take advantage of the alarm features of a device by setting a threshold and doing conversions until the device is alarming. For example:

         // get the current resolution of the device
         byte [] state = tc.readDevice();

         // set the trips
         tc.setTemperatureAlarm(TemperatureContainer.ALARM_HIGH, 50, state);
         tc.setTemperatureAlarm(TemperatureContainer.ALARM_LOW, 20, state);
         tc.writeDevice(state);

         do // loop on conversions until an alarm occurs
         {
            tc.doTemperatureConvert(state);
         } while (!tc.isAlarming());

  #### Example 3

  Sets the temperature resolution of a TemperatureContainer instance '`tc`':

         byte[] state = tc.readDevice();
         if (tc.hasSelectableTemperatureResolution())
         {
            double[] resolution = tc.getTemperatureResolutions();
            tc.setTemperatureResolution(resolution [resolution.length - 1], state);
            tc.writeDevice(state);
         }

Version:
  0.00, 27 August 2000
See Also:
  `OneWireContainer10`, `OneWireContainer21`, `OneWireContainer26`, `OneWireContainer28`, `OneWireContainer30`

Field Summary
`static int` | `ALARM_HIGH` high temperature alarm
`static int` | `ALARM_LOW` low temperature alarm

Method Summary
`void` | `doTemperatureConvert(byte[] state)` Performs a temperature conversion.
`double` | `getMaxTemperature()` Gets the maximum temperature in Celsius.
`double` | `getMinTemperature()` Gets the minimum temperature in Celsius.
`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.
`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` | `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.
`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.

Methods inherited from interface com.dalsemi.onewire.container.OneWireSensor
`readDevice, writeDevice`

Field Detail

### ALARM_HIGH

    public static final int ALARM_HIGH

  high temperature alarm

### ALARM_LOW

    public static final int ALARM_LOW

  low temperature alarm

Method Detail

### hasTemperatureAlarms

    public boolean hasTemperatureAlarms()

  Checks to see if this temperature measuring device has high/low trip alarms.
  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.
  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.
  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()
                                         throws OneWireException

  Gets the temperature alarm resolution in Celsius.
  Returns:
    temperature alarm resolution in Celsius for this 1-wire device
  Throws:
    `OneWireException` - Device does not support temperature alarms
  See Also:
    `hasTemperatureAlarms()`, `getTemperatureAlarm(int, byte[])`, `setTemperatureAlarm(int, double, byte[])`

### getMaxTemperature

    public double getMaxTemperature()

  Gets the maximum temperature in Celsius.
  Returns:
    maximum temperature in Celsius for this 1-wire device

### getMinTemperature

    public double getMinTemperature()

  Gets the minimum temperature in Celsius.
  Returns:
    minimum temperature in Celsius for this 1-wire device

### doTemperatureConvert

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

  Performs a temperature conversion.
  Parameters:
    `state` - byte array with device state information
  Throws:
    `OneWireException` - Part could not be found [ fatal ]
    `OneWireIOException` - Data wasn't transferred properly [ recoverable ]

### getTemperature

    public double getTemperature(byte[] state)
                          throws OneWireIOException

  Gets the temperature value in Celsius from the `state` data retrieved from the `readDevice()` method.
  Parameters:
    `state` - byte array with device state information
  Returns:
    temperature in Celsius from the last `doTemperatureConvert()`
  Throws:
    `OneWireIOException` - In the case of invalid temperature data

### getTemperatureAlarm

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

  Gets the specified temperature alarm value in Celsius from the `state` data retrieved from the `readDevice()` method.
  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
  Throws:
    `OneWireException` - Device does not support temperature alarms
  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.
  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)
                             throws OneWireException

  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.
  Parameters:
    `alarmType` - valid value: `ALARM_HIGH` or `ALARM_LOW`
    `alarmValue` - alarm trip value in Celsius
    `state` - byte array with device state information
  Throws:
    `OneWireException` - Device does not support temperature alarms
  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.
  Parameters:
    `resolution` - temperature resolution in Celsius
    `state` - byte array with device state information
  Throws:
    `OneWireException` - Device does not support selectable temperature resolution
  See Also:
    `hasSelectableTemperatureResolution()`, `getTemperatureResolution(byte[])`, `getTemperatureResolutions()`

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