Dallas Semiconductor 1-Wire API 1.10: Class OneWireContainer3A

com.dalsemi.onewire.container
Class OneWireContainer3A

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

All Implemented Interfaces:: OneWireSensor, SwitchContainer

public class OneWireContainer3A
extends OneWireContainer
implements SwitchContainer

1-Wire® container for a Single Addressable Switch, DS2413. This container encapsulates the functionality of the 1-Wire family type 3A (hex)

Features

Eight channels of programmable I/O with open-drain outputs
Logic level sensing of the PIO pin can be sensed
Multiple DS2413's can be identified on a common 1-Wire bus and operated independently.
Supports 1-Wire Conditional Search command with response controlled by programmable PIO conditions
Supports Overdrive mode which boosts communication speed up to 142k bits per second.

Usage

Version:: 1.00, 01 Jun 2002
Author:: JPE
See Also:: OneWireSensor, SwitchContainer, OneWireContainer

Field Summary

static byte PIO_ACCESS_READ
          PIO Access read command

static byte PIO_ACCESS_WRITE
          PIO Access read command

Constructor Summary

OneWireContainer3A()
          Creates a new OneWireContainer for communication with a DS2413.

OneWireContainer3A(DSPortAdapter sourceAdapter, byte[] newAddress)
          Creates a new OneWireContainer for communication with a DS2413.

OneWireContainer3A(DSPortAdapter sourceAdapter, long newAddress)
          Creates a new OneWireContainer for communication with a DS2413.

OneWireContainer3A(DSPortAdapter sourceAdapter, String newAddress)
          Creates a new OneWireContainer for communication with a DS2413.

Method Summary

void clearActivity()
          Clears the activity latches the next time possible.

String getAlternateNames()
          Retrieves the alternate Dallas Semiconductor part numbers or names.

String getDescription()
          Gets a short description of the function of this iButton or 1-Wire Device type.

boolean getLatchState(int channel, byte[] state)
          Checks the latch state of the indicated channel.

boolean getLevel(int channel, byte[] state)
          Checks the sensed level on the indicated channel.

int getMaxSpeed()
          Returns the maximum speed this iButton or 1-Wire device can communicate at.

String getName()
          Gets the Dallas Semiconductor part number of the iButton or 1-Wire Device as a java.lang.String.

int getNumberChannels(byte[] state)
          Gets the number of channels supported by this switch.

boolean getSensedActivity(int channel, byte[] state)
          Checks if the indicated channel has experienced activity.

boolean hasActivitySensing()
          Checks if the channels of this switch support activity sensing.

boolean hasLevelSensing()
          Checks if the channels of this switch support level sensing.

boolean hasSmartOn()
          Checks if the channels of this switch support 'smart on'.

boolean isHighSideSwitch()
          Checks if the channels of this switch are 'high side' switches.

boolean onlySingleChannelOn()
          Checks if the channels of this switch require that only one channel is on at any one time.

byte[] readDevice()
          Retrieves the 1-Wire device sensor state.

byte[] readRegister()
          Retrieves the 1-Wire device register mask.

void setLatchState(byte set, byte[] state)
          Sets the latch state for all of the channels.

void setLatchState(int channel, boolean latchState, boolean doSmart, byte[] state)
          Sets the latch state of the indicated channel.

void writeDevice(byte[] state)
          Writes the 1-Wire device sensor state that have been changed by 'set' methods.

void writeRegister(byte[] register)
          Writes the 1-Wire device register mask that have been changed by 'set' methods.

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

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

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

PIO_ACCESS_READ

public static final byte PIO_ACCESS_READ

PIO Access read command

PIO_ACCESS_WRITE

public static final byte PIO_ACCESS_WRITE

PIO Access read command

Constructor Detail

OneWireContainer3A

public OneWireContainer3A()

Creates a new OneWireContainer for communication with a DS2413. Note that the method setupContainer(com.dalsemi.onewire.adapter.DSPortAdapter,byte[]) must be called to set the correct DSPortAdapter device address.

See Also:: setupContainer(DSPortAdapter,byte[]), OneWireContainer3A(DSPortAdapter,byte[]), OneWireContainer3A(DSPortAdapter,long), OneWireContainer3A(DSPortAdapter,String)

OneWireContainer3A

public OneWireContainer3A(DSPortAdapter sourceAdapter,
                          byte[] newAddress)

Creates a new OneWireContainer for communication with a DS2413.

Parameters:: sourceAdapter - adapter object required to communicate with this 1-Wire device; newAddress - address of this DS2413
See Also:: OneWireContainer3A(), OneWireContainer3A(DSPortAdapter,long), OneWireContainer3A(DSPortAdapter,String)

OneWireContainer3A

public OneWireContainer3A(DSPortAdapter sourceAdapter,
                          long newAddress)

Creates a new OneWireContainer for communication with a DS2413.

Parameters:: sourceAdapter - adapter object required to communicate with this 1-Wire device; newAddress - address of this DS2413
See Also:: OneWireContainer3A(), OneWireContainer3A(DSPortAdapter,byte[]), OneWireContainer3A(DSPortAdapter,String)

OneWireContainer3A

public OneWireContainer3A(DSPortAdapter sourceAdapter,
                          String newAddress)

Creates a new OneWireContainer for communication with a DS2413.

Parameters:: sourceAdapter - adapter object required to communicate with this 1-Wire device; newAddress - address of this DS2413
See Also:: OneWireContainer3A(), OneWireContainer3A(DSPortAdapter,byte[]), OneWireContainer3A(DSPortAdapter,long)

Method Detail

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

getMaxSpeed

public int getMaxSpeed()

Returns the maximum speed this iButton or 1-Wire device can communicate at.

Overrides:: getMaxSpeed in class OneWireContainer

Returns:: maximum speed
See Also:: DSPortAdapter.setSpeed(int)

getNumberChannels

public int getNumberChannels(byte[] state)

Gets the number of channels supported by this switch. Channel specific methods will use a channel number specified by an integer from [0 to (getNumberChannels(byte[]) - 1)]. Note that all devices of the same family will not necessarily have the same number of channels.

Specified by:: getNumberChannels in interface SwitchContainer

Parameters:: state - current state of the device returned from readDevice()
Returns:: the number of channels for this device
See Also:: OneWireSensor.readDevice()

isHighSideSwitch

public boolean isHighSideSwitch()

Checks if the channels of this switch are 'high side' switches. This indicates that when 'on' or true, the switch output is connect to the 1-Wire data. If this method returns false then when the switch is 'on' or true, the switch is connected to ground.

Specified by:: isHighSideSwitch in interface SwitchContainer

Returns:: true if the switch is a 'high side' switch, false if the switch is a 'low side' switch
See Also:: getLatchState(int,byte[])

hasActivitySensing

public boolean hasActivitySensing()

Checks if the channels of this switch support activity sensing. If this method returns true then the method getSensedActivity(int,byte[]) can be used.

Specified by:: hasActivitySensing in interface SwitchContainer

Returns:: true if channels support activity sensing
See Also:: getSensedActivity(int,byte[]), clearActivity()

hasLevelSensing

public boolean hasLevelSensing()

Checks if the channels of this switch support level sensing. If this method returns true then the method getLevel(int,byte[]) can be used.

Specified by:: hasLevelSensing in interface SwitchContainer

Returns:: true if channels support level sensing
See Also:: getLevel(int,byte[])

hasSmartOn

public boolean hasSmartOn()

Checks if the channels of this switch support 'smart on'. Smart on is the ability to turn on a channel such that only 1-Wire device on this channel are awake and ready to do an operation. This greatly reduces the time to discover the device down a branch. If this method returns true then the method setLatchState(int,boolean,boolean,byte[]) can be used with the doSmart parameter true.

Specified by:: hasSmartOn in interface SwitchContainer

Returns:: true if channels support 'smart on'
See Also:: setLatchState(int,boolean,boolean,byte[])

onlySingleChannelOn

public boolean onlySingleChannelOn()

Checks if the channels of this switch require that only one channel is on at any one time. If this method returns true then the method setLatchState(int,boolean,boolean,byte[]) will not only affect the state of the given channel but may affect the state of the other channels as well to insure that only one channel is on at a time.

Specified by:: onlySingleChannelOn in interface SwitchContainer

Returns:: true if only one channel can be on at a time.
See Also:: setLatchState(int,boolean,boolean,byte[])

getLevel

public boolean getLevel(int channel,
                        byte[] state)

Checks the sensed level on the indicated channel. To avoid an exception, verify that this switch has level sensing with the hasLevelSensing(). Level sensing means that the device can sense the logic level on its PIO pin.

Specified by:: getLevel in interface SwitchContainer

Parameters:: channel - channel to execute this operation, in the range [0 to (getNumberChannels(byte[]) - 1)]; state - current state of the device returned from readDevice()
Returns:: true if level sensed is 'high' and false if level sensed is 'low'
See Also:: OneWireSensor.readDevice(), hasLevelSensing()

getLatchState

public boolean getLatchState(int channel,
                             byte[] state)

Checks the latch state of the indicated channel.

Specified by:: getLatchState in interface SwitchContainer

Parameters:: channel - channel to execute this operation, in the range [0 to (getNumberChannels(byte[]) - 1)]; state - current state of the device returned from readDevice()
Returns:: true if channel latch is 'on' or conducting and false if channel latch is 'off' and not conducting. Note that the actual output when the latch is 'on' is returned from the isHighSideSwitch() method.
See Also:: OneWireSensor.readDevice(), isHighSideSwitch(), setLatchState(int,boolean,boolean,byte[])

getSensedActivity

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

Checks if the indicated channel has experienced activity. This occurs when the level on the PIO pins changes. To clear the activity that is reported, call clearActivity(). To avoid an exception, verify that this device supports activity sensing by calling the method hasActivitySensing().

Specified by:: getSensedActivity in interface SwitchContainer

Parameters:: channel - channel to execute this operation, in the range [0 to (getNumberChannels(byte[]) - 1)]; state - current state of the device returned from readDevice()
Returns:: true if activity was detected and false if no activity was detected
Throws:: OneWireException - if this device does not have activity sensing
See Also:: hasActivitySensing(), clearActivity()

clearActivity

public void clearActivity()
                   throws OneWireException

Clears the activity latches the next time possible. For example, on a DS2406/07, this happens the next time the status is read with readDevice().

Specified by:: clearActivity in interface SwitchContainer

Throws:: OneWireException - if this device does not support activity sensing
See Also:: OneWireSensor.readDevice(), getSensedActivity(int,byte[])

setLatchState

public void setLatchState(int channel,
                          boolean latchState,
                          boolean doSmart,
                          byte[] state)

Sets the latch state of the indicated 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().

Specified by:: setLatchState in interface SwitchContainer

Parameters:: channel - channel to execute this operation, in the range [0 to (getNumberChannels(byte[]) - 1)]; latchState - true to set the channel latch 'on' (conducting) and false to set the channel latch 'off' (not conducting). Note that the actual output when the latch is 'on' is returned from the isHighSideSwitch() method.; doSmart - If latchState is 'on'/true then doSmart indicates if a 'smart on' is to be done. To avoid an exception check the capabilities of this device using the hasSmartOn() method.; state - current state of the device returned from readDevice()
See Also:: hasSmartOn(), getLatchState(int,byte[]), OneWireSensor.writeDevice(byte[])

setLatchState

public void setLatchState(byte set,
                          byte[] state)

Sets the latch state for all of the channels. 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:: set - the state to set all of the channels, in the range [0 to (getNumberChannels(byte[]) - 1)]; state - current state of the device returned from readDevice()
See Also:: getLatchState(int,byte[]), OneWireSensor.writeDevice(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

readRegister

public byte[] readRegister()
                    throws OneWireIOException,
                           OneWireException

Retrieves the 1-Wire device register mask. This register is returned as a byte array. Pass this byte array to the 'get' and 'set' methods. If the device register mask needs to be changed then call the 'writeRegister' to finalize the changes.

Returns:: 1-Wire device register mask
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 PIO access write (x x x x x x PIOB PIOA)
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

writeRegister

public void writeRegister(byte[] register)
                   throws OneWireIOException,
                          OneWireException

Writes the 1-Wire device register mask that have been changed by 'set' methods.

Parameters:: register - 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

Field Summary
`static byte`	`PIO_ACCESS_READ` PIO Access read command
`static byte`	`PIO_ACCESS_WRITE` PIO Access read command

Constructor Summary
`OneWireContainer3A()` Creates a new `OneWireContainer` for communication with a DS2413.
`OneWireContainer3A(DSPortAdapter sourceAdapter, byte[] newAddress)` Creates a new `OneWireContainer` for communication with a DS2413.
`OneWireContainer3A(DSPortAdapter sourceAdapter, long newAddress)` Creates a new `OneWireContainer` for communication with a DS2413.
`OneWireContainer3A(DSPortAdapter sourceAdapter, String newAddress)` Creates a new `OneWireContainer` for communication with a DS2413.

Method Summary
`void`	`clearActivity()` Clears the activity latches the next time possible.
`String`	`getAlternateNames()` Retrieves the alternate Dallas Semiconductor part numbers or names.
`String`	`getDescription()` Gets a short description of the function of this iButton or 1-Wire Device type.
`boolean`	`getLatchState(int channel, byte[] state)` Checks the latch state of the indicated channel.
`boolean`	`getLevel(int channel, byte[] state)` Checks the sensed level on the indicated channel.
`int`	`getMaxSpeed()` Returns the maximum speed this iButton or 1-Wire device can communicate at.
`String`	`getName()` Gets the Dallas Semiconductor part number of the iButton or 1-Wire Device as a `java.lang.String`.
`int`	`getNumberChannels(byte[] state)` Gets the number of channels supported by this switch.
`boolean`	`getSensedActivity(int channel, byte[] state)` Checks if the indicated channel has experienced activity.
`boolean`	`hasActivitySensing()` Checks if the channels of this switch support activity sensing.
`boolean`	`hasLevelSensing()` Checks if the channels of this switch support level sensing.
`boolean`	`hasSmartOn()` Checks if the channels of this switch support 'smart on'.
`boolean`	`isHighSideSwitch()` Checks if the channels of this switch are 'high side' switches.
`boolean`	`onlySingleChannelOn()` Checks if the channels of this switch require that only one channel is on at any one time.
`byte[]`	`readDevice()` Retrieves the 1-Wire device sensor state.
`byte[]`	`readRegister()` Retrieves the 1-Wire device register mask.
`void`	`setLatchState(byte set, byte[] state)` Sets the latch state for all of the channels.
`void`	`setLatchState(int channel, boolean latchState, boolean doSmart, byte[] state)` Sets the latch state of the indicated channel.
`void`	`writeDevice(byte[] state)` Writes the 1-Wire device sensor state that have been changed by 'set' methods.
`void`	`writeRegister(byte[] register)` Writes the 1-Wire device register mask that have been changed by 'set' methods.

com.dalsemi.onewire.container Class OneWireContainer3A

Features

Usage

PIO_ACCESS_READ

PIO_ACCESS_WRITE

OneWireContainer3A

OneWireContainer3A

OneWireContainer3A

OneWireContainer3A

getName

getAlternateNames

getDescription

getMaxSpeed

getNumberChannels

isHighSideSwitch

hasActivitySensing

hasLevelSensing

hasSmartOn

onlySingleChannelOn

getLevel

getLatchState

getSensedActivity

clearActivity

setLatchState

setLatchState

readDevice

readRegister

writeDevice

writeRegister

com.dalsemi.onewire.container
Class OneWireContainer3A