155 lines
5.5 KiB
Markdown
155 lines
5.5 KiB
Markdown
# Getting started: facility automation
|
|
|
|
Build a small temperature flow, then connect a real sensor when you're ready.
|
|
No hardware required for the first lap.
|
|
|
|
## Start Fluksio
|
|
|
|
You need Git and Docker with Compose v2 on a 64-bit machine, x86 or ARM. A
|
|
Raspberry Pi 4 or 5 with a 64-bit OS works too. Clone the app repository and
|
|
start its single container. Replace `<repository-url>` with the app
|
|
repository's URL:
|
|
|
|
```sh
|
|
git clone <repository-url> fluksio
|
|
cd fluksio
|
|
docker compose up -d
|
|
docker compose logs fluksio
|
|
```
|
|
|
|
The first build takes a few minutes, longer on a Raspberry Pi. The log shows
|
|
the admin account and its password once, on the first start. Open
|
|
[http://localhost:8080](http://localhost:8080) and sign in. Adding Python code
|
|
requires that superuser account.
|
|
|
|
Everything runs in that one container on one port: the engine, its API and the
|
|
dashboard. To use another port, change the left side of `ports` in
|
|
`compose.yml`, for example `"9000:8000"`. From another machine on your network,
|
|
open `http://<host-ip>:8080`. Set `FRONTEND_HOST` in `compose.yml` to the
|
|
address you open, since links for wall panels and mails are built from it.
|
|
|
|
The image starts minimal. MQTT, InfluxDB, outbound mail and the rest are
|
|
[extras](../reference/configuration.md#image-options). Add the ones you need to
|
|
`EXTRAS` in `compose.yml` and rebuild:
|
|
|
|
```yaml
|
|
args:
|
|
EXTRAS: "mqtt,influx"
|
|
```
|
|
|
|
```sh
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Stop the container with `docker compose down`. Your data stays on the `data`
|
|
volume for the next start.
|
|
|
|
## Your first flow
|
|
|
|
Open **Flows**, create a flow named `house`, and use **Add node** to add an
|
|
**Inject** node. In its panel:
|
|
|
|
- Under **Provides**, add `living_temperature` with type `float`.
|
|
- Under **Settings**, set the `living_temperature` value to `18.0` and
|
|
**Interval** to `5` seconds.
|
|
|
|
This gives you a pretend sensor. Add a **Function** node with:
|
|
|
|
- **Consumes**: `living_temperature`, type `float`.
|
|
- **Provides**: `heat_wanted`, type `bool`.
|
|
|
|
In the code editor, enter:
|
|
|
|
```python
|
|
def process(living_temperature):
|
|
return {"heat_wanted": living_temperature < 21.0}
|
|
```
|
|
|
|
Message names connect the nodes automatically; there are no wires to draw.
|
|
Save the code with ⌘S / Ctrl-S, then click **Publish** in the dock. Open
|
|
**Flow settings** from the dock's pencil button and make sure **Running** is on.
|
|
|
|
Every five seconds, `18.0` should produce `true`. Select the Function and check
|
|
the value under its `heat_wanted` output. Change the Inject value to `22.0`,
|
|
publish again, and check that the result becomes `false`. Click the edge to
|
|
inspect the temperature readings. Your first bit of automation is alive.
|
|
|
|
If nothing happens, open **Issues** and **Logs** in the dock. They show missing
|
|
inputs, code errors and connection problems. See [The flow editor](../interface/flow-editor.md)
|
|
for the controls and shortcuts.
|
|
|
|
## Connect a real sensor
|
|
|
|
Replace the Inject node with an **MQTT** node:
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| **Provides** | `living_temperature`, type `float` |
|
|
| `broker_host` | your broker's hostname or IP, reachable from the engine |
|
|
| `topic` | the sensor's temperature topic |
|
|
|
|
Publish the change. The Function now responds to sensor readings instead of
|
|
the test value. If your sensor sends a JSON object such as
|
|
`{"temperature": 18.0}`, set `json_key` to `temperature`.
|
|
|
|
An MQTT node with inputs is a sender and publishes to its configured topic;
|
|
one with outputs only is a listener and subscribes. Add a sender only after
|
|
checking the payload format your device expects. A relay may need `ON` and
|
|
`OFF` rather than a boolean.
|
|
|
|
!!! tip "Keep the first test on screen"
|
|
|
|
Check both warm and cold readings before connecting an actuator. **Pause**
|
|
and **Step** let you inspect queued messages one at a time. A real heating
|
|
controller also needs appropriate limits and hysteresis.
|
|
|
|
The MQTT node needs the `mqtt` extra. Fluksio does not run a broker, so point
|
|
the node at your own, such as Mosquitto.
|
|
|
|
## Show it on a dashboard
|
|
|
|
Create a dashboard and add a gauge bound to `house.living_temperature`.
|
|
Publish the dashboard to see the current reading. Dashboard controls can also
|
|
publish messages, so choose their bindings with care.
|
|
|
|
See [Dashboards and devices](../interface/dashboards.md) for widgets and pairing
|
|
a wall tablet.
|
|
|
|
For longer-term history, add an **InfluxDB** node that consumes
|
|
`living_temperature`. It needs the `influx` extra. Configure your database URL,
|
|
organization, bucket, token and `writes` mapping. Store the token under
|
|
**Secrets** and select it in the node's credential field.
|
|
[Node types](../reference/node-types.md#influxdb)
|
|
has the write and query formats.
|
|
|
|
Run InfluxDB separately, just like the MQTT broker.
|
|
|
|
## Run it long term
|
|
|
|
The container from `compose.yml` is fit for long-term use. It restarts with
|
|
Docker, and `/data` holds everything it keeps: the database, the flows,
|
|
secrets, artifacts and its Redis. Back up that volume. Compose prefixes its
|
|
name with your project name.
|
|
|
|
The container speaks plain HTTP. For access from outside your network, put a
|
|
reverse proxy with HTTPS and WebSocket support in front of it, such as Caddy,
|
|
Traefik or nginx, or [enroll with the portal](../interface/portal.md).
|
|
For example, a Caddyfile can proxy your app address:
|
|
|
|
```text
|
|
fluksio.example.com {
|
|
reverse_proxy localhost:8080
|
|
}
|
|
```
|
|
|
|
Set `FRONTEND_HOST` to `https://fluksio.example.com` and `TZ` to your
|
|
timezone, such as `Europe/Berlin`. See [Configuration](../reference/configuration.md)
|
|
for the other settings, which go under `environment` in `compose.yml`.
|
|
|
|
To update, pull the repository and rebuild:
|
|
|
|
```sh
|
|
git pull
|
|
docker compose up -d --build
|
|
```
|