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_core.py ADDED
@@ -0,0 +1,555 @@
1
+ """
2
+ PRATICO 3 - shared core: hardware layer, measurement cycle, calibration and result files
3
+ =======================================================================================
4
+
5
+ Used by pratico3_usr.py (field program, buttons + LCD) and pratico3_cal.py (calibration over
6
+ SSH / keyboard). Every acquisition parameter lives in pratico3_config.json.
7
+
8
+ Measurement cycle (chosen from the protocol-screening run of 2026-11-17):
9
+ LED off -> discard 1 conversion -> n_dark dark conversions
10
+ LED on -> discard `discard_after_on` conversions -> n_avg conversions averaged -> LED off
11
+ net = mean(LED) - mean(dark); A = -log10(net_sample / net_blank) (raw CH0 counts)
12
+
13
+ Default setting gain 96x / 200 ms / 200 ms rate: blank ~35 % of full scale, noise of the
14
+ averaged reading < 0.02 mAU, ~5 s per reading.
15
+
16
+ Fixes vs PRATICO 2 v2.0.0:
17
+ * fresh-data flag is `new_als_data_available` (v2 tested `new_als_data`, which does not exist,
18
+ and fell back to sleep(1));
19
+ * the ValueError raised by `light_channels` on the data-invalid bit is caught: an isolated
20
+ invalid conversion is discarded and replaced, repeated ones mean saturation;
21
+ * dark subtraction in every cycle, light-leak and saturation checks;
22
+ * absorbance from raw CH0 counts (no lux formula and its x100 scale error).
23
+
24
+ `--simulate` (SimHardware) runs everything on a PC without hardware.
25
+ """
26
+ import json
27
+ import math
28
+ import os
29
+ import random
30
+ import shutil
31
+ import statistics
32
+ import subprocess
33
+ import sys
34
+ import time
35
+
36
+ VERSION = "3.0.0"
37
+
38
+ HOME = os.path.expanduser("~")
39
+ BASE = os.environ.get("PRATICO3_HOME", os.path.join(HOME, "PRATICO_3"))
40
+
41
+ DEFAULT_CONFIG = {
42
+ "gain": 96, # 1, 2, 4, 8, 48, 96
43
+ "integration_ms": 200, # 50, 100, 150, 200, 250, 300, 350, 400
44
+ "rate_ms": 200, # >= integration: 50, 100, 200, 500, 1000, 2000
45
+ "n_dark": 5, # dark conversions per cycle (LED off)
46
+ "discard_after_on": 2, # conversions dropped after LED switch-on
47
+ "n_avg": 13, # LED-on conversions averaged (13 x 200 ms ~ 2.6 s)
48
+ "blank_repeats": 2, # blank = mean of this many cycles
49
+ "max_rel_spread": 0.02, # QC: (max-min)/mean of the averaged conversions
50
+ "max_invalid": 2, # data-invalid conversions tolerated (replaced) per cycle
51
+ "sat_counts": 60000, # CH0 at or above this = saturated
52
+ "min_signal_counts": 30, # net below this = LED off / A too high
53
+ "dark_max_counts": 20, # dark above this = lid open / light leak
54
+ "target_fs": [0.20, 0.75], # blank window (fraction of 65535) for auto-range
55
+ "autorange_on_blank": True, # step the gain down if the blank saturates
56
+ "reaction_time_s": {"N": 0, "P": 0}, # >0: countdown from reagent addition to reading
57
+ "cal_levels": {"N": [0.2, 0.5, 1, 2, 5, 10], "P": [0.02, 0.05, 0.1, 0.2, 0.5, 1]}, # mg/L
58
+ "accept_recovery_pct": 15, # calibration QC band for back-calculated standards
59
+ "led_gpio": 26,
60
+ "button_ok_gpio": 4,
61
+ "button_mode_gpio": 21,
62
+ "long_press_s": 3.0,
63
+ "lcd_bus": 3,
64
+ "lcd_addr": 39, # 0x27
65
+ "cal_file": os.path.join(BASE, "calibration", "pratico3_cal.json"),
66
+ "res_file": os.path.join(BASE, "results", "results.csv"),
67
+ "log_dir": os.path.join(BASE, "logs"),
68
+ }
69
+
70
+ LABEL = {"N": "N-NO3", "P": "P-PO4"}
71
+ GAINS = [1, 2, 4, 8, 48, 96]
72
+ RATES = [50, 100, 200, 500, 1000, 2000]
73
+ FULL_SCALE = 65535
74
+
75
+
76
+ def rate_for(integration_ms):
77
+ return min(r for r in RATES if r >= integration_ms)
78
+
79
+
80
+ # ============================================================================ config
81
+ def config_path():
82
+ here = os.path.dirname(os.path.abspath(__file__))
83
+ for p in (os.environ.get("PRATICO3_CONFIG", ""), os.path.join(BASE, "pratico3_config.json"),
84
+ os.path.join(here, "pratico3_config.json")):
85
+ if p and os.path.exists(p):
86
+ return p
87
+ return os.path.join(here, "pratico3_config.json")
88
+
89
+
90
+ def load_config(path=None):
91
+ cfg = json.loads(json.dumps(DEFAULT_CONFIG))
92
+ path = path or config_path()
93
+ if os.path.exists(path):
94
+ with open(path) as f:
95
+ user = json.load(f)
96
+ for k, v in user.items():
97
+ if k.startswith("_"):
98
+ continue
99
+ if isinstance(v, dict) and isinstance(cfg.get(k), dict):
100
+ cfg[k].update(v)
101
+ else:
102
+ cfg[k] = v
103
+ for k in ("cal_file", "res_file", "log_dir"):
104
+ cfg[k] = os.path.expanduser(cfg[k])
105
+ cfg["rate_ms"] = max(cfg["rate_ms"], rate_for(cfg["integration_ms"]))
106
+ return cfg
107
+
108
+
109
+ # ============================================================================ hardware
110
+ class Hardware:
111
+ """LTR-329 on I2C-1, LED on a GPIO (active high), OK/MODE buttons to GND, LCD on I2C-3."""
112
+
113
+ def __init__(self, cfg):
114
+ import board
115
+ import adafruit_ltr329_ltr303 as ltr
116
+ import RPi.GPIO as GPIO
117
+ self.GPIO = GPIO
118
+ self.cfg = cfg
119
+ GPIO.setmode(GPIO.BCM)
120
+ GPIO.setwarnings(False)
121
+ GPIO.setup(cfg["led_gpio"], GPIO.OUT, initial=GPIO.LOW)
122
+ for pin in (cfg["button_ok_gpio"], cfg["button_mode_gpio"]):
123
+ GPIO.setup(pin, GPIO.IN, pull_up_down=GPIO.PUD_UP)
124
+ self.ltr = ltr.LTR329(board.I2C())
125
+ self.lcd = None
126
+ try:
127
+ from RPLCD.i2c import CharLCD
128
+ self.lcd = CharLCD("PCF8574", cfg["lcd_addr"], port=cfg["lcd_bus"], cols=16, rows=2,
129
+ dotsize=8)
130
+ self.lcd.clear()
131
+ except Exception as e: # LCD is optional (calibration over SSH works without it)
132
+ print(f"[WARN] LCD not available: {e}")
133
+ self.apply_settings(cfg["gain"], cfg["integration_ms"], cfg["rate_ms"])
134
+
135
+ def apply_settings(self, gain, integration_ms, rate_ms):
136
+ self.ltr.als_gain = gain
137
+ self.ltr.integration_time = integration_ms
138
+ self.ltr.measurement_rate = max(rate_ms, rate_for(integration_ms))
139
+ self.gain, self.integration_ms = gain, integration_ms
140
+ self.rate_ms = max(rate_ms, rate_for(integration_ms))
141
+ time.sleep(2 * self.rate_ms / 1000)
142
+ try:
143
+ self.ltr.throw_out_reading()
144
+ except ValueError:
145
+ pass
146
+
147
+ def data_ready(self):
148
+ return bool(self.ltr.new_als_data_available)
149
+
150
+ def read_raw(self):
151
+ """(ch0, ch1, valid). valid=False when the sensor sets the data-invalid bit."""
152
+ try:
153
+ ch0, ch1 = self.ltr.light_channels
154
+ return ch0, ch1, True
155
+ except ValueError:
156
+ return FULL_SCALE, FULL_SCALE, False
157
+
158
+ def led(self, on):
159
+ self.GPIO.output(self.cfg["led_gpio"], self.GPIO.HIGH if on else self.GPIO.LOW)
160
+
161
+ def show(self, l1, l2=""):
162
+ if self.lcd is not None:
163
+ try:
164
+ self.lcd.home()
165
+ self.lcd.write_string(f"{l1[:16]:<16}")
166
+ self.lcd.cursor_pos = (1, 0)
167
+ self.lcd.write_string(f"{l2[:16]:<16}")
168
+ except Exception as e:
169
+ print(f"[WARN] LCD write failed: {e}")
170
+ print(f"[LCD] {l1[:16]:<16} | {l2[:16]}", flush=True)
171
+
172
+ def pressed(self, which):
173
+ pin = self.cfg["button_ok_gpio"] if which == "ok" else self.cfg["button_mode_gpio"]
174
+ return self.GPIO.input(pin) == self.GPIO.LOW
175
+
176
+ def sleep(self, s):
177
+ time.sleep(s)
178
+
179
+ def now(self):
180
+ return time.monotonic()
181
+
182
+ def close(self):
183
+ try:
184
+ self.led(False)
185
+ if self.lcd is not None:
186
+ self.lcd.clear()
187
+ self.lcd.backlight_enabled = False
188
+ self.lcd.close()
189
+ except Exception:
190
+ pass
191
+ finally:
192
+ self.GPIO.cleanup()
193
+
194
+
195
+ class SimHardware:
196
+ """Software stand-in for tests on a PC: blank ~23 000 counts at 96x/200, 0.03 % noise,
197
+ a few dark counts, saturation, rare invalid conversions. Button presses come from `script`,
198
+ a list of ("ok" | "mode", hold_seconds); keyboard input for pratico3_cal comes from stdin."""
199
+
200
+ def __init__(self, cfg, script=None, seed=1, k=1.206, invalid_rate=0.002):
201
+ self.cfg = cfg
202
+ self.rng = random.Random(seed)
203
+ self.k, self.invalid_rate = k, invalid_rate
204
+ self.t = 0.0
205
+ self.led_on = False
206
+ self.absorbance = 0.0 # set by the test harness
207
+ self.lid_open = False
208
+ self.script = list(script or [])
209
+ self._press = None
210
+ self._last = 0.0
211
+ self.lcd_lines = ("", "")
212
+ self.apply_settings(cfg["gain"], cfg["integration_ms"], cfg["rate_ms"])
213
+
214
+ def apply_settings(self, gain, integration_ms, rate_ms):
215
+ self.gain, self.integration_ms = gain, integration_ms
216
+ self.rate_ms = max(rate_ms, rate_for(integration_ms))
217
+ self._last = self.t
218
+
219
+ def data_ready(self):
220
+ return self.t - self._last >= self.rate_ms / 1000
221
+
222
+ def read_raw(self):
223
+ self._last = self.t
224
+ if self.rng.random() < self.invalid_rate:
225
+ return FULL_SCALE, FULL_SCALE, False
226
+ scale = self.gain * self.integration_ms
227
+ dark = 2.6 * scale / (96 * 400) + (0.05 * FULL_SCALE * scale / (96 * 400) if self.lid_open else 0)
228
+ sig = self.k * scale * 10 ** (-self.absorbance) if self.led_on else 0.0
229
+ ch0 = dark + sig * (1 + self.rng.gauss(0, 0.0003))
230
+ ch0 = int(max(0, round(ch0 + self.rng.gauss(0, 0.3))))
231
+ if ch0 >= FULL_SCALE:
232
+ return FULL_SCALE, FULL_SCALE, False
233
+ return ch0, int(ch0 * 0.27), True
234
+
235
+ def led(self, on):
236
+ self.led_on = bool(on)
237
+
238
+ def show(self, l1, l2=""):
239
+ self.lcd_lines = (l1[:16], l2[:16])
240
+ print(f"[LCD t={self.t:7.1f}s] {l1[:16]:<16} | {l2[:16]}", flush=True)
241
+
242
+ def pressed(self, which):
243
+ if self._press is None:
244
+ if not self.script:
245
+ raise SystemExit("[SIM] no more scripted button presses")
246
+ btn, hold = self.script.pop(0)
247
+ self._press = (btn, self.t, hold)
248
+ btn, t0, hold = self._press
249
+ if self.t - t0 > hold:
250
+ self._press = None
251
+ return False
252
+ return btn == which
253
+
254
+ def sleep(self, s):
255
+ self.t += s
256
+
257
+ def now(self):
258
+ return self.t
259
+
260
+ def close(self):
261
+ pass
262
+
263
+
264
+ def make_hw(cfg, simulate=False, **kw):
265
+ return SimHardware(cfg, **kw) if simulate else Hardware(cfg)
266
+
267
+
268
+ # ============================================================================ acquisition
269
+ class MeasureError(Exception):
270
+ pass
271
+
272
+
273
+ def read_fresh(hw, timeout=None):
274
+ """Wait for a NEW conversion and return it as dict(t, ch0, ch1, valid)."""
275
+ timeout = timeout or max(2.0, 4 * hw.rate_ms / 1000)
276
+ t_end = hw.now() + timeout
277
+ while hw.now() < t_end:
278
+ if hw.data_ready():
279
+ ch0, ch1, ok = hw.read_raw()
280
+ return {"t": hw.now(), "ch0": ch0, "ch1": ch1, "valid": ok}
281
+ hw.sleep(0.01)
282
+ raise MeasureError("Sensor timeout")
283
+
284
+
285
+ def read_valid(hw, n, cfg, bad):
286
+ """n valid conversions; isolated invalid ones are replaced (counted in bad[0])."""
287
+ out = []
288
+ while len(out) < n:
289
+ r = read_fresh(hw)
290
+ if r["valid"]:
291
+ out.append(r)
292
+ continue
293
+ bad[0] += 1
294
+ if bad[0] > cfg["max_invalid"]:
295
+ raise MeasureError("Saturated")
296
+ return out
297
+
298
+
299
+ def measure_cycle(hw, cfg):
300
+ """One pulsed cycle. Returns dict(net, mean, dark, sd, spread, n, ch0, ...)."""
301
+ bad = [0]
302
+ t_wall = time.time()
303
+ try:
304
+ hw.led(False)
305
+ read_fresh(hw) # conversion in progress: discard
306
+ dk = read_valid(hw, cfg["n_dark"], cfg, bad)
307
+ dark = statistics.fmean(d["ch0"] for d in dk)
308
+ if max(d["ch0"] for d in dk) > cfg["dark_max_counts"]:
309
+ raise MeasureError("Light leak/lid")
310
+ hw.led(True)
311
+ for _ in range(cfg["discard_after_on"]):
312
+ read_fresh(hw)
313
+ rd = read_valid(hw, cfg["n_avg"], cfg, bad)
314
+ finally:
315
+ hw.led(False)
316
+ vals = [r["ch0"] for r in rd]
317
+ if max(vals) >= cfg["sat_counts"]:
318
+ raise MeasureError("Saturated")
319
+ mean = statistics.fmean(vals)
320
+ sd = statistics.stdev(vals) if len(vals) > 1 else 0.0
321
+ net = mean - dark
322
+ spread = (max(vals) - min(vals)) / mean if mean > 0 else float("inf")
323
+ out = dict(net=net, mean=mean, dark=dark, sd=sd, spread=spread, n=len(vals), ch0=vals,
324
+ invalid=bad[0], gain=hw.gain, integration_ms=hw.integration_ms, rate_ms=hw.rate_ms,
325
+ t_wall=t_wall, t_mono=rd[len(rd) // 2]["t"])
326
+ if net < cfg["min_signal_counts"]:
327
+ raise MeasureError("No signal")
328
+ if spread > cfg["max_rel_spread"]:
329
+ raise MeasureError("Unstable signal")
330
+ return out
331
+
332
+
333
+ def measure_repeated(hw, cfg, k):
334
+ """k cycles merged (used for the blank)."""
335
+ ms = [measure_cycle(hw, cfg) for _ in range(max(1, k))]
336
+ if len(ms) == 1:
337
+ return ms[0]
338
+ out = dict(ms[-1])
339
+ nets = [m["net"] for m in ms]
340
+ out.update(net=statistics.fmean(nets), mean=statistics.fmean(m["mean"] for m in ms),
341
+ dark=statistics.fmean(m["dark"] for m in ms), ch0=[v for m in ms for v in m["ch0"]],
342
+ n=sum(m["n"] for m in ms), cycles=len(ms),
343
+ cycle_rsd=statistics.stdev(nets) / statistics.fmean(nets))
344
+ out["sd"] = statistics.stdev(out["ch0"])
345
+ return out
346
+
347
+
348
+ def autorange(hw, cfg):
349
+ """Lower the gain until the blank (cuvette in, LED on) is inside target_fs. Returns gain."""
350
+ lo, hi = cfg["target_fs"]
351
+ for g in [g for g in GAINS if g <= cfg["gain"]][::-1]:
352
+ hw.apply_settings(g, cfg["integration_ms"], cfg["rate_ms"])
353
+ hw.led(True)
354
+ try:
355
+ read_fresh(hw)
356
+ read_fresh(hw)
357
+ r = read_fresh(hw)
358
+ finally:
359
+ hw.led(False)
360
+ frac = r["ch0"] / FULL_SCALE if r["valid"] else 1.0
361
+ if frac <= hi:
362
+ cfg["gain"] = g
363
+ return g
364
+ cfg["gain"] = GAINS[0]
365
+ return GAINS[0]
366
+
367
+
368
+ def absorbance(sample_net, blank_net):
369
+ if blank_net <= 0 or sample_net <= 0:
370
+ return None
371
+ return -math.log10(sample_net / blank_net)
372
+
373
+
374
+ def sigma_absorbance(sample, blank):
375
+ """1-sigma of A from the scatter of the averaged conversions (instrument noise only)."""
376
+ def rel(m):
377
+ return (m["sd"] / math.sqrt(max(m["n"], 1))) / m["net"] if m["net"] > 0 else float("inf")
378
+ return math.sqrt(rel(sample) ** 2 + rel(blank) ** 2) / math.log(10)
379
+
380
+
381
+ # ============================================================================ buttons / keyboard
382
+ def _stdin_line_ready():
383
+ if sys.platform.startswith("win") or not sys.stdin or not sys.stdin.isatty():
384
+ return False
385
+ import select
386
+ return bool(select.select([sys.stdin], [], [], 0)[0])
387
+
388
+
389
+ def wait_key(hw, long_press_s=3.0, keyboard=False):
390
+ """Wait for OK or MODE (or Enter on the keyboard when keyboard=True).
391
+ Returns 'ok', 'mode', 'mode_long' or the typed text (keyboard)."""
392
+ while True:
393
+ if keyboard and _stdin_line_ready():
394
+ return sys.stdin.readline().strip() or "ok"
395
+ for b in ("ok", "mode"):
396
+ if hw.pressed(b):
397
+ t0 = hw.now()
398
+ while hw.pressed(b):
399
+ hw.sleep(0.02)
400
+ if b == "mode" and hw.now() - t0 >= long_press_s:
401
+ hw.show("Release MODE", "")
402
+ while hw.pressed(b):
403
+ hw.sleep(0.02)
404
+ return "mode_long"
405
+ hw.sleep(0.05)
406
+ return b
407
+ hw.sleep(0.02)
408
+
409
+
410
+ def countdown(hw, seconds, label, keyboard=False):
411
+ """Reaction timer started when the reagent is added. MODE (or 's' + Enter) skips.
412
+ Returns the monotonic start time."""
413
+ t0 = hw.now()
414
+ last = None
415
+ while True:
416
+ left = int(math.ceil(seconds - (hw.now() - t0)))
417
+ if left <= 0:
418
+ return t0
419
+ if left != last:
420
+ hw.show(f"{label} wait {left:>4}s"[:16], "MODE = skip")
421
+ last = left
422
+ if hw.pressed("mode"):
423
+ while hw.pressed("mode"):
424
+ hw.sleep(0.02)
425
+ return t0
426
+ if keyboard and _stdin_line_ready() and sys.stdin.readline().strip().lower() == "s":
427
+ return t0
428
+ hw.sleep(0.05)
429
+
430
+
431
+ # ============================================================================ calibration file
432
+ def load_calibration(path):
433
+ """{'N': {...}, 'P': {...}}; entries have slope, intercept (A = slope*C + intercept)."""
434
+ with open(path) as f:
435
+ cal = json.load(f)
436
+ for an in ("N", "P"):
437
+ if an in cal and not {"slope", "intercept"} <= set(cal[an]):
438
+ raise ValueError(f"calibration entry {an} incomplete")
439
+ return cal
440
+
441
+
442
+ def save_calibration(path, cal):
443
+ os.makedirs(os.path.dirname(path), exist_ok=True)
444
+ if os.path.exists(path):
445
+ shutil.copy2(path, path.replace(".json", time.strftime("_%Y%m%d-%H%M%S.json")))
446
+ tmp = path + ".tmp"
447
+ with open(tmp, "w") as f:
448
+ json.dump(cal, f, indent=2)
449
+ f.flush()
450
+ os.fsync(f.fileno())
451
+ os.replace(tmp, path)
452
+
453
+
454
+ def concentration(A, entry):
455
+ """Concentration and a flag: '' ok, '<LOD', '>range'."""
456
+ if A is None or not entry or entry.get("slope", 0) == 0:
457
+ return None, "no cal"
458
+ c = (A - entry["intercept"]) / entry["slope"]
459
+ flag = ""
460
+ if entry.get("lod") is not None and c < entry["lod"]:
461
+ flag = "<LOD"
462
+ elif entry.get("c_max") is not None and c > 1.1 * entry["c_max"]:
463
+ flag = ">range"
464
+ return c, flag
465
+
466
+
467
+ # ============================================================================ results / logs
468
+ RES_FIELDS = ["seq", "datetime", "clock_synced", "uptime_s", "analyte", "conc_mgL", "flag", "A",
469
+ "sigma_A", "reaction_s", "sample_net", "blank_net", "blank_age_s", "dark", "gain",
470
+ "integration_ms", "n_avg", "spread", "invalid", "cal_date", "fw"]
471
+
472
+
473
+ def clock_synced():
474
+ try:
475
+ out = subprocess.run(["timedatectl", "show", "-p", "NTPSynchronized", "--value"],
476
+ capture_output=True, text=True, timeout=3).stdout.strip()
477
+ return out == "yes"
478
+ except Exception:
479
+ return False
480
+
481
+
482
+ def uptime_s():
483
+ try:
484
+ with open("/proc/uptime") as f:
485
+ return float(f.read().split()[0])
486
+ except OSError:
487
+ return time.monotonic()
488
+
489
+
490
+ def append_result(path, row):
491
+ os.makedirs(os.path.dirname(path), exist_ok=True)
492
+ new = not os.path.exists(path)
493
+ seq = 1
494
+ if not new:
495
+ with open(path) as f:
496
+ seq = max(1, sum(1 for _ in f)) # header + n rows -> next = n + 1
497
+ row = dict(row, seq=seq)
498
+ with open(path, "a") as f:
499
+ if new:
500
+ f.write(",".join(RES_FIELDS) + "\n")
501
+ f.write(",".join("" if row.get(k) is None else str(row.get(k)) for k in RES_FIELDS) + "\n")
502
+ f.flush()
503
+ os.fsync(f.fileno())
504
+ return seq
505
+
506
+
507
+ def log_raw(cfg, kind, m, extra=None):
508
+ """Every reading with its conversions, one JSON line per measurement."""
509
+ try:
510
+ os.makedirs(cfg["log_dir"], exist_ok=True)
511
+ rec = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "kind": kind, **m}
512
+ if extra:
513
+ rec.update(extra)
514
+ with open(os.path.join(cfg["log_dir"], time.strftime("%Y%m%d") + ".jsonl"), "a") as f:
515
+ f.write(json.dumps(rec) + "\n")
516
+ except OSError:
517
+ pass
518
+
519
+
520
+ # ============================================================================ self test
521
+ def selftest(simulate=False):
522
+ """Non-interactive check: settings, one blank-style reading, dark and LED levels."""
523
+ cfg = load_config()
524
+ hw = make_hw(cfg, simulate=simulate)
525
+ try:
526
+ cp = config_path()
527
+ print(f"PRATICO 3 core {VERSION} config {cp if os.path.exists(cp) else 'built-in defaults'}")
528
+ print(f"setting {hw.gain}x / {hw.integration_ms} ms / rate {hw.rate_ms} ms")
529
+ hw.show("PRATICO 3", "self test")
530
+ m = measure_cycle(hw, cfg)
531
+ print(f"dark {m['dark']:.1f} LED {m['mean']:.1f} ({m['mean'] / FULL_SCALE:.1%} FS) "
532
+ f"net {m['net']:.1f} CV {m['sd'] / m['mean']:.3%} spread {m['spread']:.3%} "
533
+ f"n {m['n']} invalid {m['invalid']}")
534
+ hw.show("Self test OK", f"{m['mean'] / FULL_SCALE:.0%} FS")
535
+ return 0
536
+ except MeasureError as e:
537
+ print(f"[FAIL] {e}")
538
+ hw.show("Self test FAIL", str(e))
539
+ return 1
540
+ finally:
541
+ hw.sleep(1.0)
542
+ hw.close()
543
+
544
+
545
+ def main(argv=None):
546
+ """pratico-selftest: hardware self test (or --simulate without hardware)."""
547
+ import argparse
548
+ ap = argparse.ArgumentParser(description="PRATICO 3 hardware self test")
549
+ ap.add_argument("--simulate", action="store_true", help="no hardware (PC test)")
550
+ ap.add_argument("--version", action="version", version=f"PRATICO 3 firmware {VERSION}")
551
+ return selftest(simulate=ap.parse_args(argv).simulate)
552
+
553
+
554
+ if __name__ == "__main__":
555
+ raise SystemExit(main())
pratico3_service.py ADDED
@@ -0,0 +1,118 @@
1
+ #!/usr/bin/env python3
2
+ """PRATICO 3 - start the field program at every power-on (systemd *user* service, no sudo).
3
+
4
+ pratico-service install install and enable pratico3.service, then start it
5
+ pratico-service uninstall stop, disable and remove it
6
+ pratico-service status show whether it is installed, enabled and running
7
+
8
+ From a git checkout the same works with python3 pratico3_service.py install (or bash install.sh).
9
+ Run it as the normal user (e.g. fww), not with sudo.
10
+ """
11
+ import argparse
12
+ import os
13
+ import subprocess
14
+ import sys
15
+
16
+ import pratico3_core as core
17
+
18
+ UNIT = "pratico3.service"
19
+ UNIT_DIR = os.path.join(core.HOME, ".config", "systemd", "user")
20
+ UNIT_PATH = os.path.join(UNIT_DIR, UNIT)
21
+
22
+
23
+ def unit_text():
24
+ """The unit runs this Python on pratico3_usr.py, so it works for pipx, pip and git installs."""
25
+ here = os.path.dirname(os.path.abspath(__file__))
26
+ usr = os.path.join(here, "pratico3_usr.py")
27
+ return f"""[Unit]
28
+ Description=PRATICO 3 field program (buttons + LCD)
29
+ After=basic.target
30
+
31
+ [Service]
32
+ Type=simple
33
+ WorkingDirectory={here}
34
+ ExecStart={sys.executable} -u {usr}
35
+ Restart=on-failure
36
+ RestartSec=5
37
+ KillSignal=SIGTERM
38
+ TimeoutStopSec=10
39
+
40
+ [Install]
41
+ WantedBy=default.target
42
+ """
43
+
44
+
45
+ def systemctl(*args, check=False):
46
+ return subprocess.run(["systemctl", "--user", *args], capture_output=True, text=True, check=check)
47
+
48
+
49
+ def out(cmd):
50
+ try:
51
+ return subprocess.run(cmd, capture_output=True, text=True).stdout.strip()
52
+ except OSError:
53
+ return ""
54
+
55
+
56
+ def warnings(cfg):
57
+ user = os.environ.get("USER") or os.path.basename(core.HOME)
58
+ if out(["loginctl", "show-user", user, "-p", "Linger", "--value"]) != "yes":
59
+ print("\n!! Linger is off: user services start only after a login. Enable start at boot with:")
60
+ print(f" sudo loginctl enable-linger {user}")
61
+ if subprocess.run(["systemctl", "is-enabled", "--quiet", "fww.service"]).returncode == 0:
62
+ print("\n!! The PRATICO 2 service fww.service is enabled and would compete for the hardware:")
63
+ print(" sudo systemctl disable --now fww.service")
64
+ if not os.path.exists(cfg["cal_file"]):
65
+ print("\nNo calibration yet: the field program shows absorbance only until you run pratico-cal")
66
+
67
+
68
+ def install(start=True):
69
+ cfg = core.load_config()
70
+ for d in (UNIT_DIR, os.path.dirname(cfg["cal_file"]), os.path.dirname(cfg["res_file"]), cfg["log_dir"]):
71
+ os.makedirs(d, exist_ok=True)
72
+ with open(UNIT_PATH, "w") as f:
73
+ f.write(unit_text())
74
+ systemctl("daemon-reload", check=True)
75
+ systemctl("enable", UNIT, check=True)
76
+ print(f"{UNIT} installed and enabled (python {sys.executable})")
77
+ if start:
78
+ systemctl("restart", UNIT)
79
+ print("started:", systemctl("is-active", UNIT).stdout.strip())
80
+ warnings(cfg)
81
+ print("\nLogs: journalctl --user-unit=pratico3 -f")
82
+ return 0
83
+
84
+
85
+ def uninstall():
86
+ systemctl("disable", "--now", UNIT)
87
+ if os.path.exists(UNIT_PATH):
88
+ os.remove(UNIT_PATH)
89
+ systemctl("daemon-reload")
90
+ print(f"{UNIT} stopped and removed (calibration and results are kept in {core.BASE})")
91
+ return 0
92
+
93
+
94
+ def status():
95
+ print(f"unit file : {UNIT_PATH if os.path.exists(UNIT_PATH) else 'not installed'}")
96
+ print(f"enabled : {systemctl('is-enabled', UNIT).stdout.strip() or 'no'}")
97
+ print(f"active : {systemctl('is-active', UNIT).stdout.strip() or 'no'}")
98
+ cp = core.config_path()
99
+ print(f"firmware : {core.VERSION} config {cp if os.path.exists(cp) else 'built-in defaults'}")
100
+ return 0
101
+
102
+
103
+ def main(argv=None):
104
+ ap = argparse.ArgumentParser(description="PRATICO 3 boot service (systemd user service)")
105
+ ap.add_argument("action", choices=["install", "uninstall", "status"])
106
+ ap.add_argument("--no-start", action="store_true", help="install and enable, but do not start now")
107
+ args = ap.parse_args(argv)
108
+ if not sys.platform.startswith("linux"):
109
+ sys.exit("pratico-service is for the Raspberry Pi (Linux with systemd).")
110
+ if os.geteuid() == 0:
111
+ sys.exit("Run as the normal user (e.g. fww), not with sudo.")
112
+ if args.action == "install":
113
+ return install(start=not args.no_start)
114
+ return uninstall() if args.action == "uninstall" else status()
115
+
116
+
117
+ if __name__ == "__main__":
118
+ sys.exit(main())