Public Capabilities (First Prototype)

s-kostyuk commented 6 years ago

This pull request introduces Capabilities to the public.

What was added:

now every Thing has a list of capabilities - a list of functions (their names, to be exact) that are supported by (are implemented in) thing Thing;
a list of capabilities is now showed in the REST API representations;
added a new mandatory field for all system-defined Capabilities: a _capability_name private field;
added a logic of dynamic evaluation-time definition of capabilities for all implementations of the Thing class by the means of the CapabilityFiller metaclass.

Closes #52

s-kostyuk commented 6 years ago

WARNING: Some discussion related to the naming of Capabilities is needed.

s-kostyuk commented 6 years ago

So far I liked the naming conventions described in this note. The only problem is that with such naming conventions there will be a lot of Capabilities like has_value, has_state and other ones starting with has_ prefix.

An alternative is to use -able naming for Capabilities. But it's often awkward to create and read such names.

The other alternative is just to stick with naming like actuator, player on other similar names as used in SmartThings ecosystem. But with such decision there will be easy to jumble with capabilities and type names

s-kostyuk commented 6 years ago

OK. Now, how to name capabilities of such two basic categories of devices? 1) valves, gates, doors, locks etc. with open and close states and corresponding commands? 2) power wallets, lighting, fans etc. with on and off states and corresponding commands?

Like this? 1) Openable? Closable? CanBeOpened? CanBeClosed? CanBeOpenedOrClosed? OpenClosed? Slider? HasOpenClose? OpenCloseState? Sliding? 2) Onable? Offable? Turnable? CanBeTrunedOn? CanBeTurnedOnAndOff? OnOff? Switch? HasOnOff? OnOffState? Switching?

And all of them together: Togglable? Activatible? Deactivatible? Toggling? Just Actuator implying that all Actuators can be toggled between some two states or explicitly activated and deactivated?

God, I don't know

s-kostyuk commented 6 years ago

About naming. Sonos uses Capabilities too. But looks like Capabilities are only human-oriented names intended for the usage in documentation only, not in API: https://musicpartners.sonos.com/node/530

s-kostyuk commented 6 years ago

OK. Alexa uses the name of the device category for naming of Capabilities. For example:

ThermostatController
TemperatureSensor
PowerController
PercentageController

s-kostyuk commented 6 years ago

Here is the proposal

Actuators

Actuators are devices that can "act", i.e. execute some commands, to change their state and the state of the outside world.

Those devices provide an actuator capability.

Has State

Has State devices are devices that have the state property. The value of the property is some string which is directly mapped to one of the device states. The exact set of possible states is defined by a set of Capabilities provided by the device.

Those devices provide a has_state capability.

Is Active

Is Active devices are devices whose state can be easily and directly mapped onto two categories: "active" or "inactive" states. You can determine either the device is active or not by the value of is_active field. In one of the "active" states the value of is_active field is equal to true, on other states it's equal to false. Actuator Is Active devices support the specified commands: toggle, activate and deactivate.

Those devices provide an is_active capability.

On/Off

On/Off devices are devices that can be either powered "on" or "off". The current state of those devices can be determined by the value of the is_power_on field. Actuator On/Off devices are able to be turned on and off with the on and off commands correspondingly.

Those devices provide an on_off capability.

If the device provides both on_off and is_active capabilities, then the on state is usually mapped to true value of is_active field and off state is mapped to false. on command is also mapped to the activate and off command is mapped to the deactivate command.

Open/Closed

Open/Closed devices are devices that can be in either "open" or "closed" state. The current state of those devices can be determined bу the value of the state field. In addition to the "open" and "closed" states there are two transitional states possible: "opening" and "closing".

Those devices provide an open_closed capability.

If the device provides both open_closed and is_active capabilities, then the open and opening stats are usually mapped to true value of is_active field and close with closing states are mapped to false. Also generic activate and deactivate commands are available for such devices with activate mapped to open, deactivate mapped to close and toggle toggles between the opposite states (from open to closed, from closed to open, from opening to closed, from closing to opened).

Multimode

Multimode devices are able to work in different modes. By switching the mode of the device some Capabilities may become available for usage and some may gone. The current mode of the device is specified in the mode field. If the mode of the device was changed, then the list of capabilities and a set of available fields are altered to correspond to the current mode (FIXME: Is it reasonable?). Only one device mode сan be chosen at a time. The current mode of the device can be set via set_mode command.

Those devices provide an multimode capability.

Has Brightness

Has Brightness devices are devices that have the brightness property. The brightness property is an integer value in the range from 0 (zero) to 100. Actuator Has Brightness devices are able to change their brightness with a set_brighness command. Usually normal people call Actuator Has Brightness devices as "dimmable" devices.

Those devices provide a has_brightness capability.

Has Color

Has Color devices are devices that have the "color" property. The color property value can be specified in one the two systems: HSB (hue, saturation, brightness) or RGB (red, green, blue). Actuator Has Color devices are able to change their color with a set_color command.

Those devices provide a has_color capability.

Has Value

Has Value devices are devices that have the "value" property. This field and a corresponding property is rarely used in the real life. See has_brightness, has_temperature, has_volume and other similar Capabilities instead.

Those devices provide a has_value capability.

Has Volume

Has Value devices are devices that have the "volume" property - the measure 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.

Those devices provide a has_volume capability.

s-kostyuk commented 6 years ago

Devices and their capabilities (research):

s-kostyuk commented 6 years ago

Documentation will be prepared in the separate branch and pushed with the separate pull request

s-kostyuk commented 6 years ago

This pull request will be closed. The original branch will be rebased

s-kostyuk / everpl