pratico-sensor 3.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pratico3_cal.py +362 -0
- pratico3_core.py +555 -0
- pratico3_service.py +118 -0
- pratico3_usr.py +203 -0
- pratico_sensor-3.0.0.dist-info/METADATA +74 -0
- pratico_sensor-3.0.0.dist-info/RECORD +10 -0
- pratico_sensor-3.0.0.dist-info/WHEEL +5 -0
- pratico_sensor-3.0.0.dist-info/entry_points.txt +5 -0
- pratico_sensor-3.0.0.dist-info/licenses/LICENSE +674 -0
- pratico_sensor-3.0.0.dist-info/top_level.txt +4 -0
pratico3_usr.py
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
PRATICO 3 - field program (no PC needed: two buttons + 16x2 LCD)
|
|
4
|
+
================================================================
|
|
5
|
+
|
|
6
|
+
Starts automatically at power-on (pratico3.service). Buttons:
|
|
7
|
+
OK (GPIO 4) : confirm / measure / start the reaction timer
|
|
8
|
+
MODE (GPIO 21) : short press = switch N-NO3 <-> P-PO4 ; hold 3 s = new blank
|
|
9
|
+
|
|
10
|
+
Cycle
|
|
11
|
+
1. "Blank: DI water" -> distilled water in the cuvette, lid closed, OK.
|
|
12
|
+
2. "N-NO3 OK=measure" (MODE switches analyte).
|
|
13
|
+
reaction_time_s = 0 : sample in, lid closed, OK -> reading.
|
|
14
|
+
reaction_time_s > 0 : add the reagent, OK starts the timer, insert the cuvette and close
|
|
15
|
+
the lid; the reading is taken automatically when the timer ends.
|
|
16
|
+
3. The LCD shows the concentration (mg/L) and the absorbance; the result is appended to
|
|
17
|
+
results/results.csv. OK = back to the menu.
|
|
18
|
+
|
|
19
|
+
Files (under ~/PRATICO_3)
|
|
20
|
+
calibration/pratico3_cal.json written by pratico3_cal.py
|
|
21
|
+
results/results.csv one row per sample
|
|
22
|
+
logs/YYYYMMDD.jsonl every reading with its raw conversions
|
|
23
|
+
|
|
24
|
+
python3 pratico3_usr.py --simulate runs without hardware (scripted buttons)
|
|
25
|
+
"""
|
|
26
|
+
import argparse
|
|
27
|
+
import os
|
|
28
|
+
import signal
|
|
29
|
+
import sys
|
|
30
|
+
import time
|
|
31
|
+
|
|
32
|
+
import pratico3_core as core
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def fmt_conc(c):
|
|
36
|
+
if abs(c) < 1:
|
|
37
|
+
return f"{c:.3f}"
|
|
38
|
+
if abs(c) < 10:
|
|
39
|
+
return f"{c:.2f}"
|
|
40
|
+
return f"{c:.1f}"
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def do_blank(hw, cfg):
|
|
44
|
+
while True:
|
|
45
|
+
hw.show("Blank: DI water", "lid closed, OK")
|
|
46
|
+
if core.wait_key(hw, cfg["long_press_s"]) != "ok":
|
|
47
|
+
continue
|
|
48
|
+
while True:
|
|
49
|
+
hw.show("Blank ...", "keep lid closed")
|
|
50
|
+
try:
|
|
51
|
+
m = core.measure_repeated(hw, cfg, cfg["blank_repeats"])
|
|
52
|
+
break
|
|
53
|
+
except core.MeasureError as e:
|
|
54
|
+
if str(e) == "Saturated" and cfg["autorange_on_blank"]:
|
|
55
|
+
g = core.autorange(hw, cfg)
|
|
56
|
+
hw.show("Auto-range", f"gain {g}x")
|
|
57
|
+
hw.sleep(1.5)
|
|
58
|
+
continue
|
|
59
|
+
hw.show(str(e), "OK = retry")
|
|
60
|
+
core.wait_key(hw, cfg["long_press_s"])
|
|
61
|
+
m = None
|
|
62
|
+
break
|
|
63
|
+
if m is None:
|
|
64
|
+
continue
|
|
65
|
+
fs = m["mean"] / core.FULL_SCALE
|
|
66
|
+
core.log_raw(cfg, "blank", m)
|
|
67
|
+
print(f"blank net {m['net']:.1f} dark {m['dark']:.1f} ({fs:.1%} FS) gain {m['gain']}x "
|
|
68
|
+
f"{m['integration_ms']} ms", flush=True)
|
|
69
|
+
if fs < cfg["target_fs"][0]:
|
|
70
|
+
hw.show("Blank low", f"{fs:.0%} FS OK=go")
|
|
71
|
+
core.wait_key(hw, cfg["long_press_s"])
|
|
72
|
+
else:
|
|
73
|
+
hw.show("Blank OK", f"{fs:.0%} FS")
|
|
74
|
+
hw.sleep(1.5)
|
|
75
|
+
m["t_taken"] = hw.now()
|
|
76
|
+
return m
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def measure_sample(hw, cfg, an):
|
|
80
|
+
"""Returns (measurement, reaction_s) or (None, None) if the user went back."""
|
|
81
|
+
rt = cfg["reaction_time_s"].get(an, 0)
|
|
82
|
+
t_start = None
|
|
83
|
+
if rt > 0:
|
|
84
|
+
hw.show("Add reagent,", "OK=start timer")
|
|
85
|
+
if core.wait_key(hw, cfg["long_press_s"]) != "ok":
|
|
86
|
+
return None, None
|
|
87
|
+
t_start = core.countdown(hw, rt, an)
|
|
88
|
+
while True:
|
|
89
|
+
hw.show("Measuring ...", core.LABEL[an])
|
|
90
|
+
try:
|
|
91
|
+
m = core.measure_cycle(hw, cfg)
|
|
92
|
+
react = None if t_start is None else round(m["t_mono"] - t_start, 1)
|
|
93
|
+
return m, react
|
|
94
|
+
except core.MeasureError as e:
|
|
95
|
+
hw.show(str(e), "OK=retry MODE=bk")
|
|
96
|
+
if core.wait_key(hw, cfg["long_press_s"]) != "ok":
|
|
97
|
+
return None, None
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def main(argv=None):
|
|
101
|
+
ap = argparse.ArgumentParser(description="PRATICO 3 field program")
|
|
102
|
+
ap.add_argument("--simulate", action="store_true")
|
|
103
|
+
args = ap.parse_args(argv)
|
|
104
|
+
cfg = core.load_config()
|
|
105
|
+
kw = {}
|
|
106
|
+
sim_A = []
|
|
107
|
+
if args.simulate:
|
|
108
|
+
base = os.path.join(os.getcwd(), "sim_out")
|
|
109
|
+
cfg.update(res_file=os.path.join(base, "results", "results.csv"), log_dir=os.path.join(base, "logs"),
|
|
110
|
+
cal_file=os.environ.get("PRATICO3_SIM_CAL", os.path.join(base, "calibration",
|
|
111
|
+
"pratico3_cal.json")))
|
|
112
|
+
# blank OK, measure N, back, MODE (->P), measure P, back, hold MODE (new blank), OK
|
|
113
|
+
kw["script"] = [("ok", .1), ("ok", .1), ("ok", .1), ("mode", .1), ("ok", .1), ("ok", .1),
|
|
114
|
+
("mode", 3.5), ("ok", .1)]
|
|
115
|
+
sim_A = [0.2200, 0.3360]
|
|
116
|
+
|
|
117
|
+
def _term(signum, frame):
|
|
118
|
+
raise KeyboardInterrupt
|
|
119
|
+
signal.signal(signal.SIGTERM, _term)
|
|
120
|
+
|
|
121
|
+
hw = None
|
|
122
|
+
for attempt in range(5): # at boot the I2C devices may need a moment
|
|
123
|
+
try:
|
|
124
|
+
hw = core.make_hw(cfg, simulate=args.simulate, **kw)
|
|
125
|
+
break
|
|
126
|
+
except Exception as e:
|
|
127
|
+
print(f"[WARN] hardware init failed ({e}), retrying", flush=True)
|
|
128
|
+
time.sleep(2)
|
|
129
|
+
if hw is None:
|
|
130
|
+
return 1
|
|
131
|
+
try:
|
|
132
|
+
hw.show("PRATICO 3", f"fw {core.VERSION}")
|
|
133
|
+
hw.sleep(1.5)
|
|
134
|
+
try:
|
|
135
|
+
cal = core.load_calibration(cfg["cal_file"])
|
|
136
|
+
except (OSError, ValueError) as e:
|
|
137
|
+
print(f"[WARN] no calibration ({e}) - absorbance only", flush=True)
|
|
138
|
+
cal = {}
|
|
139
|
+
hw.show("Calibration", f"N:{'yes' if 'N' in cal else 'no '} P:{'yes' if 'P' in cal else 'no'}")
|
|
140
|
+
hw.sleep(1.5)
|
|
141
|
+
synced = core.clock_synced() if not args.simulate else False
|
|
142
|
+
blank = do_blank(hw, cfg)
|
|
143
|
+
an = "N"
|
|
144
|
+
while True:
|
|
145
|
+
hw.show(f"{core.LABEL[an]} OK=measure", "MODE=N/P hold=bk")
|
|
146
|
+
k = core.wait_key(hw, cfg["long_press_s"])
|
|
147
|
+
if k == "mode":
|
|
148
|
+
an = "P" if an == "N" else "N"
|
|
149
|
+
continue
|
|
150
|
+
if k == "mode_long":
|
|
151
|
+
blank = do_blank(hw, cfg)
|
|
152
|
+
continue
|
|
153
|
+
if sim_A:
|
|
154
|
+
hw.absorbance = sim_A.pop(0)
|
|
155
|
+
m, react = measure_sample(hw, cfg, an)
|
|
156
|
+
if m is None:
|
|
157
|
+
continue
|
|
158
|
+
A = core.absorbance(m["net"], blank["net"])
|
|
159
|
+
if A is None:
|
|
160
|
+
hw.show("Invalid signal", "OK = back")
|
|
161
|
+
core.wait_key(hw, cfg["long_press_s"])
|
|
162
|
+
continue
|
|
163
|
+
entry = cal.get(an)
|
|
164
|
+
c, flag = core.concentration(A, entry) if entry else (None, "no cal")
|
|
165
|
+
sA = core.sigma_absorbance(m, blank)
|
|
166
|
+
row = dict(datetime=time.strftime("%Y-%m-%d %H:%M:%S"), clock_synced=int(synced),
|
|
167
|
+
uptime_s=round(core.uptime_s()), analyte=core.LABEL[an],
|
|
168
|
+
conc_mgL=None if c is None else round(c, 4), flag=flag, A=round(A, 5),
|
|
169
|
+
sigma_A=round(sA, 6), reaction_s=react, sample_net=round(m["net"], 1),
|
|
170
|
+
blank_net=round(blank["net"], 1), blank_age_s=round(hw.now() - blank["t_taken"]),
|
|
171
|
+
dark=round(m["dark"], 2), gain=m["gain"], integration_ms=m["integration_ms"],
|
|
172
|
+
n_avg=m["n"], spread=round(m["spread"], 5), invalid=m["invalid"],
|
|
173
|
+
cal_date=entry.get("date") if entry else None, fw=core.VERSION)
|
|
174
|
+
seq = core.append_result(cfg["res_file"], row)
|
|
175
|
+
core.log_raw(cfg, "sample", m, {"analyte": an, "A": A, "conc": c, "flag": flag,
|
|
176
|
+
"reaction_s": react, "seq": seq})
|
|
177
|
+
print(f"#{seq} {core.LABEL[an]}: A={A:.4f} C={c if c is None else round(c, 4)} {flag}",
|
|
178
|
+
flush=True)
|
|
179
|
+
l2 = f"A={A:.3f} #{seq}"
|
|
180
|
+
if c is None:
|
|
181
|
+
l1 = f"{core.LABEL[an]} A only"
|
|
182
|
+
elif flag == "<LOD":
|
|
183
|
+
l1 = f"{core.LABEL[an]} <LOD"
|
|
184
|
+
elif flag == ">range":
|
|
185
|
+
l1 = f"{an} {fmt_conc(c)} mg/L!"
|
|
186
|
+
l2 = f"over range #{seq}"
|
|
187
|
+
else:
|
|
188
|
+
l1 = f"{an} {fmt_conc(c)} mg/L"
|
|
189
|
+
hw.show(l1, l2)
|
|
190
|
+
k = core.wait_key(hw, cfg["long_press_s"])
|
|
191
|
+
if k == "mode_long":
|
|
192
|
+
blank = do_blank(hw, cfg)
|
|
193
|
+
except KeyboardInterrupt:
|
|
194
|
+
print("stopped", flush=True)
|
|
195
|
+
except SystemExit as e:
|
|
196
|
+
print(e, flush=True)
|
|
197
|
+
finally:
|
|
198
|
+
hw.close()
|
|
199
|
+
return 0
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
if __name__ == "__main__":
|
|
203
|
+
sys.exit(main())
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pratico-sensor
|
|
3
|
+
Version: 3.0.0
|
|
4
|
+
Summary: PRATICO 3 firmware: low-cost Raspberry Pi colorimeter for nitrate and phosphate (FreshWater Watch kits)
|
|
5
|
+
Author: Riccardo Gaetano Cirrone
|
|
6
|
+
License-Expression: GPL-3.0-only
|
|
7
|
+
Project-URL: Homepage, https://github.com/LowCostSensor/PRATICO-sensor
|
|
8
|
+
Project-URL: Documentation, https://github.com/LowCostSensor/PRATICO-sensor/tree/main/docs
|
|
9
|
+
Project-URL: Changelog, https://github.com/LowCostSensor/PRATICO-sensor/blob/main/CHANGELOG.md
|
|
10
|
+
Project-URL: Paper, https://doi.org/10.1021/acsestwater.5c00314
|
|
11
|
+
Keywords: colorimeter,nitrate,phosphate,raspberry-pi,citizen-science,water-quality
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Chemistry
|
|
17
|
+
Requires-Python: >=3.9
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: adafruit-blinka; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
21
|
+
Requires-Dist: gpiod<3,>=2.2.2; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
22
|
+
Requires-Dist: adafruit-circuitpython-ltr329-ltr303>=3.0.6; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
23
|
+
Requires-Dist: RPLCD>=1.3; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
24
|
+
Requires-Dist: smbus2; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
25
|
+
Requires-Dist: RPi.GPIO; platform_system == "Linux" and platform_machine in "aarch64 armv7l armv6l"
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
# pratico-sensor
|
|
29
|
+
|
|
30
|
+
Firmware for **PRATICO 3**, a low-cost colorimeter for nitrate (N‑NO₃) and phosphate (P‑PO₄) that
|
|
31
|
+
reads FreshWater Watch test kits. It runs on a Raspberry Pi Zero 2 W with an LTR‑329 light sensor, a
|
|
32
|
+
525 nm LED, a 16×2 LCD and two buttons.
|
|
33
|
+
|
|
34
|
+
Hardware, build guide and documentation: **https://github.com/LowCostSensor/PRATICO-sensor**
|
|
35
|
+
|
|
36
|
+
## Install (on the Raspberry Pi)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
sudo apt install -y pipx python3-dev
|
|
40
|
+
pipx install pratico-sensor
|
|
41
|
+
pipx ensurepath # then log out and in again
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Set up the I²C buses first, as in the
|
|
45
|
+
[setup guide](https://github.com/LowCostSensor/PRATICO-sensor/blob/main/docs/2-raspberry-setup.md).
|
|
46
|
+
|
|
47
|
+
## Commands
|
|
48
|
+
|
|
49
|
+
| Command | What it does |
|
|
50
|
+
|---|---|
|
|
51
|
+
| `pratico-selftest` | hardware self test: dark level, LED level, noise |
|
|
52
|
+
| `pratico-cal` | calibration with standard solutions, over SSH ([guide](https://github.com/LowCostSensor/PRATICO-sensor/blob/main/docs/3-calibration.md)) |
|
|
53
|
+
| `pratico-field` | field program: buttons + LCD ([guide](https://github.com/LowCostSensor/PRATICO-sensor/blob/main/docs/4-field-use.md)) |
|
|
54
|
+
| `pratico-service install` | start the field program at every power-on (systemd user service) |
|
|
55
|
+
|
|
56
|
+
`pratico-selftest`, `pratico-cal` and `pratico-field` accept `--simulate` to run without hardware, for
|
|
57
|
+
example on a PC. Calibration,
|
|
58
|
+
results and logs are kept in `~/PRATICO_3/`. Settings can be overridden in
|
|
59
|
+
`~/PRATICO_3/pratico3_config.json`.
|
|
60
|
+
|
|
61
|
+
## Upgrade
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
pipx upgrade pratico-sensor
|
|
65
|
+
pratico-service install # restart the field program on the new version
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Citation
|
|
69
|
+
|
|
70
|
+
Cirrone R. G. et al. Low-Cost Optical Sensing for Nitrate and Phosphate: Advancing Community
|
|
71
|
+
Freshwater Monitoring. *ACS ES&T Water* **2025**, 5, 6258–6267.
|
|
72
|
+
[doi:10.1021/acsestwater.5c00314](https://doi.org/10.1021/acsestwater.5c00314)
|
|
73
|
+
|
|
74
|
+
License: GPL-3.0.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
pratico3_cal.py,sha256=Awd8ConjOUHRLiunVukVj5Z3anEfIq5KhbNiAV624-0,17168
|
|
2
|
+
pratico3_core.py,sha256=sGIlJzL2g6FkmcQPT1fQjNdy5HDubYkAg2CIqoLny3o,20881
|
|
3
|
+
pratico3_service.py,sha256=THQK99R_y7xqoU5d13glBZToWZxjg_1Tn2D9mzKmF08,4291
|
|
4
|
+
pratico3_usr.py,sha256=1r_mksL4oPwd2vVkBZWp3esQGU-pVa7bNDccXjI9Jjw,8218
|
|
5
|
+
pratico_sensor-3.0.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
|
|
6
|
+
pratico_sensor-3.0.0.dist-info/METADATA,sha256=1DRUzaH5DG948jeJM14KGjXdhC6Jct-wkZrx8hVav9Q,3475
|
|
7
|
+
pratico_sensor-3.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
8
|
+
pratico_sensor-3.0.0.dist-info/entry_points.txt,sha256=OXao9zpm-WE_xcPqdgLtudfWFExFE_5u7LItCHqh9SI,162
|
|
9
|
+
pratico_sensor-3.0.0.dist-info/top_level.txt,sha256=eFyAVA7yWjHMRrDvOr8VvHeFBiHZrVxl1xaOG70L72k,57
|
|
10
|
+
pratico_sensor-3.0.0.dist-info/RECORD,,
|