Initialize project.

1 files changed, 102 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..01fb80a
--- /dev/null
+++ b/README.org
@@ -0,0 +1,102 @@
+#+TITLE: FAPG DAQ system
+#+AUTHOR: Marius PETER
+#+DATE: <2026-06-27 Sat>
+
+* Overview
+
+The goal of this project is to deploy a DAQ network at the FAPG.
+Sensor nodes periodically send readings to a central DAQ hub.  An
+external VPS obtains these readings, and displays them on a web
+dashboard.
+
+* Architecture
+
+#+begin_src plantuml :file docs/architecture.png
+  @startuml
+  title FAPG DAQ - from reading to web dashboard
+
+  actor "Farm user/browser" as Browser
+
+  participant "EZO probe\npH / EC / DO / Redox" as Probe
+  participant "Pi Zero 2W\nfapg-daq service" as Zero
+  participant "Pi 5\nMosquitto MQTT broker" as Broker
+  participant "VPS\nMQTT subscriber service" as VPSSubscriber
+  database "Readings database\nSQLite / PostgreSQL" as DB
+  participant "VPS\nLive dashboard app" as Dashboard
+
+  == DAQ acquisition ==
+
+  Zero -> Probe : Request UART reading
+  Probe --> Zero : Return raw sensor value
+
+  Zero -> Zero : Normalize reading
+
+  == MQTT publication ==
+
+  Zero -> Broker : MQTT PUBLISH\nfapg/daq/<probe>/<node>/reading\nJSON payload
+
+  note right of Zero
+  	Example payload:
+  	{
+  		"schema": "fapg.daq.reading.v1",
+  		"node": "fapg-zero-ph-01",
+  		"probe": "ph",
+  		"value": 7.12,
+  		"unit": "pH",
+  		"timestamp": "2026-06-27T13:45:00Z"
+  	}
+  end note
+
+  VPSSubscriber -> Broker : MQTT SUBSCRIBE\nfapg/daq/+/+/reading
+  Broker --> VPSSubscriber : MQTT MESSAGE\nreading topic + JSON payload
+
+  VPSSubscriber -> VPSSubscriber : Validate topic and payload\nparse probe, node, value, timestamp
+
+  == Database storage ==
+
+  VPSSubscriber -> DB : INSERT reading
+  DB --> VPSSubscriber : OK
+
+  == Live dashboard presentation ==
+
+  Browser -> Dashboard : Open HTTPS dashboard
+  Dashboard -> DB : SELECT recent readings
+  DB --> Dashboard : Return recent readings
+  Dashboard --> Browser : Initial HTML + Chart.js data
+
+  loop live updates
+  	VPSSubscriber -> Dashboard : Notify new reading\nWebSocket / SSE / app event
+  	Dashboard --> Browser : Push new reading\nWebSocket or Server-Sent Events
+  	Browser -> Browser : Append point to Chart.js chart
+  end
+
+  @enduml
+#+end_src
+
+#+RESULTS:
+[[file:docs/architecture.png]]
+
+** Hosts
+
+*** Raspberry Pi Zero 2W
+
+These hosts collect DAQ readings, and publish them via MQTT on the
+LAN.
+
+| Pi Zero | Probe |
+|---------+-------|
+|      01 | PH    |
+|      02 | EC    |
+|      03 | DO    |
+|      04 | ORP   |
+
+
+*** Raspberry Pi 5
+
+This host brokers MQTT messages sent on the LAN.
+
+*** VPS
+
+This host establishes a VPN connection with the Pi 5 host, subscribes
+to all MQTT topics, saves messages to a database, and exposes a
+realtime web dashboard available over the internet.