pybricks-api/pybricks/iodevices.py

# SPDX-License-Identifier: MIT
# Copyright (c) 2018-2020 The Pybricks Authors

"""Generic input/output devices."""


class LUMPDevice():
    """Devices using the LEGO UART Messaging Protocol."""

    def __init__(self, port):
        """

        Arguments:
            port (Port): Port to which the device is connected.
        """
        pass

    def read(self, mode):
        """Read values from a given mode.

        Arguments:
            mode (``int``): Device mode.

        Returns:
            ``tuple``: Values read from the sensor.
        """
        pass

    def write(self, mode, values):
        """Write values to the sensor. Only selected sensors and modes support
        this.

        Arguments:
            mode (``int``): Device mode.
            data (``tuple``): Values to be written.
        """
        pass


class Ev3devSensor():
    """Read values of an ev3dev-compatible sensor."""

    sensor_index = 0
    """Index of the ev3dev sysfs `lego-sensor`_ class."""

    port_index = 0
    """Index of the ev3dev sysfs `lego-port`_ class."""

    def __init__(self, port):
        """

        Arguments:
            port (Port): Port to which the device is connected.
        """
        pass

    def read(self, mode):
        """Read values at a given mode.

        Arguments:
            mode (``str``): `Mode name`_.

        Returns:
            ``tuple``: Values read from the sensor.
        """
        pass


class AnalogSensor():
    """Generic or custom analog sensor."""

    def __init__(self, port):
        """

        Arguments:
            port (Port): Port to which the sensor is connected.
        """
        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


class I2CDevice():
    """Generic or custom I2C device."""

    def __init__(self, port, address):
        """

        Arguments:
            port (Port): Port to which the device is connected.
            address(int): I2C address of the client device. See
                :ref:`I2C Addresses <i2caddress>`.
        """
        pass

    def read(self, reg, length=1):
        """Read bytes, starting at a given register.

        Arguments:
            reg (``int``): Register at which to begin
                reading: 0--255 or 0x00--0xFF.
            length (``int``): How many bytes to read (*Default*: ``1``).

        Returns:
            ``bytes``: Bytes returned from the device.
        """
        pass

    def write(self, reg, data=None):
        """Write bytes, starting at a given register.

        Arguments:
            reg (``int``): Register at which to begin
                writing: 0--255 or 0x00--0xFF.
            data (``bytes``): Bytes to be written (*Default*: ``None``).
        """
        pass


class UARTDevice():
    """Generic UART device."""

    def __init__(self, port, baudrate, timeout=None):
        """

        Arguments:
            port (Port): Port to which the device is connected.
            baudrate (int): Baudrate of the UART device.
            timeout (:ref:`time`): How long to wait
                during :meth:`.read` before giving up. If you choose ``None``,
                it will wait forever (*Default*: ``None``).
        """
        pass

    def read(self, length=1):
        """Read a given number of bytes from the buffer.

        Your program will wait until the requested number of bytes are
        received. If this takes longer than ``timeout``, the ``ETIMEDOUT``
        exception is raised.

        Arguments:
            length (``int``): How many bytes to read (*Default*: ``1``).

        Returns:
            ``bytes``: Bytes returned from the device.
        """
        pass

    def read_all(self):
        """Read all bytes from the buffer.

        Returns:
            ``bytes``: Bytes returned from the device.
        """
        pass

    def write(self, data):
        """Write bytes.

        Arguments:
            data (``bytes``): Bytes to be written.
        """
        pass

    def waiting(self):
        """How many bytes are still waiting to be read.

        Returns:
            ``int``: Number of bytes in the buffer.
        """
        pass

    def clear(self):
        """Empty the buffer."""
        pass