From 653aa669b2ce4b8951e274dce2cca53c6fcacac8 Mon Sep 17 00:00:00 2001
From: Laurens Valk <laurens@pybricks.com>
Date: Thu, 14 Nov 2019 08:47:30 +0100
Subject: [PATCH] doc+api/customdevices: move AnalogSensor

Generic and custom devices like the AnalogSensor will live in a dedicated module.
---
 doc/api/customdevices.rst |  9 ++++++
 doc/api/ev3devices.rst    |  4 ---
 doc/api/index.rst         |  1 +
 pybricks/customdevices.py | 61 +++++++++++++++++++++++++++++++++++++++
 4 files changed, 71 insertions(+), 4 deletions(-)
 create mode 100644 doc/api/customdevices.rst
 create mode 100644 pybricks/customdevices.py

diff --git a/doc/api/customdevices.rst b/doc/api/customdevices.rst
new file mode 100644
index 0000000..f4b4bb2
--- /dev/null
+++ b/doc/api/customdevices.rst
@@ -0,0 +1,9 @@
+:mod:`customdevices` -- Custom Devices
+===========================================
+
+.. automodule:: pybricks.customdevices
+    :no-members:
+
+Analog Sensor
+^^^^^^^^^^^^^
+.. autoclass:: pybricks.customdevices.AnalogSensor
diff --git a/doc/api/ev3devices.rst b/doc/api/ev3devices.rst
index 2543997..30316bc 100644
--- a/doc/api/ev3devices.rst
+++ b/doc/api/ev3devices.rst
@@ -55,7 +55,3 @@ Ultrasonic Sensor
 Gyroscopic Sensor
 ^^^^^^^^^^^^^^^^^
 .. autoclass:: pybricks.ev3devices.GyroSensor
-
-Analog Sensor
-^^^^^^^^^^^^^
-.. autoclass:: pybricks.ev3devices.AnalogSensor
diff --git a/doc/api/index.rst b/doc/api/index.rst
index 7381ab4..c894206 100644
--- a/doc/api/index.rst
+++ b/doc/api/index.rst
@@ -23,6 +23,7 @@ Intro
    hubs
    pupdevices
    ev3devices
+   customdevices
    parameters
    tools
    robotics
diff --git a/pybricks/customdevices.py b/pybricks/customdevices.py
new file mode 100644
index 0000000..a2ce0d3
--- /dev/null
+++ b/pybricks/customdevices.py
@@ -0,0 +1,61 @@
+"""Custom motors and sensors."""
+
+
+class AnalogSensor():
+    """Generic or custom analog sensor."""
+
+    def __init__(self, port, check_type=True):
+        """AnalogSensor(port, check_type=True)
+
+        Arguments:
+            port (Port): Port to which the sensor is connected.
+            verify_type(bool): Verify that the sensor is detected as an analog
+                sensor (*Default*: ``True``).
+
+                If you choose ``verify_type=False``, the EV3 will treat it as
+                an analog sensor even if no such sensor is detected. This is
+                useful if you have a (custom) analog sensor that is not
+                detected automatically.
+        """
+        pass
+
+    def voltage(self):
+        """Measured analog voltage.
+
+        Returns:
+            :ref:`voltage`: Analog voltage.
+        """
+        pass
+
+    def resistance(self):
+        """Measured resistance.
+
+        This value is only meaningful if the analog device is a passive load
+        such as a resistor or thermistor.
+
+        Returns:
+            :ref:`resistance: Ω <voltage>`: Resistance of the analog device.
+        """
+        pass
+
+    def active(self):
+        """Set sensor to active mode. This sets pin 5 of the sensor
+        port to `high`.
+
+        This is used in some analog
+        sensors to control a switch. For example, if you use the NXT Light
+        Sensor as a custom analog sensor, this method will turn the light on.
+        From then on, ``voltage()`` returns the raw reflected light value.
+        """
+        pass
+
+    def passive(self):
+        """Set sensor to passive mode. This sets pin 5 of the sensor
+        port to `low`.
+
+        This is used in some analog
+        sensors to control a switch. For example, if you use the NXT Light
+        Sensor as a custom analog sensor, this method will turn the light off.
+        From then on, ``voltage()`` returns the raw ambient light value.
+        """
+        pass