com.sun.spot.sensorboard.peripheral
Class ADJDS311TriColorLightSensor

java.lang.Object
  com.sun.spot.resources.Resource
      com.sun.spot.sensorboard.peripheral.ADJDS311TriColorLightSensor

All Implemented Interfaces:

IResource, ILightSensor, IMeasurementInfo, IMeasurementRangeVariable, IStandby, ITransducer, ITriColorLightSensor, IScalarInput

public class ADJDS311TriColorLightSensor
extends Resource
implements ITriColorLightSensor, ILightSensor, IMeasurementInfo, IMeasurementRangeVariable, IStandby

Class to implement an RGB light sensor on the demo sensor board and provide access to it via the ITriColorLightSensor interface. Provides methods specific to this particular light sensor.

The Avago ADJD-S311-CR999 RGB Digital Color Sensor measures the light level using a filter-coated photodiode array that converts the incident light into digital Red, Green, Blue & Clear readings. Since all the outputs increase linearly with increasing light intensity, the sensor can measure both color and total intensity of the light.

Note: Before the ADJD-S311/S371 can be used, a one time sensor gain optimization routine must be done so that the digital values ranges from 0 to 1000.

Author:

Ron Goldman

Field Summary

static int	BLUE
static int	CLEAR
static int	GREEN
static int[][]	MAX_GAINS
static int[][]	MID_GAINS
static int[][]	MIN_GAINS
static int	RED

Constructor Summary

ADJDS311TriColorLightSensor()

Method Summary

void	addILightSensorThresholdListener(ILightSensorThresholdListener who)
void	addIScalarInputThresholdListener(IScalarInputThresholdListener who) temporary method for compatibility with deprecated ILightSensor interface.
boolean	areThresholdEventsEnabled() temporary method for compatibility with deprecated ILightSensor interface.
SensorEvent	createSensorEvent() Create a SensorEvent of the appropriate type for this sensor.
void	enableThresholdEvents(boolean enable) temporary method for compatibility with deprecated ILightSensor interface.
double	getAccuracy() Returns the accuracy of the sensor (in the current measurement range) as a percentage of reading (=data value).
int[]	getAverageColorValues() Return the average of 17 readings of the red, green, blue & clear light values.
int[]	getAverageColorValues(int n) Return the average of N readings of the red, green, blue & clear light values.
int	getAverageValue() Return the average of 17 readings of the clear light value.
int	getAverageValue(int n) Return the average of N readings of the clear light value.
int	getBlueValue() Read the current blue light value.
int	getClearValue() Read the current clear light value.
int[]	getColorValues() Read the current red, green, blue & clear light values.
String	getCurrentRangeSetting() Return the current sensor gain settings.
String	getDescription() This method returns a readable description of the sensor.
int[][]	getGains() Return the current gain values.
int	getGreenValue() Read the current green light value.
int	getHighThreshold() temporary method for compatibility with deprecated ILightSensor interface.
ILightSensorThresholdListener[]	getILightSensorThresholdListeners()
PinDescriptor	getIndex() temporary method for compatibility with deprecated ILightSensor interface.
IScalarInputThresholdListener[]	getIScalarInputThresholdListeners() temporary method for compatibility with deprecated ILightSensor interface.
int	getLowThreshold() temporary method for compatibility with deprecated ILightSensor interface.
double	getMaxSamplingRate() Return the maximum sampling rate per second for this sensor.
double	getMaxValue() Returns the current maximum value of the sensor (in the current measurement range).
double	getMinValue() Returns the current minimum value of the sensor (in the current measurement range).
int[]	getOffsetValues() Set the current trim offsets based on current light reading and return them.
int	getRange() temporary method for compatibility with deprecated ILightSensor interface.
int	getRedValue() Read the current red light value.
double	getResolution() Returns the resolution of the range (in the current measurement range).
int	getValue() Return the current light sensor reading.
boolean	isInStandbyMode() Check if the light sensor is in standby mode.
int[][]	readGains() Read the current gain settings from the sensor.
void	removeILightSensorThresholdListener(ILightSensorThresholdListener who)
void	removeIScalarInputThresholdListener(IScalarInputThresholdListener who) temporary method for compatibility with deprecated ILightSensor interface.
void	saveEventState(SensorEvent evt) Save the current sensor state in the specified event.
void	setCurrentRangeSetting(String range) Sets the measurement range setting of the sensor.
void	setGains(int[][] gains) Set the light sensor sensitivity: number of capacitors & integration time for each channel: red, green, blue & clear.
void	setStandbyMode(boolean sleep) Put the light sensor into standby mode to save power.
void	setThresholds(int low, int high) temporary method for compatibility with deprecated ILightSensor interface.
void	setTrimOffsetMode(boolean enable) Specify if sensor should apply trim offsets to values returned when reading the Red/Green/Blue/Clear light values.
void	simpleAdjustGains() Use a simple method to adjust the gain settings to the maximum sensitivity for the current clear light level.
boolean	supportsThresholdEvents() temporary method for compatibility with deprecated ILightSensor interface.

Methods inherited from class com.sun.spot.resources.Resource

addTag, getTags, getTagValue, hasTag, removeTag

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.sun.spot.resources.IResource

addTag, getTags, getTagValue, hasTag, removeTag

Methods inherited from interface com.sun.spot.resources.IResource

addTag, getTags, getTagValue, hasTag, removeTag

Methods inherited from interface com.sun.spot.resources.IResource

addTag, getTags, getTagValue, hasTag, removeTag

Field Detail

RED

public static final int RED

See Also:

Constant Field Values

GREEN

public static final int GREEN

See Also:

Constant Field Values

BLUE

public static final int BLUE

See Also:

Constant Field Values

CLEAR

public static final int CLEAR

See Also:

Constant Field Values

MAX_GAINS

public static final int[][] MAX_GAINS

MID_GAINS

public static final int[][] MID_GAINS

MIN_GAINS

public static final int[][] MIN_GAINS

Constructor Detail

ADJDS311TriColorLightSensor

public ADJDS311TriColorLightSensor()

Method Detail

setGains

public void setGains(int[][] gains)
              throws IOException

Set the light sensor sensitivity: number of capacitors & integration time for each channel: red, green, blue & clear. Note: The number of selectable capacitors ranges from 1 to 16 with the value starting from 0 (i.e. 0 = 1 capacitor). Less capacitors will give higher sensitivity. The integration time slot can be varied from 0 to 4095 (= 0xFFF). More integration time slot will give higher sensitivity.

Parameters:

gains - a 2-dimensional array [2][4] with values: { { num_cap_Red, num_cap_Green, num_cap_Blue, num_cap_Clear } { int_time_Red, int_time_Green, int_time_Blue, int_time_Clear } }

Throws:

IOException

getGains

public int[][] getGains()

Return the current gain values.

Returns:

an int[2][4] array with gain values

readGains

public int[][] readGains()
                  throws IOException

Read the current gain settings from the sensor.

Returns:

an int[2][4] array with gain values

Throws:

IOException

setTrimOffsetMode

public void setTrimOffsetMode(boolean enable)
                       throws IOException

Specify if sensor should apply trim offsets to values returned when reading the Red/Green/Blue/Clear light values. When in trim offset mode the value returned when reading a light value is the actual light value read minus the trim offset.

Parameters:

enable - if true then apply offsets to future RGBC reads

Throws:

IOException

getOffsetValues

public int[] getOffsetValues()
                      throws IOException

Set the current trim offsets based on current light reading and return them.

Returns:

an array of the current trim offsets

Throws:

IOException

simpleAdjustGains

public void simpleAdjustGains()
                       throws IOException

Use a simple method to adjust the gain settings to the maximum sensitivity for the current clear light level. Tries to adjust the number of capacitors and then the integration time, while keeping the clear light value less than 1000. Starts with the sensor set to its minimum sensitivity.

Generally takes from 1-10 seconds to find a good gains setting.

Note if trim offsets were in use, calling simpleAdjustGains will disable them.

Throws:

IOException

getClearValue

public int getClearValue()
                  throws IOException

Read the current clear light value.

Specified by:

getClearValue in interface ITriColorLightSensor

Returns:

the clear light value.

Throws:

IOException

getRedValue

public int getRedValue()
                throws IOException

Read the current red light value.

Specified by:

getRedValue in interface ITriColorLightSensor

Returns:

the red light value.

Throws:

IOException

getGreenValue

public int getGreenValue()
                  throws IOException

Read the current green light value.

Specified by:

getGreenValue in interface ITriColorLightSensor

Returns:

the green light value.

Throws:

IOException

getBlueValue

public int getBlueValue()
                 throws IOException

Read the current blue light value.

Specified by:

getBlueValue in interface ITriColorLightSensor

Returns:

the blue light value.

Throws:

IOException

getColorValues

public int[] getColorValues()
                     throws IOException

Read the current red, green, blue & clear light values.

Specified by:

getColorValues in interface ITriColorLightSensor

Returns:

an array of the red, green, blue & clear light values.

Throws:

IOException

getAverageColorValues

public int[] getAverageColorValues(int n)
                            throws IOException

Return the average of N readings of the red, green, blue & clear light values. Note: the sensor is sampled every 1 millisecond.

Specified by:

getAverageColorValues in interface ITriColorLightSensor

Parameters:

n - the number of readings to take and average

Returns:

an array of the averaged red, green, blue & clear light values.

Throws:

IOException

getAverageColorValues

public int[] getAverageColorValues()
                            throws IOException

Return the average of 17 readings of the red, green, blue & clear light values.

Specified by:

getAverageColorValues in interface ITriColorLightSensor

Returns:

an array of the averaged red, green, blue & clear light values.

Throws:

IOException

getAverageValue

public int getAverageValue(int n)
                    throws IOException

Return the average of N readings of the clear light value.

Specified by:

getAverageValue in interface ILightSensor

Parameters:

n - the number of readings to take and average

Returns:

the averaged clear light value.

Throws:

IOException

getAverageValue

public int getAverageValue()
                    throws IOException

Return the average of 17 readings of the clear light value.

Specified by:

getAverageValue in interface ILightSensor

Returns:

the averaged clear light value.

Throws:

IOException

addILightSensorThresholdListener

public void addILightSensorThresholdListener(ILightSensorThresholdListener who)

removeILightSensorThresholdListener

public void removeILightSensorThresholdListener(ILightSensorThresholdListener who)

getILightSensorThresholdListeners

public ILightSensorThresholdListener[] getILightSensorThresholdListeners()

getValue

public int getValue()
             throws IOException

Description copied from interface: ILightSensor

Return the current light sensor reading.

Specified by:

getValue in interface ILightSensor

Specified by:

getValue in interface IScalarInput

Returns:

the current light intensity.

Throws:

IOException

getDescription

public String getDescription()

Description copied from interface: ITransducer

This method returns a readable description of the sensor. The description should tell the essentials of the sensor, including at least the sensor type (accelerometer, microphone, thermometer). The returned string MUST not be null or an empty string.

Specified by:

getDescription in interface ITransducer

Returns:

the description of the sensor

getMaxSamplingRate

public double getMaxSamplingRate()

Description copied from interface: ITransducer

Return the maximum sampling rate per second for this sensor.

Specified by:

getMaxSamplingRate in interface ITransducer

Returns:

the maximum sampling rate per second for this sensor or 0 if not applicable.

createSensorEvent

public SensorEvent createSensorEvent()

Description copied from interface: ITransducer

Create a SensorEvent of the appropriate type for this sensor.

Specified by:

createSensorEvent in interface ITransducer

Returns:

a SensorEvent of the appropriate type for this sensor.

saveEventState

public void saveEventState(SensorEvent evt)

Description copied from interface: ITransducer

Save the current sensor state in the specified event.

Specified by:

saveEventState in interface ITransducer

Parameters:

evt - the event to store the sensor state in

getIndex

public PinDescriptor getIndex()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

getIndex in interface IScalarInput

Returns:

null

getRange

public int getRange()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

getRange in interface IScalarInput

Returns:

0x3ff

supportsThresholdEvents

public boolean supportsThresholdEvents()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

supportsThresholdEvents in interface IScalarInput

Returns:

false

addIScalarInputThresholdListener

public void addIScalarInputThresholdListener(IScalarInputThresholdListener who)

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

addIScalarInputThresholdListener in interface IScalarInput

Parameters:

who - the light sensor threshold listener to add.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

removeIScalarInputThresholdListener

public void removeIScalarInputThresholdListener(IScalarInputThresholdListener who)

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

removeIScalarInputThresholdListener in interface IScalarInput

Parameters:

who - the scalar input threshold listener to remove.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

getIScalarInputThresholdListeners

public IScalarInputThresholdListener[] getIScalarInputThresholdListeners()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

getIScalarInputThresholdListeners in interface IScalarInput

Returns:

all of this scalar input's ILightSensorThresholdListener or an empty array if no scalar input threshold listeners are currently registered.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

setThresholds

public void setThresholds(int low,
                          int high)

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

setThresholds in interface IScalarInput

Parameters:

low - the new low threshold value.

high - the new high threshold value.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

getLowThreshold

public int getLowThreshold()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

getLowThreshold in interface IScalarInput

Returns:

the current low threshold value.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

getHighThreshold

public int getHighThreshold()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

getHighThreshold in interface IScalarInput

Returns:

the current high threshold value.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

enableThresholdEvents

public void enableThresholdEvents(boolean enable)

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

enableThresholdEvents in interface IScalarInput

Parameters:

enable - if true then listeners will be notified if the scalar input reading goes above the high threshold or below the low threshold.

Throws:

IllegalStateException - since TriColorLightSensor does not support threshold events

areThresholdEventsEnabled

public boolean areThresholdEventsEnabled()

temporary method for compatibility with deprecated ILightSensor interface.

Specified by:

areThresholdEventsEnabled in interface IScalarInput

Returns:

false

getMinValue

public double getMinValue()

Returns the current minimum value of the sensor (in the current measurement range).

Specified by:

getMinValue in interface IMeasurementInfo

Returns:

the min value of the sensor

getMaxValue

public double getMaxValue()

Returns the current maximum value of the sensor (in the current measurement range).

Specified by:

getMaxValue in interface IMeasurementInfo

Returns:

the max value of the sensor

getResolution

public double getResolution()

Returns the resolution of the range (in the current measurement range). The resolution is the minimum amount of change in the input of a sensor that can be detected as a change in the output. Resolution is a property of the transducer of a sensor but the input and output ranges and word length of the A/D converter usually set the limitations for the resolution of a digital sensor.

Specified by:

getResolution in interface IMeasurementInfo

Returns:

resolution of the sensor

getAccuracy

public double getAccuracy()

Returns the accuracy of the sensor (in the current measurement range) as a percentage of reading (=data value). Because this accuracy value describes the relative measurement error, greater values indicate a less accurate sensor. The accuracy value is within: 0 ≤ accuracy < 1

Specified by:

getAccuracy in interface IMeasurementInfo

Returns:

the accuracy of the sensor. If the accuracy is not known, a value of -1 is returned.

getCurrentRangeSetting

public String getCurrentRangeSetting()

Return the current sensor gain settings. Format is: (capR, capG, capB, capC) (intR, intG, intB, intC)

Specified by:

getCurrentRangeSetting in interface IMeasurementRangeVariable

Returns:

a String containing the current range settings

setCurrentRangeSetting

public void setCurrentRangeSetting(String range)

Sets the measurement range setting of the sensor.

Specified by:

setCurrentRangeSetting in interface IMeasurementRangeVariable

Parameters:

range - the measurement range setting to be set as a String.

Throws:

IllegalArgumentException - - if the given range is not a valid range for the sensor.

setStandbyMode

public void setStandbyMode(boolean sleep)

Put the light sensor into standby mode to save power. Note: attempts to read light sensor values while in standby mode will throw an IllegalStateException.

Specified by:

setStandbyMode in interface IStandby

Parameters:

sleep - if true then put light sensor into standby mode

isInStandbyMode

public boolean isInStandbyMode()

Check if the light sensor is in standby mode.

Specified by:

isInStandbyMode in interface IStandby

Returns:

true if the light sensor is in standby mode