@startmindmap

+[#lightgreen] Topic
++ Access

+++ REST API

++++ Base URI: http://<HOSTNAME>/rest/api/v1

++++ GET
+++++ URL: <BASE-URI>/display/uid/<PLUGIN-UID>/<PLUGIN-TOPIC>
+++++ URL: <BASE-URI>/display/alias/<PLUGIN-ALIAS>/<PLUGIN-TOPIC>

++++ POST
+++++ URL: <BASE-URI>/display/uid/<PLUGIN-UID>/<PLUGIN-TOPIC>
+++++ URL: <BASE-URI>/display/alias/<PLUGIN-ALIAS>/<PLUGIN-TOPIC>

+++++ Parameters via HTTP arguments
******: key=value __converts to__
<code>
{
    "key": "value"
}
</code>;
******: key.sub=value __converts to__
<code>
{
    "key": {
        "sub": "value"
    }
}
</code>;
******: key._0_=value __converts to__
<code>
{
    "key": [
        "value"
    ]
}
</code>;
******: key._0_.sub=value __converts to__
<code>
{
    "key": [{
        "sub": "value"
    }]
}
</code>;

+++++ A file is BASE64 encoded and provided in HTTP body.


++++ General response
+++++ In case of successful request
******:
<code>
{
    "data": {},
    "status": "ok"
}
</code>;

+++++ In case of an error
******:
<code>
{
    "data": {},
    "status": "error"
}
</code>;
+++++ The data element contains the request specific information.

+++ MQTT API

++++ Homeassistant auto discovery
+++++ Topic with plugin UID: <HOMEASSISTANT-DISCOVERY-PREFIX>/<HOMEASSISTANT-COMPONENT>/<HOSTNAME>/<PLUGIN-UID>/config
*****:
<code>
{
  "name": "MQTT text",
  "object_id": "19583",
  "unique_id": "pixelix-facfc834/19583",
  "device": {
    "identifiers": "F4:12:FA:CF:C8:34",
    "configuration_url": "http://192.168.2.62",
    "name": "pixelix-facfc834",
    "model": "Pixelix",
    "manufacturer": "BlueAndi & Friends",
    "sw_version": "v7.0.0"
  },
  "state_topic": "pixelix-facfc834/uid/19583/text/state",
  "value_template": "{{ value_json.text }}",
  "command_topic": "pixelix-facfc834/uid/19583/text/set",
  "command_template": "{\"text\": \"{{ value }}\" }"
}
</code>;
+++++ Topic with plugin alias: <HOMEASSISTANT-DISCOVERY-PREFIX>/<HOMEASSISTANT-COMPONENT>/<HOSTNAME>/<PLUGIN-ALIAS>/config
*****:
<code>
{
  "name": "MQTT text",
  "object_id": "display",
  "unique_id": "pixelix-facfc834/display",
  "device": {
    "identifiers": "F4:12:FA:CF:C8:34",
    "configuration_url": "http://192.168.2.62",
    "name": "pixelix-facfc834",
    "model": "Pixelix",
    "manufacturer": "BlueAndi & Friends",
    "sw_version": "v7.0.0"
  },
  "state_topic": "pixelix-facfc834/alias/display/text/state",
  "value_template": "{{ value_json.text }}",
  "command_topic": "pixelix-facfc834/alias/display/text/set",
  "command_template": "{\"text\": \"{{ value }}\" }"
}
</code>;
++++ HOMEASSISTANT-DEVICE-CLASS
+++++ Customizeable in Home assistant: https://www.home-assistant.io/docs/configuration/customizing-devices
+++++ Skipped, because no matching device class is available.
++++ HOMEASSISTANT-COMPONENT
+++++ Components nowadays integrations: https://www.home-assistant.io/integrations
+++++ The integration depends on the plugin.
+++++ Integration: text
++++++ https://www.home-assistant.io/integrations/text.mqtt/
+++++ Integration: sensor
++++++ https://www.home-assistant.io/integrations/sensor.mqtt/

++++ Status
+++++ MQTT topic: <HOSTNAME>/uid/<PLUGIN-UID>/<PLUGIN-TOPIC>/state
+++++ MQTT topic: <HOSTNAME>/alias/<PLUGIN-ALIAS>/<PLUGIN-TOPIC>/state
+++++ Direction: Pixelix --> Client(s)
++++ Command
+++++ MQTT topic: <HOSTNAME>/uid/<PLUGIN-UID>/<PLUGIN-TOPIC>/set
+++++ MQTT topic: <HOSTNAME>/alias/<PLUGIN-ALIAS>/<PLUGIN-TOPIC>/set
+++++ Direction: Client(s) --> Pixelix
++++ Availability
+++++ MQTT topic: <HOSTNAME>/uid/<PLUGIN-UID>/<PLUGIN-TOPIC>/available
+++++ MQTT topic: <HOSTNAME>/alias/<PLUGIN-ALIAS>/<PLUGIN-TOPIC>/available
+++++ Direction: Pixelix --> Client(s)
+++++ "online"/"offline"
+++++ Skipped for the moment. May be supported in future.

-- A plugin deals only with topics\nand doesn't know about REST or MQTT.
-- Device identification
--- Unique hostname (HOSTNAME)
-- Plugin identification
--- Unique plugin ID (PLUGIN-UID) assigned at instance creation
--- Unique plugin alias (PLUGIN-ALIAS) assigned by user

@endmindmap
