# 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.

These are the topics to which the device publishes. Users should not publish to
these and only subscribe.

- `heartbeat` QoS 0 not retained (period in milliseconds, "on-time" in milliseconds)
- `update/required` QoS 2 not retained (`true`, `false`)
- `contact/state` QoS 1 retained (`open`, `closed`)
- `blind/closure` QoS 1 retained (`0`, `1`, ... `100`)
- `blind/motion` QoS 1 retained (`up`, `down`, `stopped`)

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.

- `update/trigger` QoS 2 not retained
- `request/blind/motion` QoS 2 not retained (`up`, `down`, `stopped`)
- `request/blind/closure` QoS 2 not retained (`0`, `1`, ... `100`)