# 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`)