initial commit

4 files changed, 228 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..d37441f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# ESP8266 Lua/NodeMCU module for SDS011 particle monitor
+
+This repository contains a Lua module (`sds011.lua`) as well as ESP8266/NodeMCU
+MQTT gateway application example (`init.lua`) for the **SDS011** particulate
+matter (PM2.5 and PM10) sensor.
+
+## Dependencies
+
+sds011.lua has been tested with Lua 5.1 on NodeMCU firmware 3.0.1
+(Release 202112300746, integer build). It requires the following modules.
+
+* struct
+
+Most practical applications (such as the example in init.lua) also need the
+following modules.
+
+* gpio
+* mqtt
+* node
+* softuart
+* tmr
+* uart
+* wifi
+
+## Setup
+
+Connect the SDS011 sensor to your ESP8266/NodeMCU board as follows.
+
+* SDS011 GND → ESP8266/NodeMCU GND
+* SDS011 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. I have not tested whether that is an issue)
+* SDS011 TXD → NodeMCU D1 (ESP8266 GPIO5)
+* SDS011 RXD → NodeMCU D2 (ESP8266 GPIO4)
+
+If you use use different pins for TXD and RXD, 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 SDS011 connection.
+
+## Usage
+
+Copy **sds011.lua** to your NodeMCU board and set it up as follows.
+
+```lua
+sds011 = require("sds011")
+port = softuart.setup(9600, 2, 1)
+port:on("data", 10, uart_callback)
+
+function uart_callback(data
+	local pm25i, pm25d, pm10i, pm10d = sds011.parse_frame(data)
+	if pm25i ~= nil then
+		-- pm25i/pm10i contain the integer part (i.e., PM2.5 / PM10 value in µg/m³)
+		-- pm25d/pm10d contain the decimal/fractional part (i.e., PM2.5 / PM10 fraction in .1 µg/m³, range 0 .. 9)
+	else
+		-- invalid checksum or non-data frame (i.e., acknowledgment of a write command)
+	end
+end
+```
+
+See **init.lua** for an example. 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 = "..."
+```
+
+## SDS011 Configuration API
+
+If desired, **sds011.lua** can be used to configure the SDS011 sensor.
+Currently, the following commands are supported
+
+* `sds011.set_report_mode(active)`
+  * active == true: periodically report PM2.5 and PM10 values via UART
+  * active == false: only report PM2.5 and PM10 values when queried
+* `sds011.sleep(sleep)`
+  * sleep == true: put sensor into sleep mode. The fan is turned off, no further measurements are performed
+  * sleep == false: wake up sensor.
+* `sds011.set_work_period(period)`
+  * period == 0: continuous operation (about one measurement per second)
+  * 0 < *period* ≤ 30: about one measurement every *period* minutes; fan turned off in-between
diff --git a/init.lua b/init.lua
new file mode 100644
index 0000000..e9abef9
--- /dev/null
+++ b/init.lua
@@ -0,0 +1,73 @@
+station_cfg = {}
+dofile("config.lua")
+
+delayed_restart = tmr.create()
+chipid = node.chipid()
+mqtt_prefix = "sensor/esp8266_" .. chipid
+mqttclient = mqtt.Client("esp8266_" .. chipid, 120)
+
+print("ESP8266 " .. chipid)
+
+ledpin = 4
+gpio.mode(ledpin, gpio.OUTPUT)
+gpio.write(ledpin, 0)
+
+sds011 = require("sds011")
+
+function log_restart()
+	print("Network error " .. wifi.sta.status() .. ". Restarting in 20 seconds.")
+	delayed_restart:start()
+end
+
+function setup_client()
+	gpio.write(ledpin, 1)
+	publishing = true
+	mqttclient:publish(mqtt_prefix .. "/state", "online", 0, 1, function(client)
+		publishing = false
+	end)
+	port = softuart.setup(9600, 2, 1)
+	port:on("data", 10, uart_callback)
+end
+
+function connect_mqtt()
+	print("IP address: " .. wifi.sta.getip())
+	print("Connecting to MQTT " .. mqtt_host)
+	delayed_restart:stop()
+	mqttclient:on("connect", setup_client)
+	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 uart_callback(data)
+	local pm25i, pm25f, pm10i, pm10f = sds011.parse_frame(data)
+	if pm25i == nil then
+		print("Invalid or data-less SDS011 frame")
+		return
+	end
+	local json_str = string.format('{"pm25_ugm3": %d.%d, "pm10_ugm3": %d.%d, "rssi_dbm": %d}', pm25i, pm25f, pm10i, pm10f, wifi.sta.getrssi())
+	if not publishing then
+		publishing = true
+		gpio.write(ledpin, 0)
+		mqttclient:publish(mqtt_prefix .. "/data", json_str, 0, 0, function(client)
+			publishing = false
+			gpio.write(ledpin, 1)
+			collectgarbage()
+		end)
+	end
+end
+
+delayed_restart:register(20 * 1000, tmr.ALARM_SINGLE, node.restart)
+
+connect_wifi()
diff --git a/sds011.lua b/sds011.lua
new file mode 100644
index 0000000..a528720
--- /dev/null
+++ b/sds011.lua
@@ -0,0 +1,74 @@
+local sds011 = {}
+
+local c_head = 0xaa
+local c_tail = 0xab
+local c_id = 0xb4
+
+local c_read = 0x00
+local c_write = 0x01
+
+local c_report_mode = 0x02
+local c_active = 0x00
+local c_passive = 0x01
+
+local c_query = 0x04
+
+local c_sleepcmd = 0x06
+local c_sleep = 0x00
+local c_work = 0x01
+local c_workperiod = 0x08
+
+function sds011.finish_cmd(cmd)
+	cmd = cmd .. string.char(0xff, 0xff)
+	local checksum = 0
+	for i = 3, string.len(cmd) do
+		checksum = (checksum + string.byte(cmd, i)) % 256
+	end
+	cmd = cmd .. string.char(checksum, c_tail)
+	return cmd
+end
+
+function sds011.set_report_mode(active)
+	local cmd = string.char(c_head, c_id, c_report_mode, c_write)
+	if active then
+		cmd = cmd .. string.char(c_active)
+	else
+		cmd = cmd .. string.char(c_passive)
+	end
+	cmd = cmd .. string.char(0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+	return sds011.finish_cmd(cmd)
+end
+
+function sds011.sleep(sleep)
+	local cmd = string.char(c_head, c_id, c_sleepcmd, c_write)
+	if sleep then
+		cmd = cmd .. string.char(c_sleep)
+	else
+		cmd = cmd .. string.char(c_work)
+	end
+	cmd = cmd .. string.char(0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+	return sds011.finish_cmd(cmd)
+end
+
+function sds011.set_work_period(period)
+	-- period == 0 : continuous operation, about one measurement per second
+	-- period > 0  : about one measurement every <period> minutes, fan is turned off in-between
+	if period < 0 or period > 30 then
+		return
+	end
+	local cmd = string.char(c_head, c_id, c_workperiod, c_write, period)
+	cmd = cmd .. string.char(0, 0, 0, 0, 0, 0, 0, 0, 0, 0)
+	return sds011.finish_cmd(cmd)
+end
+
+function sds011.parse_frame(data)
+	local header, command, pm25l, pm25h, pm10l, pm10h, id1, id2, sum, tail = struct.unpack("BBBBBBBBBB", data)
+	if header ~= c_head or command ~= 0xc0 or (pm25l + pm25h + pm10l + pm10h + id1 + id2) % 256 ~= sum or tail ~= c_tail then
+		return nil
+	end
+	pm25 = pm25h * 256 + pm25l
+	pm10 = pm10h * 256 + pm10l
+	return pm25 / 10, pm25 % 10, pm10 / 10, pm10 % 10
+end
+
+return sds011