doc: api: future: Add first draft

1 files changed, 101 insertions, 0 deletions

diff --git a/doc/api/future.md b/doc/api/future.md
new file mode 100644
index 0000000..f6e418c
--- /dev/null
+++ b/doc/api/future.md
@@ -0,0 +1,101 @@
+# Future iot-contact API
+
+This is a draft for the long term goal of the `iot-contact` external API. It is
+**not the current state**.
+
+## 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    /device/type` `text/plain`
+- `GET    /device/type/uuid` `text/plain`
+- `GET    /device/hardware/version` `text/plain`
+- `GET    /device/mac-address/eui-48` `text/plain`
+- `POST   /device/reboot`
+
+- `GET    /settings` `application/json`
+- `PUT    /settings` `application/json`
+
+- `GET    /firmware/bootloader/version` `text/plain`
+- `GET    /firmware/bootloader` `application/octet-stream`
+
+- `GET    /firmware/application/active/version` `text/plain`
+- `GET    /firmware/application/active` `application/octet-stream`
+- `GET    /firmware/application/active/confirmed-flag` `text/plain`
+- `PUT    /firmware/application/active/confirmed-flag` `text/plain`
+
+- `GET    /firmware/application/inactive/version` `text/plain`
+- `GET    /firmware/application/inactive` `application/octet-stream`
+- `PUT    /firmware/application/inactive` `application/octet-stream`
+- `DELETE /firmware/application/inactive`
+- `GET    /firmware/application/inactive/test-boot-flag` `text/plain`
+- `PUT    /firmware/application/inactive/test-boot-flag` `text/plain`
+
+## Settings
+
+```
+{
+    "hostname": "mydevice",
+    "mqtt": {
+        "broker": "mqtt://...",
+        "prefix": "com/example/"
+    },
+    "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.
+
+- read-only  `heartbeat` (period in milliseconds, "on-time" in milliseconds)
+- read-only  `contact/state` (`open`, `closed`)
+- read-only  `blind/closure` (`0`, `1`, ... `100`)
+- write-only `request/blind/closure` (`0`, `1`, ... `100`)
+- read-only  `blind/motion` (`up`, `down`, `stopped`)
+- write-only `request/blind/motion` (`up`, `down`, `stopped`)