New Capabilities (#114)

Squashed commit. More info on GitHub

docs/source/developer/capability_list.rst

@@ -317,6 +317,124 @@ Actuator Has Color devices are able to change their color with a set_color
 command. Usually Color RGB profile is implemented by color sensors.
 
 
+Has Color Temperature
+^^^^^^^^^^^^^^^^^^^^^
+
+:Formal Capability Name: ``has_color_temp``
+
+:Provided Fields:
+    :Field Name: ``color_temp``
+    :Field Values:
+        Integer between 1000 and 10000 including. Color temperature value,
+        expressed in Kelvins.
+    :Field Description:
+        Specifies the current color temperature of a Thing in Kelvins.
+
+:Provided Commands:
+    :Command Name: ``set_color_temp``
+    :Command Params:
+        ``color_temp`` - the new value of color temperature to be set.
+    :Command Description:
+        Sets the color temperature for a Thing.
+
+
+Color Temperature devices are devices that have the "color temperature"
+property. The color temperature is expressed in Kelvins and can take integer
+values from 1000 to 10000 including. The color temperature of light source
+or other Actuator can be set with ``set_color_temp`` command. If the Thing
+doesn't support specified color temperature value (i.e. it's too low or
+too high for this Thing), then the color temperature will be set to the nearest
+supported value. For example, the minimum value is 2000 and the maximum value
+is 6500 K for majority of light bulbs available on the market. It's recommended
+for client applications to put some marks on the scale for Warm White (2700 K),
+Cool White (4000 K) and Daylight (5000 K) values.
+
+
+Has Temperature
+^^^^^^^^^^^^^^^
+
+:Formal Capability Name: ``has_temperature``
+
+:Provided Fields:
+    :Field Name: ``temperature_c``
+    :Field Values:
+        Floating point, temperature in degrees of **Celsius**.
+    :Field Description:
+        Expresses the current temperature measured by a Thing.
+
+:Provided Commands:
+    No commands provided
+
+
+Has Temperature devices are devices that have the "temperature" property.
+The value of "temperature_c" property is expressed in degrees of Celsius,
+Fahrenheits are not supported for now.
+
+It's supposed that the value of "temperature" property can'be changed by
+user and represents the current, real temperature of controlled object.
+For other purposes, please refer to Capability and Thing types which
+provide a "target_temperature" property.
+
+
+Has Position
+^^^^^^^^^^^^
+
+:Formal Capability Name: ``has_position``
+
+:Provided Fields:
+    :Field Name: ``position``
+    :Field Values:
+        Floating point number which represents the position of an object
+        in numbers from 0.0 to 100.0 including.
+    :Field Description:
+        Expresses the current position of a Thing.
+
+:Provided Commands:
+    :Command Name: ``set_position``
+    :Command Params:
+        ``position`` - the new value of position to be set.
+    :Command Description:
+        Sets the new position for a Thing.
+
+
+Has Position devices are devices that have the "position" property.
+This property allows to set a position of an object using only one
+single dimension. For example, it can represent the position of
+a shade (50% unrolled, 20% of window covered, etc.), the width of
+an opening (for gates, sliding doors, valves) and so on.
+
+
+Fan Speed
+^^^^^^^^^
+
+:Formal Capability Name: ``fan_speed``
+
+:Provided Fields:
+    :Field Name: ``fan_speed``
+    :Field Values:
+        Floating point numbers from 0.0 to 100.0 including.
+    :Field Description:
+        Expresses the current fan rotation speed in percents.
+
+:Provided Commands:
+    :Command Name: ``set_fan_speed``
+    :Command Params:
+        ``fan_speed`` - the new value of fan speed to be set.
+    :Command Description:
+        Sets the new fan speed for a Thing.
+
+
+Fan Speed devices are devices that have a build-in and externally
+controllable (at least monitored) fan. For example, that can be
+heaters, some HVACs and fans itself (as separate devices).
+
+The speed of some fans can be changed only by a constant step.
+For such cases (for example, for table fans with only 3 speeds),
+the whole range will be separated on the corresponding number
+of segments. For example, it'll be 0-25, 26-50, 51-75 and 76-100
+for a generic fan with speeds 0 (stopped), 1, 2 and 3 correspondingly.
+
+
 Has Value
 ^^^^^^^^^
 
@@ -344,6 +462,126 @@ a corresponding property is rarely used in the real life. See
 Capabilities instead.
 
 
+Play/Stop
+^^^^^^^^^
+
+:Formal Capability Name: ``play_stop``
+
+:Provided Fields:
+    :Field Name: ``state``
+    :Field Values:
+        string: ``playing``, ``stopped``
+    :Field Description:
+        Signs if the playback for this Thing (for some kind of player)
+        is in progress (playing) or stopped.
+
+:Provided Commands:
+    :Command Name: ``play``
+    :Command Params: No params needed
+    :Command Description:
+        Starts the playback.
+
+    |
+
+    :Command Name: ``stop``
+    :Command Params: No params needed
+    :Command Description:
+        Stops the playback.
+
+Play/Stop devices are devices that can play some media (i.e. music, video,
+radio, media stream, etc.) and which have basic controls for playback.
+Uses the "state" field to define the current playback state and corresponding
+commands to stop and resume playback.
+
+
+Pausable
+^^^^^^^^
+
+:Formal Capability Name: ``pausable``
+
+:Provided Fields:
+    :Field Name: ``state``
+    :Field Values:
+        string: ``paused``
+    :Field Description:
+        Signs if the activity for this Thing (playing, recording, etc.)
+        is paused.
+
+:Provided Commands:
+    :Command Name: ``pause``
+    :Command Params: No params needed
+    :Command Description:
+        Pauses the current activity.
+
+Pausable devices are devices that can pause the current activity
+(i.e to temporarily stop it with keeping of a current position).
+Usually provided by some kinds of Players or Recorders. For Actuator
+Pausable Things the "pause" command can be used to pause the current
+activity (i.e. the playback, recording and so on).
+
+Usually implemented alongside with Play/Stop Capability.
+
+
+Track Switching
+^^^^^^^^^^^^^^^
+
+:Formal Capability Name: ``track_switching``
+
+:Provided Fields:
+    No fields provided
+
+:Provided Commands:
+    :Command Name: ``next``
+    :Command Params: No params needed
+    :Command Description:
+        Switches the playback to the next track, video or stream.
+
+    |
+
+    :Command Name: ``previous``
+    :Command Params: No params needed
+    :Command Description:
+        Switches the playback to the previous track, video or stream.
+
+Track Switching devices are devices that can switch between the current,
+previous and the next track, song, file, video or stream in the playback
+queue. Usually implemented by Players. Track Switching devices aren't
+obliged to support playlists, switching to specific tracks in the queue
+and so on. For support of the mentioned features please refer to the
+corresponding Capabilities.
+
+Usually implemented alongside with Play/Stop and Pausable Capabilities.
+
+
+Track Info
+^^^^^^^^^^
+
+:Formal Capability Name: ``track_info``
+
+:Provided Fields:
+    :Field Name: ``track_info``
+    :Field Values:
+        String
+    :Field Description:
+        Contains the information about a current playing song, movie,
+        stream or another media in a form of a single human-readable
+        string.
+
+:Provided Commands:
+    No commands provided
+
+Track Info devices are devices that can display information about the
+current playing media. The type of this information can be arbitrary
+and is not specified by this document. It's not even supposed to be
+parsed by other devices. The only thing that must to be granted is that
+the track_info field value must to be human-readable without any additional
+processing.
+
+For support of information about the song name, movie name, artists,
+current playing TV program and so on please refer to the corresponding
+Capabilities and Thing types.
+
+
 Has Volume
 ^^^^^^^^^^
 
@@ -369,3 +607,42 @@ of loudness of how loud its sound is. Volume is an integer value in the range
 from 0 (zero) to 100. Actuator Has Volume devices are able to change their
 volume with a ``set_volume`` command.
 
+
+Multi-Source
+^^^^^^^^^^^^
+
+:Formal Capability Name: ``multi_source``
+
+:Provided Fields:
+    :Field Name: ``current_source``
+    :Field Values:
+        An integer value, an index of the current source from the
+        ``available_sources`` list.
+    :Field Description:
+        Contains an identifier of the source which is currently chosen.
+
+    |
+
+    :Field Name: ``available_sources``
+    :Field Values:
+        An ordered list of strings.
+    :Field Description:
+        An list of human-readable names for all available sources.
+
+:Provided Commands:
+    :Command Name: ``set_source``
+    :Command Params:
+        ``source`` - a new value for the ``current_source`` field.
+    :Command Description:
+        Sets the specified source for this Thing.
+
+
+Multi-Source devices are devices that can play, display or use in any
+other way information from one of several information sources. The good
+example of such device is a computer monitor. Computer monitor often
+can display information from several inputs as HDMI, VGA or DisplayPort
+input. Or a speaker system which can play a sound from coaxial, optical,
+HDMI, Bluetooth or AUX inputs.
+
+For such devices as TVs, home theaters and other multi-functional devices
+please refer to the Multi-Mode_ Capability documentation.

dpl/things/capabilities/__init__.py

@@ -15,11 +15,23 @@
 from .has_color_rgb import HasColorRGB
 from .has_value import HasValue
 from .has_volume import HasVolume
+from .has_color_temp import HasColorTemperature
+from .has_temperature import HasTemperature
+from .has_position import HasPosition
+from .fan_speed import FanSpeed
+from .play_stop import PlayStop
+from .pausable import Pausable
+from .track_switching import TrackSwitching
+from .track_info import TrackInfo
+from .multi_source import MultiSource
 
 
 __all__ = (
     'Actuator', 'HasState', 'IsActive',
     'OnOff', 'OpenClosed', 'MultiMode',
     'HasBrightness', 'HasColorHSB', 'HasColorRGB',
-    'HasValue', 'HasVolume'
+    'HasValue', 'HasVolume', 'HasColorTemperature',
+    'HasTemperature', 'HasPosition', 'FanSpeed',
+    'PlayStop', 'Pausable', 'TrackSwitching',
+    'TrackInfo', 'MultiSource'
 )

dpl/things/capabilities/fan_speed.py

@@ -0,0 +1,29 @@
+"""
+This module contains definition of Fan Speed capability
+"""
+
+
+class FanSpeed(object):
+    """
+    Fan Speed devices are devices that have a build-in and externally
+    controllable (at least monitored) fan. For example, that can be
+    heaters, some HVACs and fans itself (as separate devices).
+
+    The speed of some fans can be changed only by a constant step.
+    For such cases (for example, for table fans with only 3 speeds),
+    the whole range will be separated on the corresponding number
+    of segments. For example, it'll be 0-25, 26-50, 51-75 and 76-100
+    for a generic fan with speeds 0 (stopped), 1, 2 and 3 correspondingly.
+
+    """
+    _capability_name = 'fan_speed'
+    _commands = ('set_fan_speed',)
+
+    @property
+    def fan_speed(self) -> float:
+        """
+        Returns the current fan speed of a Thing in values from 0.0 to 100.0.
+
+        :return: the current fan speed
+        """
+        raise NotImplementedError()

dpl/things/capabilities/has_color_temp.py

@@ -0,0 +1,27 @@
+"""
+This module contains definition of Has Color Temperature capability
+"""
+
+
+class HasColorTemperature(object):
+    """
+    Color Temperature devices are devices that have the "color temperature"
+    property. The color temperature is expressed in Kelvins and can take integer
+    values from 1000 to 10000 including. The color temperature of light source
+    or other Actuator can be set with ``set_color_temp`` command.
+
+    If the Thing doesn't support specified color temperature value
+    (i.e. it's too low or too high for this Thing), then the color temperature
+    will be set to the nearest supported value.
+    """
+    _capability_name = 'has_color_temp'
+    _commands = ('set_color_temp',)
+
+    @property
+    def color_temp(self) -> int:
+        """
+        Returns the current color temperature of a Thing in Kelvins
+
+        :return: the current color temperature in Kelvins
+        """
+        raise NotImplementedError()