api: lights on hubs are instances of generic class

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
 -----

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
 -------
 

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
 -------
 

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."""
 

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()

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()

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()