====== Meta API ======

The goal of the Meta API is to provide a common interface for hybrid projects allowing projects to exchange control messages with each other. This way, it is possible to influence the behavior of one project from within another project.

An Example: One project could be a remotely controllable light installation, another project could be an online world accessible for remote participants. Using the Meta API, it is possible for controls within the online world to control the physical light installation. Also, the online world could react to the settings currently set to the light installation from even more projects connected to the common interface.

===== Existing Implementations of this Specification =====

Here is a list of already existing implementations for the Meta API.

   * Python 3
     * Coming Soon !

===== Technical Details =====

This section deals with low level implementation details in case you want to write your own implementation of the Meta API on top of MQTT. In case you are overwhelmed with this section, try to use one of the already existing implementations first.

The Meta API will be based on **MQTT Version 5** ([[https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.pdf|Specification]]) although backwards compatibility to MQTT Version 3 should be maintained where possible.

It is **strongly recommended to follow the conventions** for serializing data outlined over the next two subsections. In case you decide not to follow the conventions, this **may lead to data errors** when other projects want to communicate with your project.

==== JSON Messages ====

Please ensure that you only send valid JSON strings according to the [[https://www.ecma-international.org/wp-content/uploads/ECMA-404_2nd_edition_december_2017.pdf|ECMA-404 Standard 2nd Edition]] from 2017. A summary of this standard may also be found [[https://www.json.org/json-en.html|here]].

Once you constructed a valid JSON string, please encode this string using **UTF-8**, and put only the encoded string in a MQTT Message, **followed by a single byte with the value ''0x00''**

==== Binary Messages ====

For a more compact message size, it is also possible to use binary messages. In order to eliminate encoding errors, the following conventions should be used.

=== Primitives ===

== Boolean Values ==

Boolean values are **represented by a single byte**. This byte should be **''0x00'' for all ''FALSE'' values**, and any other value for all ''TRUE'' values. By convention, it is recommended to set the value to **''0x01'' for all representations of ''TRUE''**

== Integer Values ==

Integers are serialized as binary values with **big-endian byte order** for any datatypes that require more than a single byte for representation. **Negative values are encoded using [[https://en.wikipedia.org/wiki/Two's_complement|two’s complement]]**. The following integer types are defined:

^**Name**  ^**Byte Count**  ^**Signed**  ^**Minimal Value**  ^**Maximal Value**  ^**Also known as**       ^
|Int8      |1               |Yes         |-127               |127                |Byte, Char (Signed)     |
|UInt8     |1               |No          |0                  |255                |Byte (Unsigned)         |
|Int16     |2               |Yes         |                   |                   |Short                   |
|UInt16    |2               |No          |                   |                   |UShort                  |
|Int32     |4               |Yes         |                   |                   |Integer, Int            |
|UInt32    |4               |No          |                   |                   |Unsigned Integer, UInt  |
|Int64     |8               |Yes         |                   |                   |Long                    |
|UInt64    |8               |No          |                   |                   |ULong                   |

== Floating Point Values ==

Floating point values are **represented using the [[https://en.wikipedia.org/wiki/IEEE_754|IEEE Standard for Floating-Point Arithmetic (IEEE 754)]]**. In particular, 32 bit floating points should be encoded in the binary32 format (also known as Single precision), 64 bit floating points should be encoded in the binary64 format (also known as Double precision). Please also choose **big-endian byte order**.

== String Values ==

String values should be encoded using the **UTF-8 encoding**. The string data **must be followed by a single byte containing the value ''0x00''**

=== Data Structures ===

== Fixed Size Arrays ==

A fixed size array (where the size of the array is constant for all instances where the array is used) is serialized as //n// repetitions of the base type of the array for a fixed size of //n//

== Dynamic Size Arrays ==

Dynamic sized arrays are any list-type arrays, whose size is dependent on the message instance.

Dynamic sized arrays can be serialized by **first serializing the length //n// of the array as Int32**, and then all //n// objects within the array in order (First element gets serialized first in the message, second as second element, and so on...).