Ctrl+K

EVNColourSensor

EVNColourSensor#

This class provides the following features and functionalities for our Colour Sensor Standard Peripheral (TCS34725 IC):

  • Reflected Red, Green, Blue (RGB) & Clear Light Measurements

  • Non-Blocking & Blocking Read Functions

  • Configurable Gain and Integration Times

  • Built-in I2C Port Selection and De-selection

Note

This class does I2C port selection automatically, so users do not need to call setPort() using their EVNAlpha objects.

Wiring (I2C)#

Host

Peripheral

Description

–

VIN

Not Soldered

GND

GND

Ground (0V)

3V3

3V3

3.3V Power

SCL

SCL

I2C Serial Clock

SDA

SDA

I2C Serial Data

–

INT

Not Connected

–

LED

Not Soldered

Constructor#

class EVNColourSensor(uint8_t port, uint8_t integration_cycles = 1, gain gain = COLOUR_GAIN_X16)#

The listed default settings for the sensor are listed here. Refer to setGain() & setIntegrationTime() for more information.

Parameters

  • port – I2C port the sensor is connected to (1-16)

  • integration_cycles – Number of 2.4ms integration cycle for one reading. Defaults to 1

  • gain – Gain applied to readings. Defaults to COLOUR_GAIN_X16

Functions#

bool begin()

Initializes colour sensor. Call this function before using the other functions.

Returns

Boolean indicating whether the sensor was successfully initialized. If false is returned, all other functions will return 0.

Note

If begin() returns false, try checking your connections and I2C port number!

void setGain(gain gain)

Sets internal sensor gain applied to reading. Increasing gain widens the numerical range of readings at the cost of noise.

Parameters

gain –

Gain applied to readings

  • COLOUR_GAIN_X1 – 1x gain

  • COLOUR_GAIN_X4 – 4x gain

  • COLOUR_GAIN_X16 – 16x gain

  • COLOUR_GAIN_X60 – 60x gain

void setIntegrationCycles(uint8_t integration_cycles)

Sets the number of 2.4ms integration cycles used for 1 reading.

Integration Time = 2.4ms * Integration Cycles

Parameters

integration_cycles – Number of 2.4ms integration cycles for 1 reading (1-255)

Reading Raw RGBC Values#

uint16_t read(uint8_t component, bool blocking = true)

Returns raw reading for given component (Clear, Red, Green or Blue).

Parameters

  • component –

    RGBC Component to be returned

    • CLEAR

    • RED

    • GREEN

    • BLUE

  • blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw reading

uint16_t readClear(bool blocking = true)

Same as read(CLEAR, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Clear reading

uint16_t readRed(bool blocking = true)

Same as read(RED, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Red reading

uint16_t readGreen(bool blocking = true)

Same as read(GREEN, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Green reading

uint16_t readBlue(bool blocking = true)

Same as read(BLUE, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Blue reading

float readPct(bool blocking = true)

Returns raw reading for given component as a percentage (0 - 100).

Parameters

  • component –

    RGBC Component to be returned

    • CLEAR

    • RED

    • GREEN

    • BLUE

  • blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw reading in % (0 - 100)

float readClearPct(bool blocking = true)

Same as readPct(CLEAR, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Clear reading in % (0 - 100)

float readRedPct(bool blocking = true)

Same as readPct(RED, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Red reading in % (0 - 100)

float readGreenPct(bool blocking = true)

Same as readPct(GREEN, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Green reading in % (0 - 100)

float readBluePct(bool blocking = true)

Same as readPct(BLUE, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

raw Blue reading in % (0 - 100)

Reading Normalised RGBC Values#

When you read the raw RGBC values, you may not have a reading of 0 on black surfaces or a maximum reading on white.

Instead, the readings will usually range from a low (but non-zero) to a high (but non-max) value.

Normalisation is the process of converting raw readings such that they range from 0 to 1 instead.

Normalised Reading = (Raw Reading - Low) / (High - Low)

Before reading normalised values, you first need to call the setRange() function to set the low and high values for a given colour channel.

void setRange(uint8_t component, uint16_t low, uint16_t high)

Set the range of raw values for given colour component.

If this function is not called for a given colour component, readNorm() for that colour component will return 0.

Parameters

  • component –

    RGBC Component to be set range for

    • CLEAR

    • RED

    • GREEN

    • BLUE

  • low – lower bound of readings for colour component

  • high – upper bound of readings for colour component

void setClearRange(uint16_t low, uint16_t high)

Same as setRange(CLEAR, low, high)

Parameters

  • low – lower bound of Clear readings

  • high – upper bound of Clear readings

void setRedRange(uint16_t low, uint16_t high)

Same as setRange(RED, low, high)

Parameters

  • low – lower bound of Red readings

  • high – upper bound of Red readings

void setGreenRange(uint16_t low, uint16_t high)

Same as setRange(GREEN, low, high)

Parameters

  • low – lower bound of Green readings

  • high – upper bound of Green readings

void setBlueRange(uint16_t low, uint16_t high)

Same as setRange(BLUE, low, high)

Parameters

  • low – lower bound of Blue readings

  • high – upper bound of Blue readings

After calling these functions, you can use the readNorm() function to read normalised readings.

float readNorm(uint8_t component, bool blocking = true)

Returns normalised reading for given colour component in % (0 - 100)

Parameters

  • component –

    RGBC Component to be returned

    • CLEAR

    • RED

    • GREEN

    • BLUE

  • blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

normalised reading in % (0 - 100)

float readClearNorm(bool blocking = true)

Same as readNorm(CLEAR, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

normalised Clear reading in % (0 - 100)

float readRedNorm(bool blocking = true)

Same as readNorm(RED, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

normalised Red reading in % (0 - 100)

float readGreenNorm(bool blocking = true)

Same as readNorm(GREEN, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

normalised Green reading in % (0 - 100)

float readBlueNorm(bool blocking = true)

Same as readNorm(BLUE, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

normalised Blue reading in % (0 - 100)

Reading HSV Values#

By default, raw readings are used for HSV Colourspace conversion.

One can set HSV conversion to use normalised readings using useNormForHSV().

void useNormForHSV(bool enable)
Parameters

enable – Whether to use normalised readings for HSV conversion

float readHSV(uint8_t component, bool blocking = true)

Returns given component of reading when converted to HSV (Hue, Saturation or Value)

Parameters

  • component –

    HSV Component to be returned

    • HUE

    • SAT

    • VAL

  • blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

  • HUE: Hue component of reading in degrees (0-360)

  • SAT: Saturation component of reading in % (0-100)

  • VAL: Value component of reading in % (0-100)

float readHue(bool blocking = true)

Same as readHSV(HUE, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

Hue component of reading in degrees (0-360)

float readSaturation(bool blocking = true)

Same as readHSV(SAT, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

Saturation component of reading in % (0-100)

float readValue(bool blocking = true)

Same as readHSV(VAL, blocking)

Parameters

blocking – Block function from returning a value until a new reading is obtained. Defaults to true

Returns

Value component of reading in % (0-100)

Contents