Dallas Semiconductor 1-Wire API 1.00 Alpha: Interface ADContainer

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 ADContainer

All Superinterfaces:
  OneWireSensor

All Known Implementing Classes:
  OneWireContainer30, OneWireContainer20, OneWireContainer26

public interface ADContainer
extends OneWireSensor

Interface class for 1-Wire® devices that perform analog measuring operations. This class should be implemented for each A/D type 1-Wire device.

### Features

- Allows multi-channel voltage readings
- Supports A/D Alarm enabling on devices with A/D Alarms
- Supports selectable A/D ranges on devices with selectable ranges
- Supports selectable A/D resolutions on devices with selectable resolutions

### Usage

`ADContainer` extends `OneWireSensor`, so the general usage model applies to any `ADContainer`:

1. readDevice()
2. perform operations on the `ADContainer`
3. writeDevice(byte[])

Consider this interaction with an `ADContainer` that reads from all of its A/D channels, then tries to set its high alarm on its first channel (channel 0):

         //adcontainer is a com.dalsemi.onewire.container.ADContainer
         byte[] state = adcontainer.readDevice();
         double[] voltages = new double[adcontainer.getNumberADChannels()];
         for (int i=0; i < adcontainer.getNumberADChannels(); i++)
         {
              adcontainer.doADConvert(i, state);
              voltages[i] = adc.getADVoltage(i, state);
         }
         if (adcontainer.hasADAlarms())
         {
              double highalarm = adcontainer.getADAlarm(0, ADContainer.ALARM_HIGH, state);
              adcontainer.setADAlarm(0, ADContainer.ALARM_HIGH, highalarm + 1.0, state);
              adcontainer.writeDevice(state);
         }

Version:
  0.00, 27 August 2000
See Also:
  `OneWireSensor`, `ClockContainer`, `TemperatureContainer`, `PotentiometerContainer`, `SwitchContainer`

Field Summary
`static int` | `ALARM_HIGH` Indicates the high AD alarm.
`static int` | `ALARM_LOW` Indicates the low AD alarm.

Method Summary
`boolean` | `canADMultiChannelRead()` Checks to see if this A/D supports doing multiple voltage conversions at the same time.
`void` | `doADConvert(boolean[] doConvert, byte[] state)` Performs voltage conversion on one or more specified channels.
`void` | `doADConvert(int channel, byte[] state)` Performs a voltage conversion on one specified channel.
`double` | `getADAlarm(int channel, int alarmType, byte[] state)` Reads the value of the specified A/D alarm on the specified channel.
`boolean` | `getADAlarmEnable(int channel, int alarmType, byte[] state)` Checks to see if the specified alarm on the specified channel is enabled.
`double` | `getADRange(int channel, byte[] state)` Returns the currently selected range for the specified channel.
`double[]` | `getADRanges(int channel)` Gets an array of available ranges for the specified A/D channel.
`double` | `getADResolution(int channel, byte[] state)` Returns the currently selected resolution for the specified channel.
`double[]` | `getADResolutions(int channel, double range)` Gets an array of available resolutions based on the specified range on the specified A/D channel.
`double[]` | `getADVoltage(byte[] state)` Reads the value of the voltages after a `doADConvert(boolean[],byte[])` method call.
`double` | `getADVoltage(int channel, byte[] state)` Reads the value of the voltages after a `doADConvert(int,byte[])` method call.
`int` | `getNumberADChannels()` Gets the number of channels supported by this A/D.
`boolean` | `hasADAlarmed(int channel, int alarmType, byte[] state)` Checks the state of the specified alarm on the specified channel.
`boolean` | `hasADAlarms()` Checks to see if this A/D measuring device has high/low alarms.
`void` | `setADAlarm(int channel, int alarmType, double alarm, byte[] state)` Sets the voltage value of the specified alarm on the specified channel.
`void` | `setADAlarmEnable(int channel, int alarmType, boolean alarmEnable, byte[] state)` Enables or disables the specified alarm on the specified channel.
`void` | `setADRange(int channel, double range, byte[] state)` Sets the input range for the specified channel.
`void` | `setADResolution(int channel, double resolution, byte[] state)` Sets the conversion resolution value for the specified channel.

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

Field Detail

### ALARM_HIGH

    public static final int ALARM_HIGH

  Indicates the high AD alarm.

### ALARM_LOW

    public static final int ALARM_LOW

  Indicates the low AD alarm.

Method Detail

### getNumberADChannels

    public int getNumberADChannels()

  Gets the number of channels supported by this A/D. Channel specific methods will use a channel number specified by an integer from [0 to (`getNumberADChannels()` - 1)].
  Returns:
    the number of channels

### hasADAlarms

    public boolean hasADAlarms()

  Checks to see if this A/D measuring device has high/low alarms.
  Returns:
    true if this device has high/low trip alarms

### getADRanges

    public double[] getADRanges(int channel)

  Gets an array of available ranges for the specified A/D channel.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
  Returns:
    array indicating the available ranges starting from the largest range to the smallest range
  See Also:
    `getNumberADChannels()`

### getADResolutions

    public double[] getADResolutions(int channel,
                                     double range)

  Gets an array of available resolutions based on the specified range on the specified A/D channel.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `range` - A/D range setting from the `getADRanges(int)` method
  Returns:
    array indicating the available resolutions on this `channel` for this `range`
  See Also:
    `getNumberADChannels()`, `getADRanges(int)`

### canADMultiChannelRead

    public boolean canADMultiChannelRead()

  Checks to see if this A/D supports doing multiple voltage conversions at the same time.
  Returns:
    true if the device can do multi-channel voltage reads
  See Also:
    `doADConvert(boolean[],byte[])`

### doADConvert

    public void doADConvert(int channel,
                            byte[] state)
                     throws OneWireIOException,
                            OneWireException

  Performs a voltage conversion on one specified channel. Use the method `getADVoltage(int,byte[])` to read the result of this conversion, using the same `channel` argument as this method uses.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `state` - current state of the device returned from `readDevice()`
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no 1-Wire device present. 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'. This is usually a recoverable error.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter. This is usually a non-recoverable error.
  See Also:
    `OneWireSensor.readDevice()`, `getADVoltage(int,byte[])`

### doADConvert

    public void doADConvert(boolean[] doConvert,
                            byte[] state)
                     throws OneWireIOException,
                            OneWireException

  Performs voltage conversion on one or more specified channels. The method `getADVoltage(byte[])` can be used to read the result of the conversion(s). This A/D must support multi-channel read, reported by `canADMultiChannelRead()`, if more then 1 channel is specified.
  Parameters:
    `doConvert` - array of size `getNumberADChannels()` representing which channels should perform conversions
    `state` - current state of the device returned from `readDevice()`
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no 1-Wire device present. 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'. This is usually a recoverable error.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter. This is usually a non-recoverable error.
  See Also:
    `OneWireSensor.readDevice()`, `getADVoltage(byte[])`, `canADMultiChannelRead()`

### getADVoltage

    public double[] getADVoltage(byte[] state)
                          throws OneWireIOException,
                                 OneWireException

  Reads the value of the voltages after a `doADConvert(boolean[],byte[])` method call. This A/D device must support multi-channel reading, reported by `canADMultiChannelRead()`, if more than 1 channel conversion was attempted by `doADConvert()`.
  Parameters:
    `state` - current state of the device returned from `readDevice()`
  Returns:
    array with the voltage values for all channels
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no 1-Wire device present. 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'. This is usually a recoverable error.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter. This is usually a non-recoverable error.
  See Also:
    `doADConvert(boolean[],byte[])`

### getADVoltage

    public double getADVoltage(int channel,
                               byte[] state)
                        throws OneWireIOException,
                               OneWireException

  Reads the value of the voltages after a `doADConvert(int,byte[])` method call. If more than one channel has been read it is more efficient to use the `getADVoltage(byte[])` method that returns all channel voltage values.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the voltage value for the specified channel
  Throws:
    `OneWireIOException` - on a 1-Wire communication error such as no 1-Wire device present. 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'. This is usually a recoverable error.
    `OneWireException` - on a communication or setup error with the 1-Wire adapter. This is usually a non-recoverable error.
  See Also:
    `doADConvert(int,byte[])`, `getADVoltage(byte[])`

### getADAlarm

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

  Reads the value of the specified A/D alarm on the specified channel. Not all A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `alarmType` - the desired alarm, `ALARM_HIGH` or `ALARM_LOW`
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the alarm value in volts
  Throws:
    `OneWireException` - if this device does not have A/D alarms
  See Also:
    `OneWireSensor.readDevice()`, `hasADAlarms()`

### getADAlarmEnable

    public boolean getADAlarmEnable(int channel,
                                    int alarmType,
                                    byte[] state)
                             throws OneWireException

  Checks to see if the specified alarm on the specified channel is enabled. Not all A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `alarmType` - the desired alarm, `ALARM_HIGH` or `ALARM_LOW`
    `state` - current state of the device returned from `readDevice()`
  Returns:
    true if specified alarm is enabled
  Throws:
    `OneWireException` - if this device does not have A/D alarms
  See Also:
    `OneWireSensor.readDevice()`, `hasADAlarms()`

### hasADAlarmed

    public boolean hasADAlarmed(int channel,
                                int alarmType,
                                byte[] state)
                         throws OneWireException

  Checks the state of the specified alarm on the specified channel. Not all A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `alarmType` - the desired alarm, `ALARM_HIGH` or `ALARM_LOW`
    `state` - current state of the device returned from `readDevice()`
  Returns:
    true if specified alarm occurred
  Throws:
    `OneWireException` - if this device does not have A/D alarms
  See Also:
    `OneWireSensor.readDevice()`, `hasADAlarms()`, `getADAlarmEnable(int,int,byte[])`, `setADAlarmEnable(int,int,boolean,byte[])`

### getADResolution

    public double getADResolution(int channel,
                                  byte[] state)

  Returns the currently selected resolution for the specified channel. This device may not have selectable resolutions, though this method will return a valid value.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the current resolution of `channel` in volts
  See Also:
    `getADResolutions(int,double)`, `setADResolution(int,double,byte[])`

### getADRange

    public double getADRange(int channel,
                             byte[] state)

  Returns the currently selected range for the specified channel. This device may not have selectable ranges, though this method will return a valid value.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `state` - current state of the device returned from `readDevice()`
  Returns:
    the input voltage range
  See Also:
    `getADRanges(int)`, `setADRange(int,double,byte[])`

### setADAlarm

    public void setADAlarm(int channel,
                           int alarmType,
                           double alarm,
                           byte[] state)
                    throws OneWireException

  Sets the voltage value of the specified alarm on the specified channel. 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 A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `alarmType` - the desired alarm, `ALARM_HIGH` or `ALARM_LOW`
    `alarm` - new alarm value
    `state` - current state of the device returned from `readDevice()`
  Throws:
    `OneWireException` - if this device does not have A/D alarms
  See Also:
    `OneWireSensor.writeDevice(byte[])`, `hasADAlarms()`, `getADAlarm(int,int,byte[])`, `getADAlarmEnable(int,int,byte[])`, `setADAlarmEnable(int,int,boolean,byte[])`, `hasADAlarmed(int,int,byte[])`

### setADAlarmEnable

    public void setADAlarmEnable(int channel,
                                 int alarmType,
                                 boolean alarmEnable,
                                 byte[] state)
                          throws OneWireException

  Enables or disables the specified alarm on the specified channel. 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 A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `alarmType` - the desired alarm, `ALARM_HIGH` or `ALARM_LOW`
    `alarmEnable` - true to enable the alarm, false to disable
    `state` - current state of the device returned from `readDevice()`
  Throws:
    `OneWireException` - if this device does not have A/D alarms
  See Also:
    `OneWireSensor.writeDevice(byte[])`, `hasADAlarms()`, `getADAlarm(int,int,byte[])`, `setADAlarm(int,int,double,byte[])`, `getADAlarmEnable(int,int,byte[])`, `hasADAlarmed(int,int,byte[])`

### setADResolution

    public void setADResolution(int channel,
                                double resolution,
                                byte[] state)

  Sets the conversion resolution value for the specified channel. 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 A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `resolution` - one of the resolutions returned by `getADResolutions(int,double)`
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `getADResolutions(int,double)`, `getADResolution(int,byte[])`

### setADRange

    public void setADRange(int channel,
                           double range,
                           byte[] state)

  Sets the input range for the specified channel. 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 A/D devices have alarms. Check to see if this device has alarms first by calling the `hasADAlarms()` method.
  Parameters:
    `channel` - channel number in the range [0 to (`getNumberADChannels()` - 1)]
    `range` - one of the ranges returned by `getADRanges(int)`
    `state` - current state of the device returned from `readDevice()`
  See Also:
    `getADRanges(int)`, `getADRange(int,byte[])`

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