Class: Tinkerforge::BrickletColor

Inherits:
Device
  • Object
show all
Defined in:
lib/tinkerforge/bricklet_color.rb

Overview

Measures color (RGB value), illuminance and color temperature

Constant Summary collapse

DEVICE_IDENTIFIER =

:nodoc:

243
DEVICE_DISPLAY_NAME =

:nodoc:

'Color Bricklet'
CALLBACK_COLOR =

This callback is triggered periodically with the period that is set by BrickletColor#set_color_callback_period. The parameter is the color of the sensor as RGBC.

CALLBACK_COLOR is only triggered if the color has changed since the last triggering.

8
CALLBACK_COLOR_REACHED =

This callback is triggered when the threshold as set by BrickletColor#set_color_callback_threshold is reached. The parameter is the color of the sensor as RGBC.

If the threshold keeps being reached, the callback is triggered periodically with the period as set by BrickletColor#set_debounce_period.

9
CALLBACK_ILLUMINANCE =

This callback is triggered periodically with the period that is set by BrickletColor#set_illuminance_callback_period. The parameter is the illuminance. See BrickletColor#get_illuminance for how to interpret this value.

CALLBACK_ILLUMINANCE is only triggered if the illuminance has changed since the last triggering.

21
CALLBACK_COLOR_TEMPERATURE =

This callback is triggered periodically with the period that is set by BrickletColor#set_color_temperature_callback_period. The parameter is the color temperature in Kelvin.

CALLBACK_COLOR_TEMPERATURE is only triggered if the color temperature has changed since the last triggering.

22
FUNCTION_GET_COLOR =

:nodoc:

1
FUNCTION_SET_COLOR_CALLBACK_PERIOD =

:nodoc:

2
FUNCTION_GET_COLOR_CALLBACK_PERIOD =

:nodoc:

3
FUNCTION_SET_COLOR_CALLBACK_THRESHOLD =

:nodoc:

4
FUNCTION_GET_COLOR_CALLBACK_THRESHOLD =

:nodoc:

5
FUNCTION_SET_DEBOUNCE_PERIOD =

:nodoc:

6
FUNCTION_GET_DEBOUNCE_PERIOD =

:nodoc:

7
FUNCTION_LIGHT_ON =

:nodoc:

10
FUNCTION_LIGHT_OFF =

:nodoc:

11
FUNCTION_IS_LIGHT_ON =

:nodoc:

12
FUNCTION_SET_CONFIG =

:nodoc:

13
FUNCTION_GET_CONFIG =

:nodoc:

14
FUNCTION_GET_ILLUMINANCE =

:nodoc:

15
FUNCTION_GET_COLOR_TEMPERATURE =

:nodoc:

16
FUNCTION_SET_ILLUMINANCE_CALLBACK_PERIOD =

:nodoc:

17
FUNCTION_GET_ILLUMINANCE_CALLBACK_PERIOD =

:nodoc:

18
FUNCTION_SET_COLOR_TEMPERATURE_CALLBACK_PERIOD =

:nodoc:

19
FUNCTION_GET_COLOR_TEMPERATURE_CALLBACK_PERIOD =

:nodoc:

20
FUNCTION_GET_IDENTITY =

:nodoc:

255
THRESHOLD_OPTION_OFF =

:nodoc:

'x'
THRESHOLD_OPTION_OUTSIDE =

:nodoc:

'o'
THRESHOLD_OPTION_INSIDE =

:nodoc:

'i'
THRESHOLD_OPTION_SMALLER =

:nodoc:

'<'
THRESHOLD_OPTION_GREATER =

:nodoc:

'>'
LIGHT_ON =

:nodoc:

0
LIGHT_OFF =

:nodoc:

1
GAIN_1X =

:nodoc:

0
GAIN_4X =

:nodoc:

1
GAIN_16X =

:nodoc:

2
GAIN_60X =

:nodoc:

3
INTEGRATION_TIME_2MS =

:nodoc:

0
INTEGRATION_TIME_24MS =

:nodoc:

1
INTEGRATION_TIME_101MS =

:nodoc:

2
INTEGRATION_TIME_154MS =

:nodoc:

3
INTEGRATION_TIME_700MS =

:nodoc:

4

Constants inherited from Device

Device::RESPONSE_EXPECTED_ALWAYS_FALSE, Device::RESPONSE_EXPECTED_ALWAYS_TRUE, Device::RESPONSE_EXPECTED_FALSE, Device::RESPONSE_EXPECTED_INVALID_FUNCTION_ID, Device::RESPONSE_EXPECTED_TRUE

Instance Attribute Summary

Attributes inherited from Device

#callback_formats, #expected_response_function_id, #expected_response_sequence_number, #registered_callbacks, #uid

Instance Method Summary collapse

Methods inherited from Device

#dequeue_response, #enqueue_response, #get_api_version, #get_response_expected, #send_request, #set_response_expected, #set_response_expected_all

Constructor Details

#initialize(uid, ipcon) ⇒ BrickletColor

Creates an object with the unique device ID uid and adds it to the IP Connection ipcon.



90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/tinkerforge/bricklet_color.rb', line 90

def initialize(uid, ipcon)
  super uid, ipcon

  @api_version = [2, 0, 0]

  @response_expected[FUNCTION_GET_COLOR] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_COLOR_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_COLOR_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_COLOR_CALLBACK_THRESHOLD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_COLOR_CALLBACK_THRESHOLD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_DEBOUNCE_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_DEBOUNCE_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[CALLBACK_COLOR] = RESPONSE_EXPECTED_ALWAYS_FALSE
  @response_expected[CALLBACK_COLOR_REACHED] = RESPONSE_EXPECTED_ALWAYS_FALSE
  @response_expected[FUNCTION_LIGHT_ON] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_LIGHT_OFF] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_IS_LIGHT_ON] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_CONFIG] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_GET_CONFIG] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_ILLUMINANCE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_COLOR_TEMPERATURE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_ILLUMINANCE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_ILLUMINANCE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_COLOR_TEMPERATURE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_TRUE
  @response_expected[FUNCTION_GET_COLOR_TEMPERATURE_CALLBACK_PERIOD] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[CALLBACK_ILLUMINANCE] = RESPONSE_EXPECTED_ALWAYS_FALSE
  @response_expected[CALLBACK_COLOR_TEMPERATURE] = RESPONSE_EXPECTED_ALWAYS_FALSE
  @response_expected[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_COLOR] = 'S S S S'
  @callback_formats[CALLBACK_COLOR_REACHED] = 'S S S S'
  @callback_formats[CALLBACK_ILLUMINANCE] = 'L'
  @callback_formats[CALLBACK_COLOR_TEMPERATURE] = 'S'
end

Instance Method Details

#get_color ⇒ Object

Returns the measured color of the sensor. The values have a range of 0 to 65535.

The red ®, green (g), blue (b) and clear © colors are measured with four different photodiodes that are responsive at different wavelengths:

.. image

/Images/Bricklets/bricklet_color_wavelength_chart_600.jpg

:scale: 100 %
:alt: Chart Responsivity / Wavelength
:align: center
:target: ../../_images/Bricklets/bricklet_color_wavelength_chart_600.jpg

If you want to get the color periodically, it is recommended to use the callback CALLBACK_COLOR and set the period with BrickletColor#set_color_callback_period.



141
142
143
 
# File 'lib/tinkerforge/bricklet_color.rb', line 141

def get_color
  send_request(FUNCTION_GET_COLOR, [], '', 8, 'S S S S')
end

#get_color_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_color_callback_period.



157
158
159
 
# File 'lib/tinkerforge/bricklet_color.rb', line 157

def get_color_callback_period
  send_request(FUNCTION_GET_COLOR_CALLBACK_PERIOD, [], '', 4, 'L')
end

#get_color_callback_threshold ⇒ Object

Returns the threshold as set by BrickletColor#set_color_callback_threshold.



179
180
181
 
# File 'lib/tinkerforge/bricklet_color.rb', line 179

def get_color_callback_threshold
  send_request(FUNCTION_GET_COLOR_CALLBACK_THRESHOLD, [], '', 17, 'k S S S S S S S S')
end

#get_color_temperature ⇒ Object

Returns the color temperature in Kelvin.

To get a correct color temperature measurement make sure that the color values themself are not saturated. The color value (R, G or B) is saturated if it is equal to the maximum value of 65535. In that case you have to reduce the gain, see BrickletColor#set_config.



276
277
278
 
# File 'lib/tinkerforge/bricklet_color.rb', line 276

def get_color_temperature
  send_request(FUNCTION_GET_COLOR_TEMPERATURE, [], '', 2, 'S')
end

#get_color_temperature_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_color_temperature_callback_period.



308
309
310
 
# File 'lib/tinkerforge/bricklet_color.rb', line 308

def get_color_temperature_callback_period
  send_request(FUNCTION_GET_COLOR_TEMPERATURE_CALLBACK_PERIOD, [], '', 4, 'L')
end

#get_config ⇒ Object

Returns the configuration as set by BrickletColor#set_config.



253
254
255
 
# File 'lib/tinkerforge/bricklet_color.rb', line 253

def get_config
  send_request(FUNCTION_GET_CONFIG, [], '', 2, 'C C')
end

#get_debounce_period ⇒ Object

Returns the debounce period as set by BrickletColor#set_debounce_period.



199
200
201
 
# File 'lib/tinkerforge/bricklet_color.rb', line 199

def get_debounce_period
  send_request(FUNCTION_GET_DEBOUNCE_PERIOD, [], '', 4, 'L')
end

#get_identity ⇒ Object

Returns the UID, the UID where the Bricklet is connected to, the position, the hardware and firmware version as well as the device identifier.

The position can be ‘a’, ‘b’, ‘c’ or ‘d’.

The device identifier numbers can be found :ref:‘here <device_identifier>`. |device_identifier_constant|



320
321
322
 
# File 'lib/tinkerforge/bricklet_color.rb', line 320

def get_identity
  send_request(FUNCTION_GET_IDENTITY, [], '', 25, 'Z8 Z8 k C3 C3 S')
end

#get_illuminance ⇒ Object

Returns the illuminance affected by the gain and integration time as

set by BrickletColor#set_config. To get the illuminance in Lux apply this formula

lux = illuminance * 700 / gain / integration_time

To get a correct illuminance measurement make sure that the color values themself are not saturated. The color value (R, G or B) is saturated if it is equal to the maximum value of 65535. In that case you have to reduce the gain, see BrickletColor#set_config.



266
267
268
 
# File 'lib/tinkerforge/bricklet_color.rb', line 266

def get_illuminance
  send_request(FUNCTION_GET_ILLUMINANCE, [], '', 4, 'L')
end

#get_illuminance_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_illuminance_callback_period.



292
293
294
 
# File 'lib/tinkerforge/bricklet_color.rb', line 292

def get_illuminance_callback_period
  send_request(FUNCTION_GET_ILLUMINANCE_CALLBACK_PERIOD, [], '', 4, 'L')
end

#is_light_on ⇒ Object

Returns the state of the LED. Possible values are:

  • 0: On

  • 1: Off



217
218
219
 
# File 'lib/tinkerforge/bricklet_color.rb', line 217

def is_light_on
  send_request(FUNCTION_IS_LIGHT_ON, [], '', 1, 'C')
end

#light_off ⇒ Object

Turns the LED off.



209
210
211
 
# File 'lib/tinkerforge/bricklet_color.rb', line 209

def light_off
  send_request(FUNCTION_LIGHT_OFF, [], '', 0, '')
end

#light_on ⇒ Object

Turns the LED on.



204
205
206
 
# File 'lib/tinkerforge/bricklet_color.rb', line 204

def light_on
  send_request(FUNCTION_LIGHT_ON, [], '', 0, '')
end

#register_callback(id, &block) ⇒ Object

Registers a callback with ID id to the block block.



325
326
327
328
 
# File 'lib/tinkerforge/bricklet_color.rb', line 325

def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end

#set_color_callback_period(period) ⇒ Object

Sets the period in ms with which the CALLBACK_COLOR callback is triggered periodically. A value of 0 turns the callback off.

CALLBACK_COLOR is only triggered if the color has changed since the last triggering.

The default value is 0.



152
153
154
 
# File 'lib/tinkerforge/bricklet_color.rb', line 152

def set_color_callback_period(period)
  send_request(FUNCTION_SET_COLOR_CALLBACK_PERIOD, [period], 'L', 0, '')
end

#set_color_callback_threshold(option, min_r, max_r, min_g, max_g, min_b, max_b, min_c, max_c) ⇒ Object

Sets the thresholds for the CALLBACK_COLOR_REACHED callback.

The following options are possible:

"Option", "Description"

"'x'",    "Callback is turned off"
"'o'",    "Callback is triggered when the temperature is *outside* the min and max values"
"'i'",    "Callback is triggered when the temperature is *inside* the min and max values"
"'<'",    "Callback is triggered when the temperature is smaller than the min value (max is ignored)"
"'>'",    "Callback is triggered when the temperature is greater than the min value (max is ignored)"

The default value is (‘x’, 0, 0, 0, 0, 0, 0, 0, 0).



174
175
176
 
# File 'lib/tinkerforge/bricklet_color.rb', line 174

def set_color_callback_threshold(option, min_r, max_r, min_g, max_g, min_b, max_b, min_c, max_c)
  send_request(FUNCTION_SET_COLOR_CALLBACK_THRESHOLD, [option, min_r, max_r, min_g, max_g, min_b, max_b, min_c, max_c], 'k S S S S S S S S', 0, '')
end

#set_color_temperature_callback_period(period) ⇒ Object

Sets the period in ms with which the CALLBACK_COLOR_TEMPERATURE callback is triggered periodically. A value of 0 turns the callback off.

CALLBACK_COLOR_TEMPERATURE is only triggered if the color temperature has changed since the last triggering.

The default value is 0.



303
304
305
 
# File 'lib/tinkerforge/bricklet_color.rb', line 303

def set_color_temperature_callback_period(period)
  send_request(FUNCTION_SET_COLOR_TEMPERATURE_CALLBACK_PERIOD, [period], 'L', 0, '')
end

#set_config(gain, integration_time) ⇒ Object

Sets the configuration of the sensor. Gain and integration time can be configured in this way.

For configuring the gain:

  • 0: 1x Gain

  • 1: 4x Gain

  • 2: 16x Gain

  • 3: 60x Gain

For configuring the integration time:

  • 0: 2.4ms

  • 1: 24ms

  • 2: 101ms

  • 3: 154ms

  • 4: 700ms

Increasing the gain enables the sensor to detect a color from a higher distance.

The integration time provides a trade-off between conversion time and accuracy. With a longer integration time the values read will be more accurate but it will take longer time to get the conversion results.

The default values are 60x gain and 154ms integration time.



248
249
250
 
# File 'lib/tinkerforge/bricklet_color.rb', line 248

def set_config(gain, integration_time)
  send_request(FUNCTION_SET_CONFIG, [gain, integration_time], 'C C', 0, '')
end

#set_debounce_period(debounce) ⇒ Object

Sets the period in ms with which the threshold callback

  • CALLBACK_COLOR_REACHED

is triggered, if the threshold

  • BrickletColor#set_color_callback_threshold

keeps being reached.

The default value is 100.



194
195
196
 
# File 'lib/tinkerforge/bricklet_color.rb', line 194

def set_debounce_period(debounce)
  send_request(FUNCTION_SET_DEBOUNCE_PERIOD, [debounce], 'L', 0, '')
end

#set_illuminance_callback_period(period) ⇒ Object

Sets the period in ms with which the CALLBACK_ILLUMINANCE callback is triggered periodically. A value of 0 turns the callback off.

CALLBACK_ILLUMINANCE is only triggered if the illuminance has changed since the last triggering.

The default value is 0.



287
288
289
 
# File 'lib/tinkerforge/bricklet_color.rb', line 287

def set_illuminance_callback_period(period)
  send_request(FUNCTION_SET_ILLUMINANCE_CALLBACK_PERIOD, [period], 'L', 0, '')
end