Arduino RGB Sensor Protocol

OzRgbSensor libraries can read the brightness of the 3 basic colors: Red, Green and Blue. Most RGB reader device can light the surface with a few white LEDs. On some boards you can turn the LEDs on or off. The libraries support TCS3200 and TCS3210 chips, so the only thing that matters is that the board contains one of these chips. These chips send PWM signals for each color where the HIGH and LOW voltage values have equal length. This length is transferred to Ozeki 10 in microseconds. It is called pulse length.

I. 'Welcome' event from microcontroller

Example

c=welcome&id=knRJ67&type=OzRgbSensor&pos=1&name=MyRgbSensor&t=1

Parameters

Parameter Type Range Functionality
c String 'welcome' Identifies the welcome message.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
type String 'OzRgbSensor' Determines the type of the device.
pos Byte 0-255 Determines the position of the device on the list of the ID manager of the microcontroller. Please make sure there are no other devices in the same position.
name String e.g. 'MyRgbSensor' This is how the device will appear in Ozeki 10.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.


II. Commands to microcontroller

'getvalue' command

You can request the RGB pulse length in microsecs. It is measured by the RGB sensor.

Example

c=getvalue&id=knRJ67&t=0

Parameters

Parameter Type Range Functionality
c String 'getvalue' Identifies the command.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of commands sent. Counts from 0 to 255 then from 0 again.

Response

Responds the pulse length of each color. Ozeki 10 will remap it from 0 to 255 after calibration.
Both HIGH and LOW pulse length is equal for each color.

Example

c=getvalue_resp&r=80&g=400&b=934&id=knRJ67&t=1

Parameters

Parameter Type Range Functionality
c String 'getvalue_resp' Identifies the response
r Int 0 - 65535 The pulse length of the red color recognised by the sensor. It is measured in microsecs.
g Int 0 - 65535 The pulse length of the green color recognised by the sensor. It is measured in microsecs.
b Int 0 - 65535 The pulse length of the blue color recognised by the sensor. It is measured in microsecs.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.


'repchange' command

Sets threshold compared to the last measured r, g or b pulse length value, so a 'change' event is sent everytime it passes the threshold in one of the directions. If it is set to 0 it is turned off.

Example

//set all 3 thresholds
c=repchange&r=165&g=134&b=85&id=knRJ67&t=2
//set red threshold only
c=repchange&r=165&id=knRJ67&t=2
//set green threshold only
c=repchange&g=134&id=knRJ67&t=2
//set blue threshold only
c=repchange&r=0&g=0&b=85&id=knRJ67&t=2

Parameters

Parameter Type Range Functionality
c String 'repchange' Identifies the command.
r * Int 0 - 65535 Sets measurement threshold value for red pulse length. If 0, then the trigger to 'change' event is OFF. It stays unchanged if this value is unprovided.
g * Int 0 - 65535 Sets measurement threshold value for green pulse length. If 0, then the trigger to 'change' event is OFF. It stays unchanged if this value is unprovided.
b * Int 0 - 65535 Sets measurement threshold value for blue pulse length. If 0, then the trigger to 'change' event is OFF. It stays unchanged if this value is unprovided.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of commands sent. Counts from 0 to 255 then from 0 again.
* optional parameter

Response

Responds if the value of the threshold trigger has been set.

Example

//all 3 thresholds has been set
c=repchange_resp&r=165&g=134&b=85&id=knRJ67&t=3
//red threshold has been set
c=repchange_resp&r=165&g=0&b=0&id=knRJ67&t=3
//green threshold has been set
c=repchange_resp&r=0&g=134&b=0&id=knRJ67&t=3
//blue threshold has been set
c=repchange_resp&r=0&g=0&b=85&id=knRJ67&t=3

Parameters

Parameter Type Range Functionality
c String 'repchange_resp' Identifies the response.
r Int 0 - 65535 Red's measurement threshold value.
If 0, the trigger is OFF.
g Int 0 - 65535 Green's measurement threshold value.
If 0, the trigger is OFF.
b Int 0 - 65535 Blue's measurement threshold value.
If 0, the trigger is OFF.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.


'repabove' command

Triggers an 'above' event everytime the r, g or b pulse length value goes above the value set in this command.

Example

//set above event for 3 colors
c=repabove&r=850&g=1040&b=960&id=knRJ67&t=3
//set above event for red
c=repabove&r=850&id=knRJ67&t=3
//set above event for green
c=repabove&g=1040&id=knRJ67&t=3
//set above event for blue
c=repabove&r=0&g=0&b=960&id=knRJ67&t=3

Parameters

Parameter Type Range Functionality
c String 'repabove' Identifies the command.
r * Int 0 - 65535 If the rate of red crosses this value than an 'above' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
g * Int 0 - 65535 If the rate of green crosses this value than an 'above' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
b * Int 0 - 65535 If the rate of blue crosses this value than an 'above' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of commands sent. Counts from 0 to 255 then from 0 again.
* optional parameter

Response

Responds if the value of the above trigger has been set.

Example

//above event has been set for 3 colors
c=repabove_resp&r=850&g=1040&b=960&id=knRJ67&t=4
//above event has been set for red
c=repabove_resp&r=850&g=0&b=0id=knRJ67&t=4
//above event has been set for green
c=repabove_resp&r=0&g=1040&b=0&id=knRJ67&t=4
//above event has been set for blue
c=repabove_resp&r=0&g=0&b=960&id=knRJ67&t=4

Parameters

Parameter Type Range Functionality
c String 'repabove_resp' Identifies the response.
r Int 0 - 65535 Red's trigger value for the 'above' event.
If 0, the trigger is OFF.
g Int 0 - 65535 Green's trigger value for the 'above' event.
If 0, the trigger is OFF.
b Int 0 - 65535 Blue's trigger value for the 'above' event.
If 0, the trigger is OFF.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.


'repbelow' command

Triggers a 'below' event everytime the r, g or b pulse length value goes below the value set in this command.

Example

//set below event for 3 colors
c=repbelow&r=340&g=230&b=410&id=knRJ67&t=4
//set below event for red
c=repbelow&r=340&id=knRJ67&t=4
//set below event for green
c=repbelow&g=230&id=knRJ67&t=4
//set below event for blue
c=repbelow&r=0&g=0&b=410&id=knRJ67&t=4

Parameters

Parameter Type Range Functionality
c String 'repbelow' Identifies the command.
r * Int 0 - 65535 If the rate of red crosses this value than a 'below' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
g * Int 0 - 65535 If the rate of green crosses this value than a 'below' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
b * Int 0 - 65535 If the rate of blue crosses this value than a 'below' event is triggered. If 0, then trigger is OFF. It stays unchanged if this value is unprovided.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of commands sent. Counts from 0 to 255 then from 0 again.
* optional parameter

Response

Responds if the value of the below trigger has been set.

Example

//below event for 3 colors has been set
c=repbelow_resp&r=340&g=230&b=410&id=knRJ67&t=5
//below event for red has been set
c=repbelow_resp&r=340&g=0&b=0&id=knRJ67&t=5
//below event for green has been set
c=repbelow_resp&r=0&g=230&b=0id=knRJ67&t=5
//below event for blue has been set
c=repbelow_resp&r=0&g=0&b=410&id=knRJ67&t=5

Parameters

Parameter Type Range Functionality
c String 'repbelow_resp' Identifies the response.
r Int 0 - 65535 Red's trigger value for the 'below' event.
If 0, the trigger is OFF.
g Int 0 - 65535 Green's trigger value for the 'below' event.
If 0, the trigger is OFF.
b Int 0 - 65535 Blue's trigger value for the 'below' event.
If 0, the trigger is OFF.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.


III. Event from microcontroller

'change' event

This event is called if the red, green or blue pulse length value has changed more then the threshold set with the 'repchange' command. This event shows the current value of the RGB sensor.

Example

//If any of the 3 colors changes more then threshold
c=change&r=80&g=950&b=934&id=knRJ67&t=6

Parameters

Parameter Type Range Functionality
c String 'change' Identifies the event.
r Int 0 - 65535 Red pulse length. It is measured after one of the color rates has passed the threshold.
g Int 0 - 65535 Green pulse length. It is measured after one of the color rates has passed the threshold.
b Int 0 - 65535 Blue pulse length. It is measured after one of the color rates has passed the threshold.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.

'above' event

This event is called if the red, green or blue pulse length has crossed above a preset value which you can set with the 'repabove' command.

Example

//b=180 went over the set value
c=above&r=80&g=400&b=1180&id=knRJ67&t=7

Parameters

Parameter Type Range Functionality
c String 'above' Identifies the event.
r Int 0 - 65535 Red pulse length. It is measured after one of the color rates crossed 'above' the set value.
g Int 0 - 65535 Green pulse length. It is measured after one of the color rates crossed 'above' the set value.
b Int 0 - 65535 Blue pulse length. It is measured after one of the color rates crossed 'above' the set value.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.

'below' event

This event is called if the red, green or blue value has crossed below a preset value which you can set with the 'repbelow' command.

Example

//r=22 gone below the set value
c=below&r=80&g=400&b=160&id=knRJ67&t=8

Parameters

Parameter Type Range Functionality
c String 'below' Identifies the event.
r Int 0 - 65535 Red pulse length. It is measured after one of the color rates crossed 'below' the set value.
g Int 0 - 65535 Green pulse length. It is measured after one of the color rates crossed 'below' the set value.
b Int 0 - 65535 Blue pulse length. It is measured after one of the color rates crossed 'below' the set value.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the device which is chosen by the microcontroller.
t Byte 0-255 Counts the number of events and responses sent combined. Counts from 0 to 255 then from 0 again.

More information