# 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/",
        "automation": {
            "enable": false,
            "hour": null,
            "minute": null,
            "second": null
        }
    },
    "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`)
- write-only `update/trigger`
- read-only  `update/required` (`true`, `false`)