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_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,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,5 @@
1
+ [console_scripts]
2
+ pratico-cal = pratico3_cal:main
3
+ pratico-field = pratico3_usr:main
4
+ pratico-selftest = pratico3_core:main
5
+ pratico-service = pratico3_service:main