Merge pull request #115 from G3zz/tcs3472-rebased

Add support for the TCS34725 colour sensor

README.rst → README.md

@@ -60,6 +60,7 @@ Contributors
 * `Serge Schneider`_
 * `Dave Jones`_
 * `Tyler Laws`_
+* `George Boukeas`_
 
 Open Source
 ===========

debian/changelog

@@ -0,0 +1,36 @@
+python-sense-hat (2.3.1~test0) UNRELEASED; urgency=medium
+
+  * v2.3.1 alpha
+
+ -- George Boukeas <george.boukeas@raspberrypi.org>  Wed, 21 Jul 2021 15:11:00 +0000
+
+python-sense-hat (2.3.0~test0) UNRELEASED; urgency=medium
+
+  * v2.3.0 alpha
+
+ -- Serge Schneider <serge@raspberrypi.com>  Fri, 11 Dec 2020 14:41:32 +0000
+
+python-sense-hat (2.2.0-1) jessie; urgency=medium
+
+  * v2.2.0 release
+
+ -- Serge Schneider <serge@raspberrypi.org>  Sun, 07 Aug 2016 14:32:16 +0100
+
+python-sense-hat (2.1.0-1) jessie; urgency=low
+
+  * v2.1.0 release
+
+ -- Serge Schneider <serge@raspberrypi.org>  Tue, 25 Aug 2015 05:19:02 +0100
+
+python-sense-hat (2.0.0-1) jessie; urgency=low
+
+  * v2.0.0 release
+  * Rename to python-sense-hat
+
+ -- Serge Schneider <serge@raspberrypi.org>  Fri, 21 Aug 2015 19:36:23 +0100
+
+astropi (1.1.5-1) jessie; urgency=low
+
+  * Initial release
+
+ -- Serge Schneider <serge@raspberrypi.org>  Fri, 03 Jul 2015 03:24:45 +0100

debian/compat

@@ -0,0 +1 @@
+9

debian/control

@@ -0,0 +1,32 @@
+Source: python-sense-hat
+Section: python
+Priority: optional
+Maintainer: Serge Schneider <serge@raspberrypi.com>
+Build-Depends: debhelper (>= 9~), dh-python, python-all (>= 2.6.6-3~),
+ python-setuptools, python3-all, python3-setuptools
+Standards-Version: 4.3.0
+Homepage: https://github.com/RPi-Distro/python-sense-hat
+Vcs-Git: git://github.com/RPi-Distro/python-sense-hat.git -b debian
+Vcs-Browser: https://github.com/RPi-Distro/python-sense-hat/tree/debian
+
+Package: python-sense-hat
+Architecture: all
+Depends: ${misc:Depends}, ${python:Depends}, python-rtimulib, python-pil,
+ python-numpy
+Description: Sense HAT python library (Python 2)
+ Python module to control the Sense HAT for the Raspberry Pi used
+ in the Astro Pi mission - an education outreach programme for UK schools
+ sending code experiments to the International Space Station
+ .
+ This package installs the library for Python 2.
+
+Package: python3-sense-hat
+Architecture: all
+Depends: ${misc:Depends}, ${python3:Depends}, python3-rtimulib, python3-pil,
+ python3-numpy, python3-smbus
+Description: Sense HAT python library (Python 3)
+ Python module to control the Sense HAT for the Raspberry Pi used
+ in the Astro Pi mission - an education outreach programme for UK schools
+ sending code experiments to the International Space Station
+ .
+ This package installs the library for Python 3.

debian/copyright

@@ -0,0 +1,32 @@
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: python-sense-hat
+Source: https://github.com/RPi-Distro/python-sense-hat
+
+Files: *
+Copyright: 2015 Raspberry Pi Foundation
+License: BSD-3-Clause
+
+License: BSD-3-Clause
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+ 3. Neither the name of the University nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+ .
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
+ A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE HOLDERS OR
+ CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
+ EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
+ PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
+ PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
+ LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 
+ NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

debian/rules

@@ -0,0 +1,13 @@
+#!/usr/bin/make -f
+# See debhelper(7) (uncomment to enable)
+# output every command that modifies files on the build system.
+#DH_VERBOSE = 1
+
+DPKG_EXPORT_BUILDFLAGS = 1
+include /usr/share/dpkg/default.mk
+
+
+export PYBUILD_NAME = sense-hat
+
+%:
+	dh $@ --with python2,python3 --buildsystem=pybuild

debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

docs/api.md

@@ -774,3 +774,131 @@ Note that the `direction_any` event is always called *after* all other events
 making it an ideal hook for things like display refreshing (as in the example
 above).
 
+- - -
+## Light and colour sensor
+
+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.
+
+You can interact with the colour sensor through the `colour` (or `color`) attribute of the Sense HAT, which corresponds to a `ColourSensor` object.
+
+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.
+
+```python
+from sense_hat import SenseHat
+from time import sleep
+
+sense = SenseHat()
+sense.color.gain = 4
+sense.color.integration_cycles = 64
+
+while True:
+    sleep(2 * sense.colour.integration_time)
+    red, green, blue, clear = sense.colour.colour # readings scaled to 0-256
+    print(f"R: {red}, G: {green}, B: {blue}, C: {clear}")
+```
+
+---
+### Obtaining RGB and Clear light readings
+
+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.
+
+`ColourSensor` property | Returned type | Explanation
+--- | --- | ---
+`red` | int | The amount of incident red light, scaled to 0-256
+`green` | int | The amount of incident green light, scaled to 0-256
+`blue` | int | The amount of incident blue light, scaled to 0-256
+`clear` | int | The amount of incident light (brightness), scaled to 0-256
+`colour` | tuple | A 4-tuple containing the RGBC (Red, Green, Blue and Clear) sensor readings, each scaled to 0-256
+
+These are all read-only properties; they cannot be set.
+
+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.
+
+---
+### Gain
+
+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. 
+
+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.
+
+```python
+from sense_hat import SenseHAT
+from time import sleep
+
+sense = SenseHat()
+sense.colour.gain = 1
+sleep(1)
+print(f"Gain: {sense.colour.gain}")
+print(f"RGBC: {sense.colour.colour}")
+
+sense.colour.gain = 16
+sleep(1)
+print(f"Gain: {sense.colour.gain}")
+print(f"RGBC: {sense.colour.colour}")
+```
+
+Under the same lighting conditions, the RGBC values should be considerably higher when the gain setting is increased.
+
+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. 
+
+---
+### Integration cycles and the interval between measurements
+
+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.
+
+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.
+
+```python
+from sense_hat import SenseHAT
+from time import sleep
+
+sense = SenseHat()
+sense.colour.integration_cycles = 100
+print(f"Integration cycles: {sense.colour.integration_cycles}")
+print(f"Minimum wait time between measurements: {sense.colour.integration_time} seconds")
+```
+
+---
+### Integration cycles and raw values
+
+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. 
+
+The range of the raw values depends on the number of integration cycles:
+
+`integration_cycles` | maximum raw value (`max_raw`)
+--- | ---
+1 - 64 | 1024 * `integration_cycles`
+\> 64 | 65536
+
+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.
+
+The following properties of the `ColourSensor` object provide direct access to the raw values measured by the sensor.
+
+`ColourSensor` property | Returned type | Explanation
+--- | --- | ---
+`red_raw` | int | The amount of incident red light, between 0 and `max_raw`
+`green_raw` | int | The amount of incident green light, between 0 and `max_raw`
+`blue_raw` | int | The amount of incident blue light, between 0 and `max_raw`
+`clear_raw` | int | The amount of incident light (brightness), between 0 and `max_raw`
+`colour_raw` | tuple | A 4-tuple containing the RGBC (Red, Green, Blue and Clear) raw sensor readings, each between 0 and `max_raw`
+
+Here is an example comparing raw values to the corresponding scaled ones, for a given number of integration cycles.
+
+```
+from sense_hat import SenseHAT
+from time import sleep
+
+sense = SenseHat()
+sense.colour.integration_cycles = 64
+print(f"Minimum time between readings: {sense.colour.integration_time} seconds")
+print(f"Maximum raw sensor reading: {sense.colour.max_raw}")
+sleep(sense.colour.integration_time + 0.1)  # try omitting this
+print(f"Current raw sensor readings: {sense.colour.colour_raw}")
+print(f"Scaled values: {sense.colour.colour}")
+```
+
+## Exceptions
+
+Custom Sense HAT exceptions are statically defined in the `sense_hat.exceptions` module. 
+The exceptions relate to problems encountered while initialising the colour chip or due to setting invalid parameters. 
+Each exception includes a message describing the issue encountered, and is subclassed from the base class `SenseHatException`. 

docs/changelog.md

@@ -2,6 +2,10 @@
 
 ## v2
 
+### 2.3.x
+
+- Added support for the light/colour sensor in the v2 Sense HAT
+
 ### 2.2.0
 
 - Added new stick interface for the joystick

docs/index.md

@@ -12,6 +12,7 @@ The Sense HAT features an 8x8 RGB LED matrix, a mini joystick and the following
 - Temperature
 - Humidity
 - Barometric pressure
+- Light and colour
 
 ## Install
 
@@ -35,10 +36,10 @@ sense = SenseHat()
 sense.show_message("Hello world!")
 ```
 
-See the [API reference](api.md) for full documentation of the library's functions. See [examples](https://github.com/RPi-Distro/python-sense-hat/blob/master/examples/README.md).
+See the [API reference](api.md) for full documentation of the library's functions. See [examples](examples/README.md).
 
 ## Development
 
-This library is maintained by the Raspberry Pi Foundation on GitHub at [github.com/RPi-Distro/python-sense-hat](https://github.com/RPi-Distro/python-sense-hat)
+This library is maintained by the Raspberry Pi Foundation on GitHub at [github.com/astro-pi/python-sense-hat](https://github.com/astro-pi/python-sense-hat)
 
 See the [changelog](changelog.md).

mkdocs.yml

@@ -5,8 +5,9 @@ repo_url: https://github.com/RPi-Distro/python-sense-hat
 site_description: Python module to control the Raspberry Pi Sense HAT used in the Astro Pi mission
 site_author: David Honess
 site_dir: pythonhosted
-google_analytics: ['UA-46270871-5', 'pythonhosted.org/sense-hat']
-pages:
+#google_analytics: ['UA-46270871-5', 'pythonhosted.org/sense-hat']
+nav:
 - 'Home': 'index.md'
 - 'API Reference': 'api.md'
+- 'Examples': 'examples/README.md'
 - 'Changelog': 'changelog.md'

sense_hat/__init__.py

@@ -13,4 +13,4 @@
     ACTION_HELD,
     )
 
-__version__ = '2.2.0'
+__version__ = '2.3.1'