From 3b1acea692bc41933e759e639378a85696bf15ec Mon Sep 17 00:00:00 2001
From: Ben Thorner <benthorner@users.noreply.github.com>
Date: Sat, 19 Nov 2022 22:14:53 +0000
Subject: [PATCH] Add library docs about low-level reader usage

---
 docs/examples/read_one_sample.out |  6 ++++++
 docs/examples/read_one_sample.py  | 17 +++++++++++++++++
 docs/library_usage.md             | 10 ++++++++++
 3 files changed, 33 insertions(+)
 create mode 100644 docs/examples/read_one_sample.out
 create mode 100644 docs/examples/read_one_sample.py

diff --git a/docs/examples/read_one_sample.out b/docs/examples/read_one_sample.out
new file mode 100644
index 0000000..032406c
--- /dev/null
+++ b/docs/examples/read_one_sample.out
@@ -0,0 +1,6 @@
+
+PMSx003 4 samples on default format
+2021-07-29 15:57:01: PM1 1.0, PM2.5 11.0, PM10 12.0 μg/m3
+2021-07-29 15:57:21: PM1 0.0, PM2.5 6.0, PM10 6.0 μg/m3
+2021-07-29 15:57:41: PM1 0.0, PM2.5 1.0, PM10 2.0 μg/m3
+2021-07-29 15:58:01: PM1 0.0, PM2.5 1.0, PM10 2.0 μg/m3
diff --git a/docs/examples/read_one_sample.py b/docs/examples/read_one_sample.py
new file mode 100644
index 0000000..4930057
--- /dev/null
+++ b/docs/examples/read_one_sample.py
@@ -0,0 +1,17 @@
+"""
+Read PMSx003 sensor on /dev/ttyUSB0.
+
+Use low-level reader methods for more granular
+control of the sensor.
+"""
+
+from pms.core import SensorReader
+
+reader = SensorReader(sensor="PMSx003", port="/dev/ttyUSB0")
+
+print("\nPMSx003 4 samples on default format")
+
+reader.open()
+for _ in range(4):
+    print(reader.read_one())
+reader.close()
diff --git a/docs/library_usage.md b/docs/library_usage.md
index 7efc3a1..be206c6 100644
--- a/docs/library_usage.md
+++ b/docs/library_usage.md
@@ -27,6 +27,16 @@ This section contain some help for those brave enough to use its internals as a
     --8<-- "read_two_sensors.out"
     ```
 
+=== "read one sensor (low-level API)"
+
+    ``` python
+    --8<-- "read_one_sample.py"
+    ```
+
+    ```
+    --8<-- "read_one_sample.out"
+    ```
+
 
 ## Observation data fields