initial commit

4 files changed, 383 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..338c30b
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+config.lua
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8b38677
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+# ESP8266 Lua/NodeMCU module for Sensirion SEN5x PM sensors
+
+This repository contains a Lua module (`sen5x.lua`) as well as
+MQTT-based HomeAssistant integration (`init.lua`) for **Sensirion SEN5x**
+particulate matter, VOC, and NOx sensors.
+
+## Dependencies
+
+sen5x.lua has been tested with Lua 5.1 on NodeMCU firmware 3.0.1 (Release
+202112300746, integer build). It requires the following modules.
+
+* i2c
+
+The MQTT HomeAssistant integration in init.lua additionally needs the following
+modules.
+
+* gpio
+* mqtt
+* node
+* tmr
+* uart
+* wifi
+
+## Setup
+
+Connect the SEN5x board to your ESP8266/NodeMCU board as follows.
+
+* SEN5x GND → ESP8266/NodeMCU GND
+* SEN5x 5V → 5V input (note that the "5V" pin of NodeMCU or D1 mini dev boards is connected to its USB input via a protective diode, so when powering the board via USB the "5V" output is more like 4.7V. For SEN5x, this is sufficient.)
+* SEN5x SCL → NodeMCU D1 (ESP8266 GPIO4)
+* SEN5x 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
+softuart.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 SEN5x connection.
+
+## Usage
+
+Copy **sen5x.lua** to your NodeMCU board and set it up as follows.
+
+```lua
+sen5x = require("sen5x")
+i2c.setup(0, sda_pin, scl_pin, i2c.SLOW)
+sen5x.start()
+
+-- can be called with up to 1 Hz
+function some_timer_callback()
+	if sen5x.prepare_read() then
+		local delayed_read_data = tmr.create()
+		delayed_read_data:register(20, tmr.ALARM_SINGLE, read_data)
+		delayed_read_data:start()
+	end
+end
+
+function read_data()
+	if sen5x.read() then
+		print(string.format("PM1: %d.%01d µg/m³", sen5x.pm1/10, sen5x.pm1%10))
+	end
+end
+```
+
+## 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 = "..."
+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 stored as `sen5x,[influx_attr] pm1_ugm3=...,pm2_5_ugm3=...,...`
diff --git a/init.lua b/init.lua
new file mode 100644
index 0000000..3f5813c
--- /dev/null
+++ b/init.lua
@@ -0,0 +1,212 @@
+station_cfg = {}
+publishing_mqtt = false
+publishing_http = false
+
+watchdog = tmr.create()
+push_timer = tmr.create()
+chip_id = string.format("%06X", node.chipid())
+device_id = "esp8266_" .. chip_id
+mqtt_prefix = "sensor/" .. device_id
+mqttclient = mqtt.Client(device_id, 120)
+
+dofile("config.lua")
+
+print("ESP8266 " .. chip_id)
+
+ledpin = 4
+gpio.mode(ledpin, gpio.OUTPUT)
+gpio.write(ledpin, 0)
+
+sen5x = require("sen5x")
+i2c.setup(sen5x.bus_id, 2, 1, i2c.SLOW)
+
+function log_restart()
+	print("Network error " .. wifi.sta.status())
+end
+
+function setup_client()
+	print("Connected")
+	gpio.write(ledpin, 1)
+	if not sen5x.start() then
+		print("SEN5x initialization error")
+	end
+	publishing_mqtt = true
+	mqttclient:publish(mqtt_prefix .. "/state", "online", 0, 1, function(client)
+		publishing_mqtt = false
+		push_timer:start()
+		prepare_push_data()
+	end)
+end
+
+function connect_mqtt()
+	print("IP address: " .. wifi.sta.getip())
+	print("Connecting to MQTT " .. mqtt_host)
+	mqttclient:on("connect", prepare_hass_register)
+	mqttclient:on("offline", log_restart)
+	mqttclient:lwt(mqtt_prefix .. "/state", "offline", 0, 1)
+	mqttclient:connect(mqtt_host)
+end
+
+function connect_wifi()
+	print("WiFi MAC: " .. wifi.sta.getmac())
+	print("Connecting to ESSID " .. station_cfg.ssid)
+	wifi.eventmon.register(wifi.eventmon.STA_GOT_IP, connect_mqtt)
+	wifi.eventmon.register(wifi.eventmon.STA_DHCP_TIMEOUT, log_restart)
+	wifi.eventmon.register(wifi.eventmon.STA_DISCONNECTED, log_restart)
+	wifi.setmode(wifi.STATION)
+	wifi.sta.config(station_cfg)
+	wifi.sta.connect()
+end
+
+function prepare_push_data()
+	if sen5x.prepare_read() == false then
+		print("SEN5x error")
+	else
+		local delayed_read_data = tmr.create()
+		delayed_read_data:register(20, tmr.ALARM_SINGLE, push_data)
+		delayed_read_data:start()
+	end
+end
+
+function push_data()
+	if sen5x.read() == false then
+		print("SEN5x error")
+	else
+		local json_str = "{"
+		local influx_str = ""
+		if sen5x.pm1 ~= nil then
+			json_str = string.format('%s"pm1_ugm3":%d.%01d,', json_str, sen5x.pm1/10, sen5x.pm1%10)
+			influx_str = string.format("%spm1_ugm3=%d.%01d,", influx_str, sen5x.pm1/10, sen5x.pm1%10)
+		end
+		if sen5x.pm2_5 ~= nil then
+			json_str = string.format('%s"pm2_5_ugm3":%d.%01d,', json_str, sen5x.pm2_5/10, sen5x.pm2_5%10)
+			influx_str = string.format("%spm2_5_ugm3=%d.%01d,", influx_str, sen5x.pm2_5/10, sen5x.pm2_5%10)
+		end
+		if sen5x.pm4 ~= nil then
+			json_str = string.format('%s"pm4_ugm3":%d.%01d,', json_str, sen5x.pm4/10, sen5x.pm4%10)
+			influx_str = string.format("%spm4_ugm3=%d.%01d,", influx_str, sen5x.pm4/10, sen5x.pm4%10)
+		end
+		if sen5x.pm10 ~= nil then
+			json_str = string.format('%s"pm10_ugm3":%d.%01d,', json_str, sen5x.pm10/10, sen5x.pm10%10)
+			influx_str = string.format("%spm10_ugm3=%d.%01d,", influx_str, sen5x.pm10/10, sen5x.pm10%10)
+		end
+		if sen5x.humidity ~= nil then
+			json_str = string.format('%s"humidity_relpercent":%d.%01d,', json_str, sen5x.humidity/100, (sen5x.humidity%100)/10)
+			influx_str = string.format("%shumidity_relpercent=%d.%01d,", influx_str, sen5x.humidity/100, (sen5x.humidity%100)/10)
+		end
+		if sen5x.temperature ~= nil then
+			json_str = string.format('%s"temperature_celsius":%d.%01d,', json_str, sen5x.temperature/200, (sen5x.temperature%200)/20)
+			influx_str = string.format("%stemperature_celsius=%d.%01d,", influx_str, sen5x.temperature/200, (sen5x.temperature%200)/20)
+		end
+		if sen5x.voc ~= nil then
+			json_str = string.format('%s"voc":%d.%01d,', json_str, sen5x.voc/10, sen5x.voc%10)
+			influx_str = string.format("%svoc=%d.%01d,", influx_str, sen5x.voc/10, sen5x.voc%10)
+		end
+		if sen5x.nox ~= nil then
+			json_str = string.format('%s"nox":%d.%01d,', json_str, sen5x.nox/10, sen5x.nox%10)
+			influx_str = string.format("%snox=%d.%01d,", influx_str, sen5x.nox/10, sen5x.nox%10)
+		end
+		json_str = string.format('%s"rssi_dbm":%d}', json_str, wifi.sta.getrssi())
+		influx_str = string.format("%srssi_dbm=%d", influx_str, wifi.sta.getrssi())
+
+		if not publishing_mqtt then
+			watchdog:start(true)
+			publishing_mqtt = true
+			gpio.write(ledpin, 0)
+			mqttclient:publish(mqtt_prefix .. "/data", json_str, 0, 0, function(client)
+				publishing_mqtt = false
+				if influx_url and influx_attr and influx_str then
+					publish_influx(influx_str)
+				else
+					gpio.write(ledpin, 1)
+					collectgarbage()
+				end
+			end)
+		end
+	end
+end
+
+function publish_influx(payload)
+	if not publishing_http then
+		publishing_http = true
+		http.post(influx_url, influx_header, "sen5x" .. influx_attr .. " " .. payload, function(code, data)
+			publishing_http = false
+			gpio.write(ledpin, 1)
+			collectgarbage()
+		end)
+	end
+end
+
+function prepare_hass_register()
+	sen5x.prepare_get_product()
+	local delayed_hass_register = tmr.create()
+	delayed_hass_register:register(20, tmr.ALARM_SINGLE, hass_register)
+	delayed_hass_register:start()
+end
+
+function hass_register()
+	local product_name = sen5x.get_product()
+	if product_name then
+		print("Registering " .. product_name)
+	else
+		product_name = "SEN5x"
+	end
+
+	local hass_device = string.format('{"connections":[["mac","%s"]],"identifiers":["%s"],"model":"ESP8266 + %s","name":"%s %s","manufacturer":"derf"}', wifi.sta.getmac(), device_id, product_name, product_name, chip_id)
+	local hass_entity_base = string.format('"device":%s,"state_topic":"%s/data","expire_after":120', hass_device, mqtt_prefix)
+	local publish_queue = {}
+
+	local hass_pm1 = string.format('{%s,"name":"PM1.0","object_id":"%s_pm1","unique_id":"%s_pm1","device_class":"pm1","unit_of_measurement":"µg/m³","value_template":"{{value_json.pm1_ugm3}}"}', hass_entity_base, device_id, device_id)
+	table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/pm1/config", hass_pm1})
+
+	local hass_pm2_5 = string.format('{%s,"name":"PM2.5","object_id":"%s_pm2_5","unique_id":"%s_pm2_5","device_class":"pm25","unit_of_measurement":"µg/m³","value_template":"{{value_json.pm2_5_ugm3}}"}', hass_entity_base, device_id, device_id)
+	table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/pm2_5/config", hass_pm2_5})
+
+	local hass_pm4 = string.format('{%s,"name":"PM4.0","object_id":"%s_pm4","unique_id":"%s_pm4","device_class":"pm25","unit_of_measurement":"µg/m³","value_template":"{{value_json.pm4_ugm3}}"}', hass_entity_base, device_id, device_id)
+	table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/pm4/config", hass_pm4})
+
+	local hass_pm10 = string.format('{%s,"name":"PM10","object_id":"%s_pm1*","unique_id":"%s_pm10","device_class":"pm10","unit_of_measurement":"µg/m³","value_template":"{{value_json.pm10_ugm3}}"}', hass_entity_base, device_id, device_id)
+	table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/pm10/config", hass_pm10})
+
+	if product_name ~= "SEN50" then
+		local hass_temp = string.format('{%s,"name":"Temperature","object_id":"%s_temperature","unique_id":"%s_temperature","device_class":"temperature","unit_of_measurement":"°c","value_template":"{{value_json.temperature_celsius}}"}', hass_entity_base, device_id, device_id)
+		table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/temperature/config", hass_temp})
+
+		local hass_humi = string.format('{%s,"name":"Humidity","object_id":"%s_humidity","unique_id":"%s_humidity","device_class":"humidity","unit_of_measurement":"%%","value_template":"{{value_json.humidity_relpercent}}"}', hass_entity_base, device_id, device_id)
+		table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/humidity/config", hass_humi})
+
+		local hass_voc = string.format('{%s,"name":"VOC","object_id":"%s_voc","unique_id":"%s_voc","device_class":"aqi","value_template":"{{value_json.voc}}"}', hass_entity_base, device_id, device_id)
+		table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/voc/config", hass_voc})
+	end
+
+	if product_name == "SEN55" then
+		local hass_nox = string.format('{%s,"name":"NOx","object_id":"%s_nox","unique_id":"%s_nox","device_class":"nitrous_oxide","value_template":"{{value_json.nox}}"}', hass_entity_base, device_id, device_id)
+		table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/nox/config", hass_nox})
+	end
+
+	local hass_rssi = string.format('{%s,"name":"RSSI","object_id":"%s_rssi","unique_id":"%s_rssi","device_class":"signal_strength","unit_of_measurement":"dBm","value_template":"{{value_json.rssi_dbm}}","entity_category":"diagnostic"}', hass_entity_base, device_id, device_id)
+	table.insert(publish_queue, {"homeassistant/sensor/" .. device_id .. "/rssi/config", hass_rssi})
+
+	hass_mqtt(publish_queue)
+end
+
+function hass_mqtt(queue)
+	local table_n = table.getn(queue)
+	if table_n > 0 then
+		local topic = queue[table_n][1]
+		local message = queue[table_n][2]
+		table.remove(queue)
+		mqttclient:publish(topic, message, 0, 1, function(client)
+			hass_mqtt(queue)
+		end)
+	else
+		collectgarbage()
+		setup_client()
+	end
+end
+
+watchdog:register(90 * 1000, tmr.ALARM_SEMI, node.restart)
+push_timer:register(20 * 1000, tmr.ALARM_AUTO, prepare_push_data)
+watchdog:start()
+
+connect_wifi()
diff --git a/sen5x.lua b/sen5x.lua
new file mode 100644
index 0000000..afc9970
--- /dev/null
+++ b/sen5x.lua
@@ -0,0 +1,86 @@
+local sen5x = {}
+local device_address = 0x69
+
+sen5x.bus_id = 0
+
+function sen5x.start()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.TRANSMITTER) then
+		return false
+	end
+	i2c.write(sen5x.bus_id, {0x00, 0x21})
+	i2c.stop(sen5x.bus_id)
+	return true
+end
+
+function sen5x.stop()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.TRANSMITTER) then
+		return false
+	end
+	i2c.write(sen5x.bus_id, {0x01, 0x04})
+	i2c.stop(sen5x.bus_id)
+	return true
+end
+
+function sen5x.read_value(data, index)
+	local val = string.byte(data, index) * 256 + string.byte(data, index+1)
+	if val == 0xffff or val == 0x7fff then
+		val = nil
+	end
+	return val
+end
+
+function sen5x.prepare_read()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.TRANSMITTER) then
+		return false
+	end
+	i2c.write(sen5x.bus_id, {0x03, 0xc4})
+	i2c.stop(sen5x.bus_id)
+	return true
+end
+
+function sen5x.read()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.RECEIVER) then
+		return false
+	end
+	local data = i2c.read(sen5x.bus_id, 24)
+	i2c.stop(sen5x.bus_id)
+	sen5x.pm1 = sen5x.read_value(data, 1)
+	sen5x.pm2_5 = sen5x.read_value(data, 4)
+	sen5x.pm4 = sen5x.read_value(data, 7)
+	sen5x.pm10 = sen5x.read_value(data, 10)
+	sen5x.humidity = sen5x.read_value(data, 13)
+	sen5x.temperature = sen5x.read_value(data, 16)
+	sen5x.voc = sen5x.read_value(data, 19)
+	sen5x.nox = sen5x.read_value(data, 22)
+	return true
+end
+
+function sen5x.prepare_get_product()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.TRANSMITTER) then
+		return false
+	end
+	i2c.write(sen5x.bus_id, {0xd0, 0x14})
+	i2c.stop(sen5x.bus_id)
+	return true
+end
+
+function sen5x.get_product()
+	i2c.start(sen5x.bus_id)
+	if not i2c.address(sen5x.bus_id, device_address, i2c.RECEIVER) then
+		return nil
+	end
+	local data = i2c.read(sen5x.bus_id, 48)
+	i2c.stop(sen5x.bus_id)
+	local ret = ""
+	ret = ret .. string.sub(data, 1, 2)
+	ret = ret .. string.sub(data, 4, 5)
+	ret = ret .. string.sub(data, 7, 7)
+	return ret
+end
+
+return sen5x