com.dalsemi.onewire.container
Class OneWireContainer20

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

All Implemented Interfaces:

ADContainer, OneWireSensor

public class OneWireContainer20

extends OneWireContainer

implements ADContainer

1-Wire® container that encapsulates the functionality of the 1-Wire family type 20 (hex), Dallas Semiconductor part number: DS2450, 1-Wire Quad A/D Converter.

Features

• Four high-impedance inputs
• Programmable input range (2.56V, 5.12V), resolution (1 to 16 bits) and alarm thresholds
• 5V, single supply operation
• Very low power, 2.5 mW active, 25 µW idle
• Unused analog inputs can serve as open drain digital outputs for closed-loop control
• Operating temperature range from -40°C to +85°C

Usage

Example device setup

      byte[] state = owd.readDevice();
      owd.setResolution(OneWireContainer20.CHANNELA, 16, state);
      owd.setResolution(OneWireContainer20.CHANNELB, 8, state);
      owd.setRange(OneWireContainer20.CHANNELA, 5.12, state);
      owd.setRange(OneWireContainer20.CHANNELB, 2.56, state);
      owd.writeDevice();
 

Example device read

      owd.doADConvert(OneWireContainer20.CHANNELA, state);
      owd.doADConvert(OneWireContainer20.CHANNELB, state);
      double chAVolatge = owd.getADVoltage(OneWireContainer20.CHANNELA, state);
      double chBVoltage = owd.getADVoltage(OneWireContainer20.CHANNELB, state);
 

Note

When converting analog voltages to digital, the user of the device must gaurantee that the voltage seen by the channel of the quad A/D does not exceed the selected input range of the device. If this happens, the device will default to reading 0 volts. There is NO way to know if the device is reading a higher than specified voltage or NO voltage.

DataSheet

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

Version:

0.00, 28 Aug 2000

Author:

JK,DSS

Field Summary

static int	ALARM_OFFSET Offset of ALARMS in array returned from read state
static int	BITMAP_OFFSET Offset of BITMAP in array returned from read state
static int	CHANNELA Channel A number
static int	CHANNELB Channel B number
static int	CHANNELC Channel C number
static int	CHANNELD Channel D number
static int	EXPOWER_OFFSET Offset of external power offset in array returned from read state
static int	NO_PRESET No preset value
static int	NUM_CHANNELS Number of channels
static int	PRESET_TO_ONES Preset value to ones
static int	PRESET_TO_ZEROS Preset value to zeros

Fields inherited from interface com.dalsemi.onewire.container.ADContainer

ALARM_HIGH, ALARM_LOW

Constructor Summary

OneWireContainer20()
Default constructor

OneWireContainer20(DSPortAdapter sourceAdapter, byte[] newAddress)
Creates a container with a provided adapter object and the address of the 1-Wire device.

OneWireContainer20(DSPortAdapter sourceAdapter, long newAddress)
Creates a container with a provided adapter object and the address of the 1-Wire device.

OneWireContainer20(DSPortAdapter sourceAdapter, String newAddress)
Creates a container with a provided adapter object and the address of the 1-Wire device.

Method Summary

boolean	canADMultiChannelRead() Queries 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 all specified channels.
void	doADConvert(boolean[] doConvert, int[] preset, byte[] state) Performs voltage conversion on all specified channels.
void	doADConvert(int channel, byte[] state) Performs voltage conversion on specified channel.
void	doADConvert(int channel, int preset, byte[] state) Performs voltage conversion on specified channel.
double	getADAlarm(int channel, int alarmType, byte[] state) Extracts the alarm voltage value of the specified channel from the provided state buffer.
boolean	getADAlarmEnable(int channel, int alarmType, byte[] state) Extracts the alarm enable value of the specified channel from the provided state buffer.
double	getADRange(int channel, byte[] state) Extracts the input voltage range of the specified channel from the provided state buffer.
double[]	getADRanges(int channel) Queries to get an array of available ranges for the specified A/D channel.
double	getADResolution(int channel, byte[] state) Extracts the conversion resolution of the specified channel from the provided state buffer expressed in volts.
double[]	getADResolutions(int channel, double range) Queries to get an array of available resolutions based on the specified range on the specified A/D channel.
double[]	getADVoltage(byte[] state) Reads the voltage values.
double	getADVoltage(int channel, byte[] state) Reads a channels voltage value.
String	getAlternateNames() Gets any other possible names for this 1-Wire device.
String	getDescription() Gets a brief description of the functionality of this 1-Wire device.
boolean	getDevicePOR(byte[] state) Detects if this device has seen a Power-On-Reset (POR).
int	getMaxSpeed() Gets the maximum speed this 1-Wire device can communicate at.
Enumeration	getMemoryBanks() Gets an enumeration of memory banks.
String	getName() Gets the name of this 1-Wire device.
int	getNumberADChannels() Queries to get the number of channels supported by this A/D.
boolean	getOutputState(int channel, byte[] state) Detects if the output is enabled for the specified channel from the provided register buffer.
boolean	hasADAlarmed(int channel, int alarmType, byte[] state) Checks the alarm event value of the specified channel from the provided state buffer.
boolean	hasADAlarms() Queries to see if this A/D measuring device has high/low alarms.
static double	interpretVoltage(long rawVoltage, double range) Converts a raw voltage long value for the DS2450 into a valid voltage.
boolean	isOutputEnabled(int channel, byte[] state) Detects if the output is enabled for the specified channel from the provided register buffer.
boolean	isPowerExternal(byte[] state) Extracts the state of the external power indicator from the provided register buffer.
byte[]	readDevice() Retrieves the entire A/D control/status and alarm pages.
void	setADAlarm(int channel, int alarmType, double alarm, byte[] state) Sets the alarm voltage value of the specified channel in the provided state buffer.
void	setADAlarmEnable(int channel, int alarmType, boolean alarmEnable, byte[] state) Sets the alarm enable value of the specified channel in the provided state buffer.
void	setADRange(int channel, double range, byte[] state) Sets the input range for the specified channel in the provided state buffer.
void	setADResolution(int channel, double resolution, byte[] state) Sets the conversion resolution value for the specified channel in the provided state buffer.
void	setOutput(int channel, boolean outputEnable, boolean outputState, byte[] state) Sets the output enable and state for the specified channel in the provided register buffer.
void	setPower(boolean external, byte[] state) Sets or clears the external power flag in the provided register buffer.
static int	voltageToInt(double voltage, double range) Converts a voltage double value to the DS2450 specific int value.
void	writeDevice(byte[] state) Writes the bytes in the provided A/D register pages that have been changed by the 'set' methods.

Methods inherited from class com.dalsemi.onewire.container.OneWireContainer

doSpeed, equals, getAdapter, getAddress, getAddressAsLong, getAddressAsString, hashCode, isAlarming, isPresent, setSpeed, setupContainer, setupContainer, setupContainer, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

BITMAP_OFFSET

public static final int BITMAP_OFFSET

Offset of BITMAP in array returned from read state

ALARM_OFFSET

public static final int ALARM_OFFSET

Offset of ALARMS in array returned from read state

EXPOWER_OFFSET

public static final int EXPOWER_OFFSET

Offset of external power offset in array returned from read state

CHANNELA

public static final int CHANNELA

Channel A number

CHANNELB

public static final int CHANNELB

Channel B number

CHANNELC

public static final int CHANNELC

Channel C number

CHANNELD

public static final int CHANNELD

Channel D number

NO_PRESET

public static final int NO_PRESET

No preset value

PRESET_TO_ZEROS

public static final int PRESET_TO_ZEROS

Preset value to zeros

PRESET_TO_ONES

public static final int PRESET_TO_ONES

Preset value to ones

NUM_CHANNELS

public static final int NUM_CHANNELS

Number of channels

Constructor Detail

OneWireContainer20

public OneWireContainer20()

Default constructor

OneWireContainer20

public OneWireContainer20(DSPortAdapter sourceAdapter,
                          byte[] newAddress)

Creates a container with a provided adapter object and the address of the 1-Wire device.

Parameters:

sourceAdapter - adapter required to communicate with this device

newAddress - address of this 1-Wire device

OneWireContainer20

public OneWireContainer20(DSPortAdapter sourceAdapter,
                          long newAddress)

Creates a container with a provided adapter object and the address of the 1-Wire device.

Parameters:

sourceAdapter - adapter required to communicate with this device

newAddress - address of this 1-Wire device

OneWireContainer20

public OneWireContainer20(DSPortAdapter sourceAdapter,
                          String newAddress)

Creates a container with a provided adapter object and the address of the 1-Wire device.

Parameters:

sourceAdapter - adapter required to communicate with this device

newAddress - address of this 1-Wire device

Method Detail

getName

public String getName()

Gets the name of this 1-Wire device.

Overrides:

getName in class OneWireContainer

Returns:

representation of this 1-Wire device's name

getAlternateNames

public String getAlternateNames()

Gets any other possible names for this 1-Wire device.

Overrides:

getAlternateNames in class OneWireContainer

Returns:

representation of this 1-Wire device's other names

getDescription

public String getDescription()

Gets a brief description of the functionality of this 1-Wire device.

Overrides:

getDescription in class OneWireContainer

Returns:

description of this 1-Wire device's functionality

getMaxSpeed

public int getMaxSpeed()

Gets the maximum speed this 1-Wire device can communicate at.

Overrides:

getMaxSpeed in class OneWireContainer

Returns:

maximum speed of this One-Wire device

getMemoryBanks

public Enumeration getMemoryBanks()

Gets an enumeration of memory banks.

Overrides:

getMemoryBanks in class OneWireContainer

Returns:

enumeration of memory banks

See Also:

MemoryBank, PagedMemoryBank, OTPMemoryBank

getNumberADChannels

public int getNumberADChannels()

Queries to get the number of channels supported by this A/D. Channel specific methods will use a channel number specified by an integer from [0 to (getNumberChannels() - 1)].

Specified by:

getNumberADChannels in interface ADContainer

Returns:

the number of channels

hasADAlarms

public boolean hasADAlarms()

Queries to see if this A/D measuring device has high/low alarms.

Specified by:

hasADAlarms in interface ADContainer

Returns:

true if it has high/low trips

getADRanges

public double[] getADRanges(int channel)

Queries to get an array of available ranges for the specified A/D channel.

Specified by:

getADRanges in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

Returns:

available ranges starting from the largest range to the smallest range

getADResolutions

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

Queries to get an array of available resolutions based on the specified range on the specified A/D channel.

Specified by:

getADResolutions in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

range - specified range

Returns:

available resolutions

canADMultiChannelRead

public boolean canADMultiChannelRead()

Queries to see if this A/D supports doing multiple voltage conversions at the same time.

Specified by:

canADMultiChannelRead in interface ADContainer

Returns:

true if can do multi-channel voltage reads

readDevice

public byte[] readDevice()
                  throws OneWireIOException,
                         OneWireException

Retrieves the entire A/D control/status and alarm pages. It reads this and verifies the data with the onboard CRC generator. Use the byte array returned from this method with static utility methods to extract the status, alarm and other register values. Appended to the data is 2 bytes that represent a bitmap of changed bytes. These bytes are used in the writeADRegisters() in conjuction with the 'set' methods to only write back the changed register bytes.

Specified by:

readDevice in interface OneWireSensor

Returns:

register page contents verified with onboard CRC

Throws:

OneWireIOException - Data was not read correctly

OneWireException - Could not find part

writeDevice

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

Writes the bytes in the provided A/D register pages that have been changed by the 'set' methods. It knows which state has changed by looking at the bitmap fields appended to the register data. Any alarm flags will be automatically cleared. Only VCC powered indicator byte in physical location 0x1C can be written in the calibration memory bank.

Specified by:

writeDevice in interface OneWireSensor

Parameters:

state - register pages

Throws:

OneWireIOException - Data was not written correctly

OneWireException - Could not find part

getADVoltage

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

Reads the voltage values. Must be used after a doADConvert() method call. Also must include the last valid state from the readDevice() method and this A/D must support multi-channel read canMultiChannelRead() if there are more then 1 channel.

Specified by:

getADVoltage in interface ADContainer

Parameters:

state - current state of this device returned from readDevice()

Returns:

voltage values for all channels

Throws:

OneWireIOException - Data was not read correctly

OneWireException - Could not find part

getADVoltage

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

Reads a channels voltage value. Must be used after a doADConvert() method call. Also must include the last valid state from the readDevice() method. Note, if more then one channel is to be read then it is more efficient to use the getADVoltage(byte[]) method that returns all channel values.

Specified by:

getADVoltage in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of this device returned from readDevice()

Returns:

voltage value for the specified channel

Throws:

OneWireIOException - Data was not read correctly

OneWireException - Could not find part

IllegalArgumentException - Invalid channel number passed

doADConvert

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

Performs voltage conversion on specified channel. The method getADVoltage() can be used to read the result of the conversion.

Specified by:

doADConvert in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of this device returned from readDevice()

Throws:

OneWireIOException - Data was not written correctly

OneWireException - Could not find part

doADConvert

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

Performs voltage conversion on all specified channels. The method getADVoltage() can be used to read the result of the conversion. This A/D must support multi-channel read canMultiChannelRead() if there are more then 1 channel is specified.

Specified by:

doADConvert in interface ADContainer

Parameters:

doConvert - which channels to perform conversion on.

state - current state of this device returned from readDevice()

Throws:

OneWireIOException - Data was not written correctly

OneWireException - Could not find part

doADConvert

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

Performs voltage conversion on specified channel. The method getADVoltage() can be used to read the result of the conversion.

Parameters:

channel - 0,1,2,3 representing the channels A,B,C,D

preset - preset value: NO_PRESET (0), PRESET_TO_ZEROS (1), and PRESET_TO_ONES (2)

state - state of this device returned from readDevice()

Throws:

OneWireIOException - Data could not be written correctly

OneWireException - Could not find part

IllegalArgumentException - Invalid channel number passed

doADConvert

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

Performs voltage conversion on all specified channels. The method getADVoltage() can be used to read the result of the conversion.

Parameters:

doConvert - which channels to perform conversion on

preset - preset values NO_PRESET (0), PRESET_TO_ZEROS (1), and PRESET_TO_ONES (2)

state - current state of this device returned from readDevice()

Throws:

OneWireIOException - Data could not be written correctly

OneWireException - Could not find part

getADAlarm

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

Extracts the alarm voltage value of the specified channel from the provided state buffer. The state buffer is retrieved from the readDevice() method.

Specified by:

getADAlarm in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

alarmType - desired alarm, ALARM_HIGH (1) or ALARM_LOW (0)

state - current state of this device returned from readDevice()

Returns:

alarm value in volts

Throws:

IllegalArgumentException - Invalid channel number passed

getADAlarmEnable

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

Extracts the alarm enable value of the specified channel from the provided state buffer. The state buffer is retrieved from the readDevice() method.

Specified by:

getADAlarmEnable in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

alarmType - desired alarm, ALARM_HIGH (1) or ALARM_LOW (0)

state - current state of the state returned from readDevice()

Returns:

true if specified alarm is enabled

Throws:

IllegalArgumentException - Invalid channel number passed

hasADAlarmed

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

Checks the alarm event value of the specified channel from the provided state buffer. The state buffer is retrieved from the readDevice() method.

Specified by:

hasADAlarmed in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

alarmType - desired alarm, ALARM_HIGH (1) or ALARM_LOW (0)

state - current state of the state returned from readDevice()

Returns:

true if specified alarm occurred

Throws:

IllegalArgumentException - Invalid channel number passed

getADResolution

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

Extracts the conversion resolution of the specified channel from the provided state buffer expressed in volts. The state is retrieved from the readDevice() method.

Specified by:

getADResolution in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of the state returned from readDevice()

Returns:

resolution of channel in volts

Throws:

IllegalArgumentException - Invalid channel number passed

getADRange

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

Extracts the input voltage range of the specified channel from the provided state buffer. The state buffer is retrieved from the readDevice() method.

Specified by:

getADRange in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of the state returned from readDevice()

Returns:

A/D input voltage range

Throws:

IllegalArgumentException - Invalid channel number passed

isOutputEnabled

public boolean isOutputEnabled(int channel,
                               byte[] state)
                        throws IllegalArgumentException

Detects if the output is enabled for the specified channel from the provided register buffer. The register buffer is retrieved from the readDevice() method.

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of the device returned from readDevice()

Returns:

true if output is enabled on specified channel

Throws:

IllegalArgumentException - Invalid channel number passed

getOutputState

public boolean getOutputState(int channel,
                              byte[] state)
                       throws IllegalArgumentException

Detects if the output is enabled for the specified channel from the provided register buffer. The register buffer is retrieved from the readDevice() method.

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

state - current state of the device returned from readDevice()

Returns:

false if output is conducting to ground and true if not conducting

Throws:

IllegalArgumentException - Invalid channel number passed

getDevicePOR

public boolean getDevicePOR(byte[] state)

Detects if this device has seen a Power-On-Reset (POR). If this has occured it may be necessary to set the state of the device to the desired values. The register buffer is retrieved from the readDevice() method.

Parameters:

state - current state of the device returned from readDevice()

Returns:

false if output is conducting to ground and true if not conducting

isPowerExternal

public boolean isPowerExternal(byte[] state)

Extracts the state of the external power indicator from the provided register buffer. Use 'setPower' to set or clear the external power indicator flag. The register buffer is retrieved from the readDevice() method.

Parameters:

state - current state of the device returned from readDevice()

Returns:

true if set to external power operation

setADAlarm

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

Sets the alarm voltage value of the specified channel in the provided state buffer. The state buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Specified by:

setADAlarm in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

alarmType - desired alarm, ALARM_HIGH (1) or ALARM_LOW (0)

alarm - alarm value (will be reduced to 8 bit resolution)

state - current state of this device returned from readDevice()

Throws:

IllegalArgumentException - Invalid channel number passed

setADAlarmEnable

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

Sets the alarm enable value of the specified channel in the provided state buffer. The state buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Specified by:

setADAlarmEnable in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

alarmType - desired alarm, ALARM_HIGH (1) or ALARM_LOW (0)

alarmEnable - alarm enable value

state - current state of this device returned from readDevice()

Throws:

IllegalArgumentException - Invalid channel number passed

setADResolution

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

Sets the conversion resolution value for the specified channel in the provided state buffer. The state buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Specified by:

setADResolution in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

resolution - resolution to use in volts

state - current state of this device returned from readDevice()

Throws:

IllegalArgumentException - Invalid channel number passed

setADRange

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

Sets the input range for the specified channel in the provided state buffer. The state buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Specified by:

setADRange in interface ADContainer

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

range - max volt range, use getRanges() method to get available ranges

state - current state of this device returned from readDevice()

Throws:

IllegalArgumentException - Invalid channel number passed

setOutput

public void setOutput(int channel,
                      boolean outputEnable,
                      boolean outputState,
                      byte[] state)

Sets the output enable and state for the specified channel in the provided register buffer. The register buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Parameters:

channel - channel in the range [0 to (getNumberChannels() - 1)]

outputEnable - true if output is enabled

outputState - false if output is conducting to ground and true if not conducting. This parameter is not used if outputEnable is false

state - current state of the device returned from readDevice()

setPower

public void setPower(boolean external,
                     byte[] state)

Sets or clears the external power flag in the provided register buffer. The register buffer is retrieved from the readDevice() method. The method writeDevice() must be called to finalize these changes to the device. Note that multiple 'set' methods can be called before one call to writeDevice().

Parameters:

external - true if setting external power is used

state - current state of this device returned from readDevice()

interpretVoltage

public static double interpretVoltage(long rawVoltage,
                                      double range)

Converts a raw voltage long value for the DS2450 into a valid voltage. Requires the max voltage value.

Parameters:

rawVoltage - raw voltage

range - max voltage

Returns:

calculated voltage based on the range

voltageToInt

public static int voltageToInt(double voltage,
                               double range)

Converts a voltage double value to the DS2450 specific int value. Requires the max voltage value.

Parameters:

voltage - voltage

range - max voltage

Returns:

the DS2450 voltage