From 40993ba522ccd09d40910489b9f805a15077e524 Mon Sep 17 00:00:00 2001
From: Birte Kristina Friesel <derf@finalrewind.org>
Date: Sun, 14 Jan 2024 17:17:47 +0100
Subject: Document setup and application example

---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++----------
 init.lua  |  3 +--
 2 files changed, 41 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 99255ef..de2281b 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
-# ESP8266 Lua/NodeMCU module for Sensirion SCD40/SCD41 CO₂ sensor
+# ESP8266 Lua/NodeMCU module for Sensirion SCD4x CO₂ sensors
 
 This repository contains an ESP8266 NodeMCU Lua module (`scd4x.lua`) as well as
 MQTT / HomeAssistant / InfluxDB integration example (`init.lua`) for
-**Sensirion SCD40/SCD41** CO₂ sensors.
+**Sensirion SCD4x** CO₂ sensors connected via I²C.
 
 ## Dependencies
 
@@ -18,33 +18,63 @@ modules.
 * mqtt
 * node
 * tmr
-* uart
 * wifi
 
+## Setup
+
+Connect the SCD4x sensor to your ESP8266/NodeMCU board as follows.
+
+* SCD4x GND → ESP8266/NodeMCU GND
+* SCD4x 3V3 → ESP8266/NodeMCU 3V3
+* SCD4x SCL → NodeMCU D1 (ESP8266 GPIO4)
+* SCD4x SDA → NodeMCU D2 (ESP8266 GPIO5)
+
+SDA and SCL must have external pull-up resistors to 3V3.
+
+If you use different pins for SDA and SCL, you need to adjust the
+i2c.setup call in the examples provided in this repository to reflect
+those changes. Keep in mind that some ESP8266 pins must have well-defined logic
+levels at boot time and may therefore be unsuitable for SCD4x connection.
+
 ## Usage
 
 Copy **scd4x.lua** to your NodeMCU board and set it up as follows.
 
 ```lua
 scd4x = require("scd4x")
-i2c.setup(0, sda_pin, scl_pin, i2c.SLOW)
+i2c.setup(0, 2, 1, i2c.SLOW)
 scd4x.start()
 
 -- can be called with up to 1 Hz
 function some_timer_callback()
 	local co2, raw_temp, raw_humi = scd4x.read()
-	if co2 == nil then
-		print("SCD4x error")
+	if co2 ~= nil then
+		-- co2      : CO₂ concentration [ppm]
+		-- raw_temp : raw_temp/2¹⁶ - 45 == Temperature [°c]
+		-- raw_humi : raw_humi/2¹⁶ == Humidity [%]
 	else
-		-- CO₂[ppm] == co2, Temperature[°c] == raw_temp/2¹⁶ - 45, Humidity[%] == raw_humi/2¹⁶
+		print("SCD4x error")
 	end
 end
 ```
 
-See **init.lua** for an example. To use it, you need to create a **config.lua** file with WiFI and MQTT settings:
+## Application Example
+
+**init.lua** is an example application with HomeAssistant integration.
+To use it, you need to create a **config.lua** file with WiFI and MQTT settings:
 
 ```lua
-station_cfg.ssid = "..."
-station_cfg.pwd = "..."
+station_cfg = {ssid = "...", pwd = "..."}
 mqtt_host = "..."
 ```
+
+Optionally, it can also publish readings to an InfluxDB.
+To do so, configure URL and attribute:
+
+```lua
+influx_url = "..."
+influx_attr = "..."
+```
+
+Readings will be published as `scd4x[influx_attr] co2_ppm=%d,temperature_degc=%d.%d,humidity_relpercent=%d.%d`.
+So, unless `influx_attr = ''`, it must start with a comma, e.g. `influx_attr = ',device=' .. device_id`.
diff --git a/init.lua b/init.lua
index dad4019..ec8d707 100644
--- a/init.lua
+++ b/init.lua
@@ -1,4 +1,3 @@
-station_cfg = {}
 publishing_mqtt = false
 publishing_http = false
 
@@ -11,7 +10,7 @@ mqttclient = mqtt.Client(device_id, 120)
 
 dofile("config.lua")
 
-print("ESP8266 " .. chip_id)
+print("SCD4x " .. chip_id)
 
 ledpin = 4
 gpio.mode(ledpin, gpio.OUTPUT)
-- 
cgit v1.2.3