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.

The CALLBACK_COLOR callback 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.

The CALLBACK_ILLUMINANCE callback 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.

The CALLBACK_COLOR_TEMPERATURE callback 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::DEVICE_IDENTIFIER_CHECK_MATCH, Device::DEVICE_IDENTIFIER_CHECK_MISMATCH, Device::DEVICE_IDENTIFIER_CHECK_PENDING, 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, #high_level_callbacks, #registered_callbacks, #replaced, #uid

Instance Method Summary collapse

Methods inherited from Device

#check_validity, #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.



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 92

def initialize(uid, ipcon)
  super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME

  @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[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[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_COLOR] = [16, 'S S S S']
  @callback_formats[CALLBACK_COLOR_REACHED] = [16, 'S S S S']
  @callback_formats[CALLBACK_ILLUMINANCE] = [12, 'L']
  @callback_formats[CALLBACK_COLOR_TEMPERATURE] = [10, 'S']

  @ipcon.add_device self
end

Instance Method Details

#get_color ⇒ Object

Returns the measured color of the sensor.

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_COLOR callback and set the period with BrickletColor#set_color_callback_period.



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

def get_color
  check_validity

  send_request FUNCTION_GET_COLOR, [], '', 16, 'S S S S'
end

#get_color_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_color_callback_period.



158
159
160
161
162
 
# File 'lib/tinkerforge/bricklet_color.rb', line 158

def get_color_callback_period
  check_validity

  send_request FUNCTION_GET_COLOR_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_color_callback_threshold ⇒ Object

Returns the threshold as set by BrickletColor#set_color_callback_threshold.



182
183
184
185
186
 
# File 'lib/tinkerforge/bricklet_color.rb', line 182

def get_color_callback_threshold
  check_validity

  send_request FUNCTION_GET_COLOR_CALLBACK_THRESHOLD, [], '', 25, 'k S S S S S S S S'
end

#get_color_temperature ⇒ Object

Returns the color temperature.

To get a correct color temperature measurement make sure that the color values themselves 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.



293
294
295
296
297
 
# File 'lib/tinkerforge/bricklet_color.rb', line 293

def get_color_temperature
  check_validity

  send_request FUNCTION_GET_COLOR_TEMPERATURE, [], '', 10, 'S'
end

#get_color_temperature_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_color_temperature_callback_period.



329
330
331
332
333
 
# File 'lib/tinkerforge/bricklet_color.rb', line 329

def get_color_temperature_callback_period
  check_validity

  send_request FUNCTION_GET_COLOR_TEMPERATURE_CALLBACK_PERIOD, [], '', 12, 'L'
end

#get_config ⇒ Object

Returns the configuration as set by BrickletColor#set_config.



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

def get_config
  check_validity

  send_request FUNCTION_GET_CONFIG, [], '', 10, 'C C'
end

#get_debounce_period ⇒ Object

Returns the debounce period as set by BrickletColor#set_debounce_period.



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

def get_debounce_period
  check_validity

  send_request FUNCTION_GET_DEBOUNCE_PERIOD, [], '', 12, '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’, ‘d’, ‘e’, ‘f’, ‘g’ or ‘h’ (Bricklet Port). A Bricklet connected to an :ref:‘Isolator Bricklet <isolator_bricklet>` is always at position ’z’.

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



345
346
347
 
# File 'lib/tinkerforge/bricklet_color.rb', line 345

def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, '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 themselves 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.



281
282
283
284
285
 
# File 'lib/tinkerforge/bricklet_color.rb', line 281

def get_illuminance
  check_validity

  send_request FUNCTION_GET_ILLUMINANCE, [], '', 12, 'L'
end

#get_illuminance_callback_period ⇒ Object

Returns the period as set by BrickletColor#set_illuminance_callback_period.



311
312
313
314
315
 
# File 'lib/tinkerforge/bricklet_color.rb', line 311

def get_illuminance_callback_period
  check_validity

  send_request FUNCTION_GET_ILLUMINANCE_CALLBACK_PERIOD, [], '', 12, 'L'
end

#is_light_on ⇒ Object

Returns the state of the LED. Possible values are:

  • 0: On

  • 1: Off



228
229
230
231
232
 
# File 'lib/tinkerforge/bricklet_color.rb', line 228

def is_light_on
  check_validity

  send_request FUNCTION_IS_LIGHT_ON, [], '', 9, 'C'
end

#light_off ⇒ Object

Turns the LED off.



218
219
220
221
222
 
# File 'lib/tinkerforge/bricklet_color.rb', line 218

def light_off
  check_validity

  send_request FUNCTION_LIGHT_OFF, [], '', 8, ''
end

#light_on ⇒ Object

Turns the LED on.



211
212
213
214
215
 
# File 'lib/tinkerforge/bricklet_color.rb', line 211

def light_on
  check_validity

  send_request FUNCTION_LIGHT_ON, [], '', 8, ''
end

#register_callback(id, &block) ⇒ Object

Registers a callback with ID id to the block block.



350
351
352
353
 
# File 'lib/tinkerforge/bricklet_color.rb', line 350

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

#set_color_callback_period(period) ⇒ Object

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

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



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

def set_color_callback_period(period)
  check_validity

  send_request FUNCTION_SET_COLOR_CALLBACK_PERIOD, [period], 'L', 8, ''
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)"



175
176
177
178
179
 
# File 'lib/tinkerforge/bricklet_color.rb', line 175

def set_color_callback_threshold(option, min_r, max_r, min_g, max_g, min_b, max_b, min_c, max_c)
  check_validity

  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', 8, ''
end

#set_color_temperature_callback_period(period) ⇒ Object

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

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



322
323
324
325
326
 
# File 'lib/tinkerforge/bricklet_color.rb', line 322

def set_color_temperature_callback_period(period)
  check_validity

  send_request FUNCTION_SET_COLOR_TEMPERATURE_CALLBACK_PERIOD, [period], 'L', 8, ''
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.



259
260
261
262
263
 
# File 'lib/tinkerforge/bricklet_color.rb', line 259

def set_config(gain, integration_time)
  check_validity

  send_request FUNCTION_SET_CONFIG, [gain, integration_time], 'C C', 8, ''
end

#set_debounce_period(debounce) ⇒ Object

Sets the period with which the threshold callback

  • CALLBACK_COLOR_REACHED

is triggered, if the threshold

  • BrickletColor#set_color_callback_threshold

keeps being reached.



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

def set_debounce_period(debounce)
  check_validity

  send_request FUNCTION_SET_DEBOUNCE_PERIOD, [debounce], 'L', 8, ''
end

#set_illuminance_callback_period(period) ⇒ Object

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

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



304
305
306
307
308
 
# File 'lib/tinkerforge/bricklet_color.rb', line 304

def set_illuminance_callback_period(period)
  check_validity

  send_request FUNCTION_SET_ILLUMINANCE_CALLBACK_PERIOD, [period], 'L', 8, ''
end