You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api.md
+128Lines changed: 128 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -774,3 +774,131 @@ Note that the `direction_any` event is always called *after* all other events
774
774
making it an ideal hook for things like display refreshing (as in the example
775
775
above).
776
776
777
+
- - -
778
+
## Light and colour sensor
779
+
780
+
The v2 Sense HAT includes a TCS34725 colour sensor that is capable of measuring the amount of Red, Green and Blue (RGB) in the incident light, as well as providing a Clear light (brightness) reading.
781
+
782
+
You can interact with the colour sensor through the `colour` (or `color`) attribute of the Sense HAT, which corresponds to a `ColourSensor` object.
783
+
784
+
The example below serves as an overview of how the colour sensor can be used, while the sections that follow provide additional details and explanations.
The `colour` (or `color`) property of the `ColourSensor` object is a 4-tuple containing the measured values for Red, Green and Blue (RGB), along with a Clear light value, which is a measure of brightness. Individual colour and light readings can also be obtained through the `red`, `green`, `blue` and `clear` properties of the `ColourSensor` object.
804
+
805
+
`ColourSensor` property | Returned type | Explanation
806
+
--- | --- | ---
807
+
`red` | int | The amount of incident red light, scaled to 0-256
808
+
`green` | int | The amount of incident green light, scaled to 0-256
809
+
`blue` | int | The amount of incident blue light, scaled to 0-256
810
+
`clear` | int | The amount of incident light (brightness), scaled to 0-256
811
+
`colour` | tuple | A 4-tuple containing the RGBC (Red, Green, Blue and Clear) sensor readings, each scaled to 0-256
812
+
813
+
These are all read-only properties; they cannot be set.
814
+
815
+
Note that, in the current implementation, the four values accessed through the `colour` property are retrieved through a single sensor reading. Obtaining these values through the `red`, `green`, `blue` and `clear` properties would require four separate readings.
816
+
817
+
---
818
+
### Gain
819
+
820
+
In sensors, the term "gain" can be understood as being synonymous to _sensitivity_. A higher gain setting means the output values will be greater for the same input.
821
+
822
+
There are four possible gain values for the colour sensor: `1`, `4`, `16` and `60`, with the default value being `1`. You can get or set the sensor gain through the `gain` property of the `ColourSensor` object. An attempt to set the gain to a value that is not valid will result in an `InvalidGainError` exception being raised.
823
+
824
+
```python
825
+
from sense_hat import SenseHAT
826
+
from time import sleep
827
+
828
+
sense = SenseHat()
829
+
sense.colour.gain =1
830
+
sleep(1)
831
+
print(f"Gain: {sense.colour.gain}")
832
+
print(f"RGBC: {sense.colour.colour}")
833
+
834
+
sense.colour.gain =16
835
+
sleep(1)
836
+
print(f"Gain: {sense.colour.gain}")
837
+
print(f"RGBC: {sense.colour.colour}")
838
+
```
839
+
840
+
Under the same lighting conditions, the RGBC values should be considerably higher when the gain setting is increased.
841
+
842
+
When there is very little ambient light and the RGBC values are low, it makes sense to use a higher gain setting. Conversely, when there is too much light and the RGBC values are maximal, the sensor is saturated and the gain should be set to lower values.
843
+
844
+
---
845
+
### Integration cycles and the interval between measurements
846
+
847
+
You can specify the number of _integration cycles_ required to generate a new set of sensor readings. Each integration cycle is 2.4 milliseconds long, so the number of integration cycles determines the _minimum_ amount of time required between consecutive readings.
848
+
849
+
You can set the number of integration cycles to any integer between `1` and `256`, through the `integration_cycles` property of the `ColourSensor` object. The default value is `1`. An attempt to set the number of integration cycles to a value that is not valid will result in a `InvalidIntegrationCyclesError` or `TypeError` exception being raised.
print(f"Minimum wait time between measurements: {sense.colour.integration_time} seconds")
859
+
```
860
+
861
+
---
862
+
### Integration cycles and raw values
863
+
864
+
The values of the `colour`, `red`, `green`, `blue` and `clear` properties are integers between 0 and 256. However, these are not the actual _raw_ values obtained from the sensor; they have been scaled down to this range for convenience.
865
+
866
+
The range of the raw values depends on the number of integration cycles:
867
+
868
+
`integration_cycles` | maximum raw value (`max_raw`)
869
+
--- | ---
870
+
1 - 64 | 1024 * `integration_cycles`
871
+
\> 64 | 65536
872
+
873
+
What this really means is that the _accuracy_ of the sensor is affected by the number of integration cycles, i.e. the time required by the sensor to obtain a reading. A longer integration time will result in more reliable readings that fall into a wider range of values, being able to more accurately distinguish between similar lighting conditions.
874
+
875
+
The following properties of the `ColourSensor` object provide direct access to the raw values measured by the sensor.
876
+
877
+
`ColourSensor` property | Returned type | Explanation
878
+
--- | --- | ---
879
+
`red_raw` | int | The amount of incident red light, between 0 and `max_raw`
880
+
`green_raw` | int | The amount of incident green light, between 0 and `max_raw`
881
+
`blue_raw` | int | The amount of incident blue light, between 0 and `max_raw`
882
+
`clear_raw` | int | The amount of incident light (brightness), between 0 and `max_raw`
883
+
`colour_raw` | tuple | A 4-tuple containing the RGBC (Red, Green, Blue and Clear) raw sensor readings, each between 0 and `max_raw`
884
+
885
+
Here is an example comparing raw values to the corresponding scaled ones, for a given number of integration cycles.
886
+
887
+
```
888
+
from sense_hat import SenseHAT
889
+
from time import sleep
890
+
891
+
sense = SenseHat()
892
+
sense.colour.integration_cycles = 64
893
+
print(f"Minimum time between readings: {sense.colour.integration_time} seconds")
894
+
print(f"Maximum raw sensor reading: {sense.colour.max_raw}")
895
+
sleep(sense.colour.integration_time + 0.1) # try omitting this
896
+
print(f"Current raw sensor readings: {sense.colour.colour_raw}")
897
+
print(f"Scaled values: {sense.colour.colour}")
898
+
```
899
+
900
+
## Exceptions
901
+
902
+
Custom Sense HAT exceptions are statically defined in the `sense_hat.exceptions` module.
903
+
The exceptions relate to problems encountered while initialising the colour chip or due to setting invalid parameters.
904
+
Each exception includes a message describing the issue encountered, and is subclassed from the base class `SenseHatException`.
0 commit comments