2 files changed, 124 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
new file mode 100644
index 0000000..918ec19
--- /dev/null
+++ b/doc/api/README.md
@@ -0,0 +1,13 @@
+# API specification
+
+This folder contains the API specification as required by semantic versioning.
+
+Currently only the `future.md` file is given. This is the long term goal how
+the API should look like at the time of writing / committing.
+
+This will be extended by a `current.md` file describing the current state using
+the same structure. This version has to match always with the implementation in
+every commit.
+
+By this approach it will be possible to see what is left to implement by
+running `diff current.md future.md`.
diff --git a/doc/api/future.md b/doc/api/future.md
new file mode 100644
index 0000000..7486529
--- /dev/null
+++ b/doc/api/future.md
@@ -0,0 +1,111 @@
+# UART Shell
+
+This is based on the Zephyr shell. It is not part of the public API as defined
+by semantic versioning and has no stability guarantees. It is a pure
+development and debugging tool.
+
+# IPv6
+
+The device will assign itself the link-local address based on its
+hardware-provided EUI-48 MAC address without privacy extension.
+
+This makes the device discoverable in the network with a ping to the all-nodes
+IPv6 multicast address. The following example assumes the network interface for
+the discovery is `eth0`.
+
+```
+ping -c 1 ff02::1%eth0
+```
+
+If the EUI-48 MAC address of the target device is known the device can also be
+accessed directly with its link-local address.
+
+# HTTP Server
+
+- `GET /` `application/json` (returns device info, see below)
+
+- `GET    /settings` `application/json`
+- `PUT    /settings` `application/json`
+
+# Device Info
+
+```
+{
+    "hostname": "mydevice",
+    "type": {
+        "text": "iot-contact",
+        "uuid": "eeb58c52-8e25-489c-9a1a-c4662fc9318a"
+    },
+    "version": {
+        "hardware": "v1.2.3",
+        "firmware": "v4.5.6"
+    },
+    "address": {
+        "mac": {
+            "eui-48": "00:00:5e:00:53:01"
+        }
+    }
+}
+```
+
+# Settings
+
+```
+{
+    "hostname": "mydevice",
+    "update": {
+        "url": "https://deploy.xengineering.eu/git/iot-contact/latest/"
+    },
+    "mqtt": {
+        "url": "mqtt://mqtt.example.com/path/to/root"
+    },
+    "syslog": {
+        "target": {
+            "ip": "192.168.1.12",
+            "port": 514
+        }
+    },
+    "blind": {
+        "time_up_down_ms": 12000
+    }
+}
+```
+
+# MQTT
+
+All topics have the following structure:
+
+```
+<prefix>/<api-version>/<api-path>
+```
+
+The `<prefix>` is selected by the user. It is a system setting to make it
+possible to move the device API to a specific location in the topic namespace
+of a broker.
+
+The `<api-version>` is the Semantic Versioning string like `v1.2.3` of the
+currently running firmware. It is recommended to use a `+` single-level
+wildcard here for subscriptions. On each message the version string can be
+parsed from this location to check if the message is compatible with the
+receiving entity.
+
+The `<api-path>` is fixed by the firmware implementation. This is the only part
+noted down explicitly in the following MQTT API documentation.
+
+These are the topics to which the device publishes. Users should not publish to
+these and only subscribe.
+
+- `blind/closure` QoS 1 retained (`0`, `1`, ... `100`)
+- `blind/motion` QoS 1 retained (`up`, `down`, `stopped`)
+- `contact/state` QoS 1 retained (`open`, `closed`)
+- `heartbeat` QoS 0 not retained (period in milliseconds, "on-time" in milliseconds)
+- `update/required` QoS 2 not retained (`true`, `false`)
+
+These are the topics the device subscribes to. Users can publish there and
+optionally subscribe to them to see messages from other users if required. The
+annotations according Quality of Service (QoS) and the retained flag should be
+followed.
+
+- `blind/closure/set` QoS 2 not retained (`0`, `1`, ... `100`)
+- `blind/motion/set` QoS 2 not retained (`up`, `down`, `stopped`)
+- `update/trigger` QoS 2 not retained