stroblme
c9fda50601
mqtt and http take websocket's vocabulary: their Mode is LISTENER/SENDER, default names read mqtt_listener_… and http_listener_…, and mqtt's publish_queue_size is send_queue_size. No alias stays behind, so the flow store rewrites the old setting in every published and draft mqtt node when it opens, in the same migration as trigger → debounce. Every mqtt and http setting carries a one-line description for the editor, and the node-types reference uses one wording for direction and says that an http sender publishes a JSON object response on its outputs.
165 lines
6.6 KiB
Markdown
165 lines
6.6 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 the Docker stack
|
|
|
|
You need Git, Docker with Compose v2, `make`, and `openssl`. Port 80 must be
|
|
free. Clone the public app repository and run its commands from the repo root:
|
|
|
|
```sh
|
|
git clone https://git.stroblme.de/Fluksio/app.git fluksio
|
|
cd fluksio
|
|
make init
|
|
make dev-local
|
|
```
|
|
|
|
`make init` creates `.env`, generates secrets, creates the `proxy` network,
|
|
and prints your admin login. It is safe to run again: existing secrets stay
|
|
as they are.
|
|
|
|
Give the containers a moment to start on the first build, then open
|
|
[http://app.localhost](http://app.localhost). Sign in with the admin login:
|
|
adding Python code requires a superuser account. The API is at
|
|
[http://api.localhost](http://api.localhost), and the docs are at
|
|
[http://docs.localhost](http://docs.localhost).
|
|
|
|
For a Docker instance reached from another machine on your network, use:
|
|
|
|
```sh
|
|
make dev-lan
|
|
```
|
|
|
|
Open `http://<host-ip>:8080`. Choose another port with
|
|
`make dev-lan APP_PORT=8081`. This is a development stack; see
|
|
[running it long term](#run-it-long-term) before using it for a deployment.
|
|
|
|
When you are done, stop the stack with `make down`. Your data volumes stay
|
|
in place 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.
|
|
|
|
Docker development stacks include a test broker at `mosquitto:1883`; it has
|
|
no published host port, so your physical sensors cannot reach it directly.
|
|
For real sensors, use your own broker. The Docker image includes the MQTT
|
|
and InfluxDB connector dependencies.
|
|
|
|
## 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 panels](../interface/dashboards.md) for widgets and pairing
|
|
a wall tablet.
|
|
|
|
For longer-term history, add an **InfluxDB** node that consumes
|
|
`living_temperature`. Configure your server 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.
|
|
|
|
The Docker development stack includes an InfluxDB test service at
|
|
`http://influxdb:8086`, with organization and bucket `fluksio` and token
|
|
`fluksio-dev-token`. It is for testing; configure a persistent InfluxDB server
|
|
for data you want to keep. The production stack includes neither InfluxDB nor
|
|
an MQTT broker.
|
|
|
|
## Run it long term
|
|
|
|
For a Docker deployment, run `make init`, then edit the repository's `.env`:
|
|
|
|
| Setting | Example |
|
|
|---|---|
|
|
| `DOMAIN` | `example.com` |
|
|
| `ENVIRONMENT` | `production` |
|
|
| `FRONTEND_HOST` | `https://app.example.com` |
|
|
| `VITE_API_URL` | `https://api.example.com` |
|
|
| `BACKEND_CORS_ORIGINS` | `https://app.example.com` |
|
|
| `FIRST_SUPERUSER` | your administrator email |
|
|
| `TZ` | your timezone, such as `Europe/Berlin` |
|
|
|
|
Keep the generated secrets. Stop any development stack with `make down`.
|
|
Set up DNS and a reverse proxy with HTTPS and WebSocket support before running
|
|
`make up`. That target starts the application services; it requires a proxy
|
|
on the Docker `proxy` network. Route
|
|
`app.example.com` to `fluksio-app:80`, `api.example.com` to `fluksio-api:8000`
|
|
and, optionally, `docs.example.com` to `fluksio-docs:80`.
|
|
|
|
`docker/compose.traefik.yml` is an optional proxy configuration. It also needs
|
|
`EMAIL`, `USERNAME` and `HASHED_PASSWORD` for certificates and dashboard
|
|
authentication; `make init` does not set these up.
|
|
|
|
The published port from `make dev-lan` uses HTTP. For access outside your
|
|
network, use HTTPS or [enroll with the portal](../interface/portal.md).
|
|
|
|
Back up `.env` and both persistent volumes: `app-flow-data` holds the database,
|
|
flows, secrets and artifacts; `app-redis-data` holds message values, node state
|
|
and queued work. Compose prefixes volume names with the project name
|
|
`fluksio-app`. Also back up any external MQTT or InfluxDB data you need.
|
|
|
|
## Next steps
|
|
|
|
- [Flows, nodes and messages](../concepts/flows.md): how the graph works.
|
|
- [Secrets, modules and alerts](../interface/operations.md): credentials and notifications.
|
|
- [Remote workers](../code/workers.md): run node code on another machine.
|
|
- [Configuration](../reference/configuration.md): settings and storage paths.
|