# Sia server

Sia server is an Internet of Things (IoT) server. It should be compatible with
multiple devices from different vendors. The user interface should be
implemented by apps connecting to this central Sia server.

## Supported vendors and devices

### Homematic IP

[Homematic IP][1] with the [OpenCCU][2] as central device is supported with
these IoT products:

- [HmIP-SWDO-2][3] - optical window or door contact

### Shelly

[Shelly][8] is supported with the following product:

- [Shelly 2PM Gen3][7] - twin relay e.g. for roller shutter control

The implemented API is documented [here][6].

## Build instructions

The Sia server is built and tested with the Meson build automation tool.

```
meson setup build
meson compile -C build
meson test -C build
```

Build artefacts can be shown with the `tar` archive tool and `less` pager.

```
tar -tf build/sia-server-v*.tar.zst | less
```

All relevant build results are part of this Zstandard-compressed tar archive.

## Usage

On a `linux/amd64` machine the Sia server can be launched with default
configuration in an unpacked deploy archive.

```
./sia-server-linux-amd64
```

The command line interface is documented in the help page.

```
./sia-server-linux-amd64 -help
```

The configuration file format can be looked up based on the
`configs/default.json` file.

The files in the `systemd` folder are provided for integration into
[systemd][4]-based Linux distributions.

## Versioning and public Application Programming Interface (API)

This project adheres to [Semantic Versioning][5].

Only aspects explicitly stated here are part of the public API:

- file and folder structure of the deploy archive
- `sia-server-linux-amd64` command line interface
- configuration file format
- MQTT interface

## MQTT interface

The Sia server connects to a MQTT broker and exposes its client interface
there.

The MQTT broker host, port and the Sia server's client ID is configured via the
Sia configuration file.

Furthermore a topic prefix is selected. **All topics documented below are
implicitly prefixed with this topic prefix.** This allows using multiple Sia
server instances on one MQTT broker.

All message payloads are UTF-8 encoded strings.

For all terms not explained here see the [MQTT version 3.1.1 documentation][9].

### `/server/health`

- description: Indicates if Sia server is connected to the broker
- direction: Sia server to client
- Quality of Service: QoS 1 (at least once)
- retained: yes
- receives will message: yes, indicating sudden disconnect of Sia server
- topic parameters: none
- payloads:
    - `good`: Sia server is connected to MQTT broker
    - `bad`: Sia server is disconnected from MQTT broker

### `/contact/<id>/state`

- description: Indicates state of Homematic IP SWDO-2 contacts
- direction: Sia server to client
- Quality of Service: QoS 1 (at least once)
- retained: yes
- receives will message: no
- topic parameters:
    - `id`: ID of the Homematic IP SWDO-2 contact
- payloads:
    - `open`: contact is open
    - `closed`: contact is closed

[1]: https://homematic-ip.com/
[2]: https://openccu.de/
[3]: https://homematic-ip.com/en/product/window-and-door-contact-optical
[4]: https://systemd.io/
[5]: https://semver.org/
[6]: https://shelly-api-docs.shelly.cloud/gen2/
[7]: https://www.shelly.com/de/products/shelly-2pm-gen3-1/
[8]: https://shelly.com/
[9]: https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html