1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
# 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/firmware/version` `text/plain`
- `GET /device/mac-address/eui-48` `text/plain`
- `GET /settings` `application/json`
- `PUT /settings` `application/json`
# 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`)
|
