legoEv3/ev3dev2/port.py
# -----------------------------------------------------------------------------
# Copyright (c) 2015 Ralph Hempel <rhempel@hempeldesigngroup.com>
# Copyright (c) 2015 Anton Vanhoucke <antonvh@gmail.com>
# Copyright (c) 2015 Denis Demidov <dennis.demidov@gmail.com>
# Copyright (c) 2015 Eric Pascual <eric@pobot.org>
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
# -----------------------------------------------------------------------------
import sys
from . import Device
if sys.version_info < (3,4):
raise SystemError('Must be using Python 3.4 or higher')
class LegoPort(Device):
"""
The `lego-port` class provides an interface for working with input and
output ports that are compatible with LEGO MINDSTORMS RCX/NXT/EV3, LEGO
WeDo and LEGO Power Functions sensors and motors. Supported devices include
the LEGO MINDSTORMS EV3 Intelligent Brick, the LEGO WeDo USB hub and
various sensor multiplexers from 3rd party manufacturers.
Some types of ports may have multiple modes of operation. For example, the
input ports on the EV3 brick can communicate with sensors using UART, I2C
or analog validate signals - but not all at the same time. Therefore there
are multiple modes available to connect to the different types of sensors.
In most cases, ports are able to automatically detect what type of sensor
or motor is connected. In some cases though, this must be manually specified
using the `mode` and `set_device` attributes. The `mode` attribute affects
how the port communicates with the connected device. For example the input
ports on the EV3 brick can communicate using UART, I2C or analog voltages,
but not all at the same time, so the mode must be set to the one that is
appropriate for the connected sensor. The `set_device` attribute is used to
specify the exact type of sensor that is connected. Note: the mode must be
correctly set before setting the sensor type.
Ports can be found at `/sys/class/lego-port/port<N>` where `<N>` is
incremented each time a new port is registered. Note: The number is not
related to the actual port at all - use the `address` attribute to find
a specific port.
"""
SYSTEM_CLASS_NAME = 'lego-port'
SYSTEM_DEVICE_NAME_CONVENTION = '*'
__slots__ = [
'_address',
'_driver_name',
'_modes',
'_mode',
'_set_device',
'_status',
]
def __init__(self, address=None, name_pattern=SYSTEM_DEVICE_NAME_CONVENTION, name_exact=False, **kwargs):
if address is not None:
kwargs['address'] = address
super(LegoPort, self).__init__(self.SYSTEM_CLASS_NAME, name_pattern, name_exact, **kwargs)
self._address = None
self._driver_name = None
self._modes = None
self._mode = None
self._set_device = None
self._status = None
@property
def address(self):
"""
Returns the name of the port. See individual driver documentation for
the name that will be returned.
"""
self._address, value = self.get_attr_string(self._address, 'address')
return value
@property
def driver_name(self):
"""
Returns the name of the driver that loaded this device. You can find the
complete list of drivers in the [list of port drivers].
"""
self._driver_name, value = self.get_attr_string(self._driver_name, 'driver_name')
return value
@property
def modes(self):
"""
Returns a list of the available modes of the port.
"""
self._modes, value = self.get_attr_set(self._modes, 'modes')
return value
@property
def mode(self):
"""
Reading returns the currently selected mode. Writing sets the mode.
Generally speaking when the mode changes any sensor or motor devices
associated with the port will be removed new ones loaded, however this
this will depend on the individual driver implementing this class.
"""
self._mode, value = self.get_attr_string(self._mode, 'mode')
return value
@mode.setter
def mode(self, value):
self._mode = self.set_attr_string(self._mode, 'mode', value)
@property
def set_device(self):
"""
For modes that support it, writing the name of a driver will cause a new
device to be registered for that driver and attached to this port. For
example, since NXT/Analog sensors cannot be auto-detected, you must use
this attribute to load the correct driver. Returns -EOPNOTSUPP if setting a
device is not supported.
"""
raise Exception("set_device is a write-only property!")
@set_device.setter
def set_device(self, value):
self._set_device = self.set_attr_string(self._set_device, 'set_device', value)
@property
def status(self):
"""
In most cases, reading status will return the same value as `mode`. In
cases where there is an `auto` mode additional values may be returned,
such as `no-device` or `error`. See individual port driver documentation
for the full list of possible values.
"""
self._status, value = self.get_attr_string(self._status, 'status')
return value