developer entity types - YIO-Remote/documentation GitHub Wiki
Entities are the central interface objects between the integrations and the YIO-Remote UI.
They can be accessed by the integrations DLLs/shared libraries using interfaces. On the other side they are designed to be used comfortably by the YIO-Remote QML based UI. Integrations are something like drivers connecting smart home hubs, media servers...
The sources are in the sources/entities subtree.
- The Entities container is used as anchor to get all the entity objects
- The Entity object is the base class for all concrete entity objects. An entity is identified by entity_id.
- The "concrete" entity objects derived from entity, like Light, Blind, ...
Attributes of an entity are all properties of an entity which can be set (updated) by the integrations.
Features of an entity are a set of functionalities a specific entity supports. It is used by the UI to adapt the visual representation of the entity and often by the integration to decide which attributes it has to deliver.
Commands of an entity contains all possible commands which can be sent from the UI to the integrations.
- in QML it is installed as context property "entities"
- in C++ you get it using Entities::getInstance()
- Integrations get the entities interface EntitiesInterface in their create function.
// get entites by type
QList<EntityInterface *> getByType (const QString& type);
// get entites by area
QList<EntityInterface *> getByArea (const QString& area);
// get entities by integration
QList<EntityInterface *> getByIntegration (const QString& integration);
// update an entity's attributes (not recommended, use entity function updateAttrByIndex)
void update (const QString& entity_id, const QVariantMap& attributes);
// set connected, indicates that an entity is "online"
void setConnected (const QString& integationId, bool connected);
// get entity interface by entity_id
EntityInterface* getEntityInterface (const QString& entity_id);
QList<QObject*> list // all entity objects
QStringList supported_entities // supported entity types (light, blind)
QStringList supported_entities_translation // supported translations
QStringList loaded_entities // all entity_ids
QList<QObject*> mediaplayersPlaying // playing mediaplayer entities
void load // load entities from config.json
QObject* get // get entity object by entity_id
void add // add a loaded entity, assign its integration
void addLoadedEntity // add a loaded entities id
QString getSupportedEntityTranslation // get the supported translation
The generic entity object implements a featurs common for all types of entities. It is the base class of "concrete" entity objects like light, blind, *mediaplayer', ..
- For the integrations EntityInterface is used to access the entity. You get it using entitiesInterface->getEntityInterface(entityId)
- in QML it is accessed using entities.get(enityId)
- The generic entity objects contains
Access to the generic attributes from config.json
QString type(); // light, blind, ...
QString area(); // room name
QString friendly_name(); // name used in UI
QString entity_id(); // unique id
QString integration(); // integration name
QObject* integrationObj(); // integration object
QStringList supported_features(); // list of supported features, use isSupported if possible
bool isSupported(int feature); // Use enum F_xxx, defined in the "concrete" entity interface
Handling of favorite feature
// favorite state (can be changed by the UI)
bool favorite();
void setFavorite(bool value);
Handling of connected state. connected indicates that the entity is "online".
bool connected();
void setConnected(bool value);
State is an attribute common for all entity types. It is represented by an enum (ON, OFF, OPEN ...) defined by the "concrete" entity type. Instead of the integer enum also the text can be used.
int state();
bool setState(int value);
QString stateText(); // state as text
bool setStateText(const QString& stateText);
QStringList allStates(); // All states
bool isOn(); // common state interpretation
bool supportsOn(); // entity has no on state
void turnOn(); // common **ON** command
void turnOff(); // common **OFF** command
Update entity attributes (STATE, BRIGHTNESS, POSITION ...). The attribute index as enum is defined by "concrete" entity type. But there is also a conversion betwen attribute name as text and index. Update of attributes is by attribute index or name. A set of attributes can be applied using a map of named attributes. The fasted method is of course update by index. The "concrete" entity interfaces defines enums for the state, the attribute index, the command, and the feature. Conversion functions between enum and strings are available.
bool update (const QVariantMap& attributes);
bool updateAttrByName (const QString& attrName, const QVariant& value);
bool updateAttrByIndex (int attrIndex, const QVariant& value);
QString getAttrName (int attrIndex);
int getAttrIndex (const QString& attrName);
QStringList allAttributes ();
QString getFeatureName (int featureIndex);
int getFeatureIndex (const QString& featureName);
QStringList allFeatures ();
QString getCommandName (int commandIndex);
int getCommandIndex (const QString& commandName);
QStringList allCommands ();
Every "concrete" entity type has a specific interface (LightInterface ...) which can be used to access the entity specific attributes.
void* getSpecificInterface() // LightInterface, ...
// Generic command to integration (use enums C_Xxx for command, as defined in the concrete interface)
void command (int command, const QVariant& param);
To use the defined enums in QML import the definitons, sample:
import Entity.Light 1.0
A concrete entity object like Light (lets use the "light" as example) derives from Entity. Its interface LightInterface contains access to the specific attributes for the integrations. The same include file also contains the enums for the attributes (=attributeIndex) and states. It was neccessary to hold the enum definitions in a separate class to use Qt's metadata based conversion of enums between enum integer and text. And to make the enums evailable in QML.
States enum : OFF = 0, ON = 1
Attributes enum : STATE, BRIGHTNESS, COLOR, COLORTEMP
Features enum : F_BRIGHTNESS, F_COLOR, F_COLORTEMP
Commands enum: C_OFF, C_ON, C_TOGGLE, C_BRIGHTNESS, C_COLOR, C_COLORTEMP
specific attributes : brightness, color, colorTemp
Specific commands available in QML
void setBrightness (int value);
void setColor (QColor value);
void setColorTemp (int value);
States enum : OPEN = 0, CLOSED = 1
Attributes enum : STATE, POSITION
Features enum : F_OPEN, F_CLOSE, F_STOP, F_POSITION
Commands enum : C_OPEN, C_CLOSE, C_STOP, C_POSITION
specific attributes : position
Specific commands available in QML
void close();
void open();
void stop();
void setPosition(int value);
This entity is used to replace IR remote controls. They have no attributes, only commands.
States enum : OFFLINE = 0, ONLINE = 1
Attributes enum : STATE
Features enum :
// Transport and mediacontrols
F_PLAY, F_PAUSE, F_PLAYTOGGLE, F_STOP, F_FORWARD, F_BACKWARD, F_NEXT, F_PREVIOUS, F_INFO, F_RECORDINGS, F_RECORD, F_LIVE,
// digits
F_DIGIT_0, F_DIGIT_1,F_DIGIT_2, F_DIGIT_3, F_DIGIT_4, F_DIGIT_5, F_DIGIT_6, F_DIGIT_7, F_DIGIT_8, F_DIGIT_9, F_DIGIT_10, F_DIGIT_10plus,
F_DIGIT_11, F_DIGIT_12, F_DIGIT_SEPARATOR, F_DIGIT_ENTER,
// navigation
F_CURSOR_UP, F_CURSOR_DOWN, F_CURSOR_LEFT, F_CURSOR_RIGHT, F_CURSOR_OK, F_BACK, F_HOME, F_MENU, F_EXIT, F_APP, // INFO is repeated twice
// power
F_POWER_OFF, F_POWER_ON, F_POWER_TOGGLE,
//tuner
F_CHANNEL_UP, F_CHANNEL_DOWN, F_CHANNEL_SEARCH, F_FAVORITE, F_GUIDE,
// interactive
F_FUNCTION_RED, F_FUNCTION_GREEN, F_FUNCTION_YELLOW, F_FUNCTION_BLUE, F_FUNCTION_ORANGE,
// video
F_FORMAT_16_9, F_FORMAT_4_3, F_FORMAT_AUTO,
// volume
F_VOLUME_UP, F_VOLUME_DOWN, F_MUTE_TOGGLE,
// input
F_INPUT_TUNER_1, F_INPUT_TUNER_2, F_INPUT_TUNER_X, F_INPUT_HDMI_1, F_INPUT_HDMI_2, F_INPUT_HDMI_X, F_INPUT_X_1, F_INPUT_X_2,
// output
F_OUTPUT_HDMI_1, F_OUTPUT_HDMI_2, F_OUTPUT_DVI_1, F_OUTPUT_AUDIO_X, F_OUTPUT_X,
// services
F_SERVICE_NETFLIX, F_SERVICE_HULU
Commands enum:
// Not entity related but mus be defined somewhere
C_REMOTE_CHARGED, C_REMOTE_LOWBATTERY,
// Transport and mediacontrols
C_PLAY, C_PAUSE, C_PLAYTOGGLE, C_STOP, C_FORWARD, C_BACKWARD, C_NEXT, C_PREVIOUS, C_INFO, C_RECORDINGS, C_RECORD, C_LIVE,
// digits
C_DIGIT_0, C_DIGIT_1,C_DIGIT_2, C_DIGIT_3, C_DIGIT_4, C_DIGIT_5, C_DIGIT_6, C_DIGIT_7, C_DIGIT_8, C_DIGIT_9, C_DIGIT_10, C_DIGIT_10plus,
C_DIGIT_11, C_DIGIT_12, C_DIGIT_SEPARATOR, C_DIGIT_ENTER,
// navigation
C_CURSOR_UP, C_CURSOR_DOWN, C_CURSOR_LEFT, C_CURSOR_RIGHT, C_CURSOR_OK, C_BACK, C_HOME, C_MENU, C_EXIT, C_APP, // INFO is repeated twice
// power
C_POWER_OFF, C_POWER_ON, C_POWER_TOGGLE,
//tuner
C_CHANNEL_UP, C_CHANNEL_DOWN, C_CHANNEL_SEARCH, C_FAVORITE, C_GUIDE,
// interactive
C_FUNCTION_RED, C_FUNCTION_GREEN, C_FUNCTION_YELLOW, C_FUNCTION_BLUE, C_FUNCTION_ORANGE,
// video
C_FORMAT_16_9, C_FORMAT_4_3, C_FORMAT_AUTO,
// volume
C_VOLUME_UP, C_VOLUME_DOWN, C_MUTE_TOGGLE,
// input
C_INPUT_TUNER_1, C_INPUT_TUNER_2, C_INPUT_TUNER_X, C_INPUT_HDMI_1, C_INPUT_HDMI_2, C_INPUT_HDMI_X, C_INPUT_X_1, C_INPUT_X_2,
// output
C_OUTPUT_HDMI_1, C_OUTPUT_HDMI_2, C_OUTPUT_DVI_1, C_OUTPUT_AUDIO_X, C_OUTPUT_X,
// services
C_SERVICE_NETFLIX, C_SERVICE_HULU
Specific commands available in QML
// transport and media controls
void play();
void pause();
void playToggle();
void stop();
void forward();
void backward();
void next();
void previous();
void info();
void recordings();
void record();
void live();
// navigation
void cursorUp();
void cursorDown();
void cursorLeft();
void cursorRight();
void cursorOK();
void back();
void home();
void menu();
void exit();
void app();
// power commands
void powerOn();
void powerOff();
void powerToggle();
// tuner commands
void channelUp();
void channelDown();
void channelSearch();
void toFavorite();
void guide();
// volume commands
void volumeUp();
void volumeDown();
void muteToggle();
States enum : OFF = 0, ON = 1, IDLE = 2, PLAYING = 3
Attributes enum : STATE, SOURCE, VOLUME, MUTED, MEDIATYPE, MEDIATITLE, MEDIAARTIST, MEDIAIMAGE, MEDIADURATION, MEDIAPROGRESS
Features enum : F_APP_NAME, F_MEDIA_ALBUM, F_MEDIA_ARTIST, F_MEDIA_DURATION, F_MEDIA_POSITION, F_MEDIA_IMAGE,
F_MEDIA_PROGRESS, F_MEDIA_TITLE, F_MEDIA_TYPE, F_MUTE, F_MUTE_SET, F_NEXT, F_PAUSE, F_PLAY,
F_PREVIOUS, F_SEARCH, F_SEEK, F_SHUFFLE, F_SOURCE, F_STOP, F_TURN_OFF,
F_TURN_ON, F_VOLUME, F_VOLUME_DOWN, F_VOLUME_SET, F_VOLUME_UP, F_LIST, F_SPEAKER_CONTROL
Commands enum : C_TURNOFF, C_TURNON, C_PLAY, C_PAUSE, C_STOP, C_PREVIOUS, C_NEXT, C_VOLUME_SET, C_VOLUME_UP,
C_VOLUME_DOWN, C_MUTE, C_BROWSE, C_SEARCH, C_SEARCH_ITEM, C_PLAY_ITEM, C_GETALBUM, C_GETPLAYLIST
specific attributes : source, volume, muted, mediaDuration, mediaProgress, mediaType, mediaTitle, mediaArtist, mediaImage
Specific commands available in QML
void play();
void pause();
void stop();
void previous();
void next();
void setVolume(int value);
void volumeUp();
void volumeDown();
extensions for media browsing
// browse item_key, "TOP", "BACK", "PLAY"
void browse (QString command);
// command PLAY, QUEUE, SHUFFLE, RADIO
void playMedia (const QString& command, const QString& itemKey);
// Search
void search (const QString& searchText, const QString& itemKey);
Mediaplayer uses Qt's QAbstractListModel to deliver browse results. The model is delivered to the remote using the function
void setBrowseModel(QObject* model);
void setSearchModel(QObject* model);
A list item consists of
QString item_key; // unique key
QString title; // like artist, ...
QString sub_title; // like album, ..
QString image_url; // album art
QString input_prompt; // for searchable items
The browse result also contains a header
QString type; // type of browse result (Artists, Albums, Tracks ...)
QString title; // artist name ...
int level; // hierarchy level
and a list of play commands which can be applied to the list items
QStringList playCommands; // PLAY, SHUFFLE, RADIO
Stated enum : OFFLINE = 0, ONLINE = 1
Attributes enum : STATE, CURRENT, FORECAST
Features enum : F_DETAIL
Commands enum : C_SETLOCATION
specific attributes : current, forecast
Current is a structure of weatherdata, forecast is a list of up to 5 such structures.
A structure contains
QString date; // Short name of the day
QString description; // Short weather description "mostly cloudy"
QString imageurl; // Icon url
QString temp; // Current, min, max of the day temperature including unit
QString rain; // Rain in mm
QString snow; // snow in mm
QString wind; // wind in km/h
QString humidity; // humidity in %
The value strings contains the values including unit (°C). To set the values integration can use this functions.
void setCurrent (const WeatherItem ¤t);
void setForecast (QObject *model); // Model derives from QAbstractListModel
}
#include "../remote-software/sources/entities/entitiesinterface.h"
#include "../remote-software/sources/entities/entityinterface.h"
// entities from setup
m_entities = qobject_cast<EntitiesInterface *> (entities);
EntityInterface* entity = m_entities->getEntityInterface("SomfyShutter|Left");
// set state and attribute using state text and attribute text
entity->setStateText("CLOSED");
entity->updateAttrByName("position", 77);
// set attribute using index
int index = entity->getAttrIndex("position");
entity->updateAttrByIndex(index, 66);
Using "concrete" interface
#include "../remote-software/sources/entities/blindinterface.h"
BlindInterface* blind = static_cast<BlindInterface*>(entity->getSpecificInterface());
// set state
entity->setState(BlindDef::CLOSED);
// or
entity->updateAttrByIndex(BlindDef::STATE, BlindDef::CLOSED);
// get current position
pos = blind->position();
// set position
entity->updateAttrByIndex(BlindDef::POSITION, 88);
To use the enums the registered object must be imported :
import Entity.MediaPlayer 1.0
if (obj.state == MediaPlayer.PLAYING) {
...
}