..
 #############################################################
 # This file was automatically generated on 2015-05-08.      #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################


:breadcrumbs: <a href="../../index.html">Home</a> / <a href="../../index.html#software-tcpip">Software</a> / TCP/IP - Color Bricklet

.. |device_identifier_constant| unicode:: 0xA0
   :trim:

.. _color_bricklet_tcpip:

TCP/IP - Color Bricklet
=======================

This is the description of the :ref:`TCP/IP protocol <llproto_tcpip>` for the :ref:`Color Bricklet <color_bricklet>`. General information and technical
specifications for the Color Bricklet are summarized in its :ref:`hardware description
<color_bricklet_description>`.

.. _color_bricklet_tcpip_api:

API
---

A general description of the TCP/IP protocol structure can be found
:ref:`here <llproto_tcpip>`.




Basic Functions
^^^^^^^^^^^^^^^



.. tcpip:function:: BrickletColor.get_color

 :functionid: 1
 :emptyrequest: empty payload

 :response r: uint16
 :response g: uint16
 :response b: uint16
 :response c: uint16

 Returns the measured color of the sensor. The values
 have a range of 0 to 65535.
 
 The red (r), green (g), blue (b) and clear (c) 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 :tcpip:func:`CALLBACK_COLOR <BrickletColor.CALLBACK_COLOR>` and set the period with 
 :tcpip:func:`set_color_callback_period <BrickletColor.set_color_callback_period>`.
 
.. tcpip:function:: BrickletColor.light_on

 :functionid: 10
 :emptyrequest: empty payload

 :noresponse: no response

 Turns the LED on.
 
.. tcpip:function:: BrickletColor.light_off

 :functionid: 11
 :emptyrequest: empty payload

 :noresponse: no response

 Turns the LED off.
 
.. tcpip:function:: BrickletColor.is_light_on

 :functionid: 12
 :emptyrequest: empty payload

 :response light: uint8

 Returns the state of the LED. Possible values are:
 
 * 0: On
 * 1: Off
 
.. tcpip:function:: BrickletColor.set_config

 :functionid: 13
 :request gain: uint8
 :request integration_time: uint8

 :noresponse: no response

 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.
 
.. tcpip:function:: BrickletColor.get_config

 :functionid: 14
 :emptyrequest: empty payload

 :response gain: uint8
 :response integration_time: uint8

 Returns the configuration as set by :tcpip:func:`set_config <BrickletColor.set_config>`.
 
.. tcpip:function:: BrickletColor.get_illuminance

 :functionid: 15
 :emptyrequest: empty payload

 :response illuminance: uint32

 Returns the illuminance affected by the gain and integration time as
 set by :tcpip:func:`set_config <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 :tcpip:func:`set_config <BrickletColor.set_config>`.
 
.. tcpip:function:: BrickletColor.get_color_temperature

 :functionid: 16
 :emptyrequest: empty payload

 :response color_temperature: uint16

 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 :tcpip:func:`set_config <BrickletColor.set_config>`.
 


Advanced Functions
^^^^^^^^^^^^^^^^^^

.. tcpip:function:: BrickletColor.get_identity

 :functionid: 255
 :emptyrequest: empty payload

 :response uid: char[8]
 :response connected_uid: char[8]
 :response position: char
 :response hardware_version: uint8[3]
 :response firmware_version: uint8[3]
 :response device_identifier: uint16

 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|
 


Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. tcpip:function:: BrickletColor.set_color_callback_period

 :functionid: 2
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_COLOR <BrickletColor.CALLBACK_COLOR>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_COLOR <BrickletColor.CALLBACK_COLOR>` is only triggered if the color has changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletColor.get_color_callback_period

 :functionid: 3
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_color_callback_period <BrickletColor.set_color_callback_period>`.
 
.. tcpip:function:: BrickletColor.set_color_callback_threshold

 :functionid: 4
 :request option: char
 :request min_r: uint16
 :request max_r: uint16
 :request min_g: uint16
 :request max_g: uint16
 :request min_b: uint16
 :request max_b: uint16
 :request min_c: uint16
 :request max_c: uint16

 :noresponse: no response

 Sets the thresholds for the :tcpip:func:`CALLBACK_COLOR_REACHED <BrickletColor.CALLBACK_COLOR_REACHED>` callback. 
 
 The following options are possible:
 
 .. csv-table::
  :header: "Option", "Description"
  :widths: 10, 100
 
  "'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).
 
.. tcpip:function:: BrickletColor.get_color_callback_threshold

 :functionid: 5
 :emptyrequest: empty payload

 :response option: char
 :response min_r: uint16
 :response max_r: uint16
 :response min_g: uint16
 :response max_g: uint16
 :response min_b: uint16
 :response max_b: uint16
 :response min_c: uint16
 :response max_c: uint16

 Returns the threshold as set by :tcpip:func:`set_color_callback_threshold <BrickletColor.set_color_callback_threshold>`.
 
.. tcpip:function:: BrickletColor.set_debounce_period

 :functionid: 6
 :request debounce: uint32

 :noresponse: no response

 Sets the period in ms with which the threshold callback
 
 * :tcpip:func:`CALLBACK_COLOR_REACHED <BrickletColor.CALLBACK_COLOR_REACHED>`
 
 is triggered, if the threshold
 
 * :tcpip:func:`set_color_callback_threshold <BrickletColor.set_color_callback_threshold>`
 
 keeps being reached.
 
 The default value is 100.
 
.. tcpip:function:: BrickletColor.get_debounce_period

 :functionid: 7
 :emptyrequest: empty payload

 :response debounce: uint32

 Returns the debounce period as set by :tcpip:func:`set_debounce_period <BrickletColor.set_debounce_period>`.
 
.. tcpip:function:: BrickletColor.set_illuminance_callback_period

 :functionid: 17
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_ILLUMINANCE <BrickletColor.CALLBACK_ILLUMINANCE>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_ILLUMINANCE <BrickletColor.CALLBACK_ILLUMINANCE>` is only triggered if the illuminance has changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletColor.get_illuminance_callback_period

 :functionid: 18
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_illuminance_callback_period <BrickletColor.set_illuminance_callback_period>`.
 
.. tcpip:function:: BrickletColor.set_color_temperature_callback_period

 :functionid: 19
 :request period: uint32

 :noresponse: no response

 Sets the period in ms with which the :tcpip:func:`CALLBACK_COLOR_TEMPERATURE <BrickletColor.CALLBACK_COLOR_TEMPERATURE>` callback is triggered
 periodically. A value of 0 turns the callback off.
 
 :tcpip:func:`CALLBACK_COLOR_TEMPERATURE <BrickletColor.CALLBACK_COLOR_TEMPERATURE>` is only triggered if the color temperature has changed since the
 last triggering.
 
 The default value is 0.
 
.. tcpip:function:: BrickletColor.get_color_temperature_callback_period

 :functionid: 20
 :emptyrequest: empty payload

 :response period: uint32

 Returns the period as set by :tcpip:func:`set_color_temperature_callback_period <BrickletColor.set_color_temperature_callback_period>`.
 


.. _color_bricklet_tcpip_callbacks:

Callbacks
^^^^^^^^^

.. tcpip:function:: BrickletColor.CALLBACK_COLOR

 :functionid: 8

 :response r: uint16
 :response g: uint16
 :response b: uint16
 :response c: uint16


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_color_callback_period <BrickletColor.set_color_callback_period>`. The response value is the color
 of the sensor as RGBC.
 
 :tcpip:func:`CALLBACK_COLOR <BrickletColor.CALLBACK_COLOR>` is only triggered if the color has changed since the
 last triggering.
 
.. tcpip:function:: BrickletColor.CALLBACK_COLOR_REACHED

 :functionid: 9

 :response r: uint16
 :response g: uint16
 :response b: uint16
 :response c: uint16


 This callback is triggered when the threshold as set by
 :tcpip:func:`set_color_callback_threshold <BrickletColor.set_color_callback_threshold>` is reached.
 The response value 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 :tcpip:func:`set_debounce_period <BrickletColor.set_debounce_period>`.
 
.. tcpip:function:: BrickletColor.CALLBACK_ILLUMINANCE

 :functionid: 21

 :response illuminance: uint32


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_illuminance_callback_period <BrickletColor.set_illuminance_callback_period>`. The response value is the illuminance.
 See :tcpip:func:`get_illuminance <BrickletColor.get_illuminance>` for how to interpret this value.
 
 :tcpip:func:`CALLBACK_ILLUMINANCE <BrickletColor.CALLBACK_ILLUMINANCE>` is only triggered if the illuminance has changed since the
 last triggering.
 
.. tcpip:function:: BrickletColor.CALLBACK_COLOR_TEMPERATURE

 :functionid: 22

 :response color_temperature: uint16


 This callback is triggered periodically with the period that is set by
 :tcpip:func:`set_color_temperature_callback_period <BrickletColor.set_color_temperature_callback_period>`. The response value is the 
 color temperature in Kelvin.
 
 :tcpip:func:`CALLBACK_COLOR_TEMPERATURE <BrickletColor.CALLBACK_COLOR_TEMPERATURE>` is only triggered if the color temperature has 
 changed since the last triggering.
 


