class Tinkerforge::BrickletColor

Measures color (RGB value), illuminance and color temperature

Constants

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.

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.

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.

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.

Public Class Methods

new(uid, ipcon) click to toggle source

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

Calls superclass method
# File lib/tinkerforge/bricklet_color.rb, line 91
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

Public Instance Methods

get_color() click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 139
def get_color
  check_validity

  send_request FUNCTION_GET_COLOR, [], '', 16, 'S S S S'
end
get_color_callback_period() click to toggle source

Returns the period as set by BrickletColor#set_color_callback_period.

# File lib/tinkerforge/bricklet_color.rb, line 157
def get_color_callback_period
  check_validity

  send_request FUNCTION_GET_COLOR_CALLBACK_PERIOD, [], '', 12, 'L'
end
get_color_callback_threshold() click to toggle source

Returns the threshold as set by BrickletColor#set_color_callback_threshold.

# File lib/tinkerforge/bricklet_color.rb, line 181
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() click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 292
def get_color_temperature
  check_validity

  send_request FUNCTION_GET_COLOR_TEMPERATURE, [], '', 10, 'S'
end
get_color_temperature_callback_period() click to toggle source

Returns the period as set by BrickletColor#set_color_temperature_callback_period.

# File lib/tinkerforge/bricklet_color.rb, line 328
def get_color_temperature_callback_period
  check_validity

  send_request FUNCTION_GET_COLOR_TEMPERATURE_CALLBACK_PERIOD, [], '', 12, 'L'
end
get_config() click to toggle source

Returns the configuration as set by BrickletColor#set_config.

# File lib/tinkerforge/bricklet_color.rb, line 265
def get_config
  check_validity

  send_request FUNCTION_GET_CONFIG, [], '', 10, 'C C'
end
get_debounce_period() click to toggle source

Returns the debounce period as set by BrickletColor#set_debounce_period.

# File lib/tinkerforge/bricklet_color.rb, line 203
def get_debounce_period
  check_validity

  send_request FUNCTION_GET_DEBOUNCE_PERIOD, [], '', 12, 'L'
end
get_identity() click to toggle source

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|

# File lib/tinkerforge/bricklet_color.rb, line 344
def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
end
get_illuminance() click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 280
def get_illuminance
  check_validity

  send_request FUNCTION_GET_ILLUMINANCE, [], '', 12, 'L'
end
get_illuminance_callback_period() click to toggle source

Returns the period as set by BrickletColor#set_illuminance_callback_period.

# File lib/tinkerforge/bricklet_color.rb, line 310
def get_illuminance_callback_period
  check_validity

  send_request FUNCTION_GET_ILLUMINANCE_CALLBACK_PERIOD, [], '', 12, 'L'
end
is_light_on() click to toggle source

Returns the state of the LED. Possible values are:

  • 0: On

  • 1: Off

# File lib/tinkerforge/bricklet_color.rb, line 227
def is_light_on
  check_validity

  send_request FUNCTION_IS_LIGHT_ON, [], '', 9, 'C'
end
light_off() click to toggle source

Turns the LED off.

# File lib/tinkerforge/bricklet_color.rb, line 217
def light_off
  check_validity

  send_request FUNCTION_LIGHT_OFF, [], '', 8, ''
end
light_on() click to toggle source

Turns the LED on.

# File lib/tinkerforge/bricklet_color.rb, line 210
def light_on
  check_validity

  send_request FUNCTION_LIGHT_ON, [], '', 8, ''
end
register_callback(id, &block) click to toggle source

Registers a callback with ID id to the block block.

# File lib/tinkerforge/bricklet_color.rb, line 349
def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end
set_color_callback_period(period) click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 150
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) click to toggle source

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)"
# 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)
  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) click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 321
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) click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 258
def set_config(gain, integration_time)
  check_validity

  send_request FUNCTION_SET_CONFIG, [gain, integration_time], 'C C', 8, ''
end
set_debounce_period(debounce) click to toggle source

Sets the period with which the threshold callback

is triggered, if the threshold

keeps being reached.

# File lib/tinkerforge/bricklet_color.rb, line 196
def set_debounce_period(debounce)
  check_validity

  send_request FUNCTION_SET_DEBOUNCE_PERIOD, [debounce], 'L', 8, ''
end
set_illuminance_callback_period(period) click to toggle source

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.

# File lib/tinkerforge/bricklet_color.rb, line 303
def set_illuminance_callback_period(period)
  check_validity

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