From f3c29971de6c43c9b4cc4a7b3f82fc107344a93f Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Mon, 3 Jun 2019 15:18:26 +0200
Subject: [PATCH] api: lights on hubs are instances of generic class

---
 doc/ev3dev/ev3brick.rst | 14 ++++++++++---
 doc/lpf2/hub4.rst       | 22 ++++++++++++++++++++
 doc/lpf2/movehub.rst    | 21 +++++++++++++++++++
 pybricks/_common.py     | 45 +++++++++++++++++++++++++++++++++++++++++
 pybricks/ev3brick.py    | 11 ++--------
 pybricks/hub4.py        |  3 ++-
 pybricks/movehub.py     |  3 ++-
 7 files changed, 105 insertions(+), 14 deletions(-)

diff --git a/doc/ev3dev/ev3brick.rst b/doc/ev3dev/ev3brick.rst
index 9a9a2f5..7a0fd4f 100644
--- a/doc/ev3dev/ev3brick.rst
+++ b/doc/ev3dev/ev3brick.rst
@@ -30,15 +30,23 @@ Buttons
 Light
 -----
 
-.. autofunction:: ev3brick.light
+.. automethod:: ev3brick.light.color
 
     Example::
 
         # Make the light red
-        brick.light(Color.RED)
+        brick.light.color(Color.RED)
+
+        # Wait
+        wait(1000)
 
         # Turn the light off
-        brick.light(None)
+        brick.light.off()
+
+
+.. automethod:: ev3brick.light.off
+
+.. automethod:: ev3brick.light.brightness
 
 Sound
 -----
diff --git a/doc/lpf2/hub4.rst b/doc/lpf2/hub4.rst
index 91487ed..0a08383 100644
--- a/doc/lpf2/hub4.rst
+++ b/doc/lpf2/hub4.rst
@@ -4,6 +4,28 @@
 .. automodule:: hub4
     :no-members:
 
+
+Light
+-----
+
+.. automethod:: hub4.light.color
+
+    Example::
+
+        # Make the light red
+        hub4.light.color(Color.RED)
+
+        # Wait
+        wait(1000)
+
+        # Turn the light off
+        hub4.light.off()
+
+
+.. automethod:: hub4.light.off
+
+.. automethod:: hub4.light.brightness
+
 Battery
 -------
 
diff --git a/doc/lpf2/movehub.rst b/doc/lpf2/movehub.rst
index db6eaf6..441ecd6 100644
--- a/doc/lpf2/movehub.rst
+++ b/doc/lpf2/movehub.rst
@@ -4,6 +4,27 @@
 .. automodule:: movehub
     :no-members:
 
+Light
+-----
+
+.. automethod:: movehub.light.color
+
+    Example::
+
+        # Make the light red
+        movehub.light.color(Color.RED)
+
+        # Wait
+        wait(1000)
+
+        # Turn the light off
+        movehub.light.off()
+
+
+.. automethod:: movehub.light.off
+
+.. automethod:: movehub.light.brightness
+
 Battery
 -------
 
diff --git a/pybricks/_common.py b/pybricks/_common.py
index b9ae0ee..a9e623b 100644
--- a/pybricks/_common.py
+++ b/pybricks/_common.py
@@ -276,6 +276,51 @@ class Speaker():
         pass
 
 
+class Light():
+    """Control an LED."""
+
+    def on(self):
+        """Turn on the light at maximum brightness."""
+        pass
+
+    def off(self):
+        """Turn off the light."""
+        pass
+
+    def brightness(self, brightness):
+        """Set the perceived brightness of the light.
+
+        Arguments:
+            brightness (:ref:`percentage`): Perceived brightness of the light.
+        """
+        pass
+
+
+class ColorLight():
+    """Control an RGB LED."""
+
+    def color(color):
+        """Turn on the light at the specified color.
+
+        Arguments:
+            color (Color): Color of the light. The light turns off if you choose ``None`` or a color that is not available.
+        """
+        pass
+
+    def off(self):
+        """Turn off the light."""
+        pass
+
+    def brightness(self, red, green, blue):
+        """Set the perceived brightness of the red, green, and blue light.
+
+        Arguments:
+            red (:ref:`percentage`): Perceived brightness of the red light.
+            green (:ref:`percentage`): Perceived brightness of the green light.
+            blue (:ref:`percentage`): Perceived brightness of the blue light.
+        """
+        pass
+
 class Battery():
     """Get the status of a battery."""
 
diff --git a/pybricks/ev3brick.py b/pybricks/ev3brick.py
index 50062b6..c9c2184 100644
--- a/pybricks/ev3brick.py
+++ b/pybricks/ev3brick.py
@@ -1,7 +1,7 @@
 """LEGO® MINDSTORMS® EV3 Brick."""
 
 from parameters import Color
-from _common import Speaker, Display, Battery
+from _common import Speaker, Display, Battery, ColorLight
 
 
 def buttons():
@@ -14,16 +14,9 @@ def buttons():
     pass
 
 
-def light(color):
-    """Set the color of the brick light.
-
-    Arguments:
-        color (Color): Color of the light. Choose ``Color.BLACK`` or ``None``
-                       to turn the light off.
-    """
-    pass
 
 
 sound = Speaker()
 display = Display()
 battery = Battery()
+light = ColorLight()
diff --git a/pybricks/hub4.py b/pybricks/hub4.py
index 376f194..fbf416e 100644
--- a/pybricks/hub4.py
+++ b/pybricks/hub4.py
@@ -1,5 +1,6 @@
 """LEGO® Power Functions 2.0 Hub 4."""
 
-from _common import Battery
+from _common import Battery, ColorLight
 
 battery = Battery()
+light = ColorLight()
diff --git a/pybricks/movehub.py b/pybricks/movehub.py
index beceefa..dd1269e 100644
--- a/pybricks/movehub.py
+++ b/pybricks/movehub.py
@@ -1,5 +1,6 @@
 """LEGO® Power Functions 2.0 Move Hub."""
 
-from _common import Battery
+from _common import Battery, ColorLight
 
 battery = Battery()
+light = ColorLight()