Skip to content

Latest commit

 

History

History
113 lines (87 loc) · 4.87 KB

MQTT.md

File metadata and controls

113 lines (87 loc) · 4.87 KB

PIXELIX

PIXELIX

License

Plugin development

MQTT

Pixelix is a MQTT client which can be connected to a MQTT broker. The MQTT broker URL is configued in the settings via webinterface.

Format: [mqtt://][<USER>:<PASSWORD>@]<URI>

Examples:

Overview Mindmap

topic-handling-mindmap

MQTT Topics

mqtt-topic-mindmap

Birth and last will

Pixelix supports birth and last will messages (retained).

After the successful connection establishment to the MQTT broker, Pixelix will send "online" to the <HOSTNAME>/status topic. In any disconnect case, "offline" will be sent to the <HOSTNAME>/status topic.

Plugin topic path

The MQTT base topic path to access plugin related topics can be setup with the plugin UID or the plugin alias:

  • <HOSTNAME>/display/uid/<PLUGIN-UID>/<TOPIC>
  • <HOSTNAME>/display/alias/<PLUGIN-ALIAS>/<TOPIC>

Readable/Writeable Topic

If a topic is readable or writeable, use the following suffixes for the MQTT base path:

  • For readable topics, add /state to the base path.
  • For writeable topics, add /set to the base path.
  • For topics that are both readable and writeable, use both paths.

This ensures clear communication and control over the topics.

Topic name

The complete topic name can be derived from the REST API documentation.

Example: JustTextPlugin

The REST API URL looks like the following: http://<HOSTNAME>/rest/api/v1/display/uid/<PLUGIN-UID>/<TOPIC>?text=<TEXT>

  1. Replace the http://<HOSTNAME>/rest/api/v1/ part with <HOSTNAME> and remove the parameters which will look like <HOSTNAME>/display/uid/<PLUGIN-UID>/<TOPIC>
  2. To read from the topic, add /state: <HOSTNAME>/display/uid/<PLUGIN-UID>/<TOPIC>/state
    • Every URL parameter, which is in this case text=<TEXT> will be received in JSON format.
    {
    "text": "<TEXT>"
}
  3. To write to the topic, add /set: <HOSTNAME>/display/uid/<PLUGIN-UID>/<TOPIC>/set
    • Every URL parameter, which is in this case text=<TEXT> must be sent in JSON format.
    {
    "text": "<TEXT>"
}

Sending a bitmap

The JSON data must have two keys:

  • fileName: The name of the file which to upload.
  • file: The file itself in BASE64 encoded.

Example: IconTextPlugin

{
    "fileName": "hacker.bmp",
    "file": "Qk32AAAAAAAAADYAAAAoAAAACAAAAAgAAAABABgAAAAAAMAAAAAAAAAAAAAAAAAAAAAAAAAAzEg/AAAAAAAAAAAAzEg/zEg/AAAAAAAAAAAAzEg/zEg/zEg/zEg/AAAAAAAAAAAAAAAAzEg/AAAAAAAAAAAAAAAAJBztJBztAAAAzEg/AAAAzEg/zEg/zEg/AAAAJBztAAAAAAAAzEg/AAAAAAAAAAAAAAAAJBztAAAAAAAAAAAAzEg/zEg/AAAAAAAAJBztAAAAAAAAAAAAzEg/zEg/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

Sensors

The sensor topic path is valid if the sensor is available!

  • Temperature in °C: <HOSTNAME>/sensors/0/temperature/state
  • Humidity in %: <HOSTNAME>/sensors/1/humidity/state
  • Illuminance in lx: <HOSTNAME>/sensors/2/illuminance/state
  • Battery SOC in %: <HOSTNAME>/sensors/3/soc/state

Issues, Ideas And Bugs

If you have further ideas or you found some bugs, great! Create a issue or if you are able and willing to fix it by yourself, clone the repository and create a pull request.

License

The whole source code is published under the MIT license. Consider the different licenses of the used third party libraries too!

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.