[Perl] DAQ system for the FAPG.
Add AGENTS files.
Changed files
AGENTS.org
@@ -0,0 +1,196 @@
1
Added:
#+TITLE: Agent Notes
2
Added:
#+AUTHOR: Marius Peter
3
Added:
#+DATE: <2026-07-07 Tue>
4
Added:
5
Added:
* Normative language
6
Added:
7
Added:
- SHALL :: mandatory.
8
Added:
- SHOULD :: expected unless there is a documented reason not to.
9
Added:
- MAY :: optional.
10
Added:
- MUST NOT :: prohibited.
11
Added:
12
Added:
* Context
13
Added:
14
Added:
** Scope
15
Added:
16
Added:
- This project SHALL implement a data acquisition (DAQ) system for an
17
Added:
aquaponic farm.
18
Added:
- The farm is the /Ferme Aquaponique du Pays de Gex/, located in the
19
Added:
/Pays de Gex/ in France.
20
Added:
21
Added:
[[https://www.lafermeaquaponique.com/]]
22
Added:
23
Added:
** Users
24
Added:
25
Added:
- This project's customers are aquaponic farmers.
26
Added:
- The project SHALL be designed so as to be most useful to them.
27
Added:
- Their level of IT sophistication SHALL be assumed to be no higher
28
Added:
than the average person.
29
Added:
- Their level of aquaponic farm design and operation expertise SHALL
30
Added:
be assumed to correspond to deep expertise.
31
Added:
32
Added:
* Architecture
33
Added:
34
Added:
** Hosts and roles
35
Added:
36
Added:
All hosts are on the same farm LAN.
37
Added:
38
Added:
- 4 DAQ nodes :: 4 Raspberry Pi 2W units, each featuring:
39
Added:
- 1 [[https://atlas-scientific.com/carrier-boards/electrically-isolated-usb-ezo-carrier-board/][Atlas Scientific USB EZO carrier board]]
40
Added:
- 1 probe provided by Atlas Scientific
41
Added:
- 1 DAQ hub :: 1 Raspberry Pi 5 unit
42
Added:
- 1 DAQ recorder :: 1 remote VPS
43
Added:
44
Added:
** OS versions
45
Added:
46
Added:
| Host | OS | Version |
47
Added:
|--------------+----------------------+----------|
48
Added:
| DAQ nodes | Raspberry Pi OS Lite | Trixie |
49
Added:
| DAQ hub | Raspberry Pi OS Lite | Trixie |
50
Added:
| DAQ recorder | Debian 11 | Bullseye |
51
Added:
| Dev machine | Gentoo | <latest> |
52
Added:
53
Added:
** Sensor nodes
54
Added:
55
Added:
The sensor nodes feature Atlas Scientific probe circuits for:
56
Added:
57
Added:
- [[https://atlas-scientific.com/embedded-solutions/ezo-ph-circuit/][pH]],
58
Added:
- [[https://atlas-scientific.com/embedded-solutions/ezo-conductivity-circuit/][EC]],
59
Added:
- [[https://atlas-scientific.com/embedded-solutions/ezo-dissolved-oxygen-circuit/][Dissolved Oxygen]],
60
Added:
- and [[https://atlas-scientific.com/embedded-solutions/ezo-orp-circuit/][ORP]].
61
Added:
62
Added:
** DAQ messaging
63
Added:
64
Added:
- The DAQ nodes SHALL publish readings over MQTT.
65
Added:
- The DAQ hub SHALL act as the MQTT broker.
66
Added:
- The DAQ recorder SHALL persist all MQTT messages to a relational
67
Added:
database.
68
Added:
69
Added:
* Repository Map
70
Added:
71
Added:
- =README.org= :: describes the overall architecture.
72
Added:
- =lib/perl5/FAPG/DAQ/= :: contains shared Perl modules.
73
Added:
- =roles/daq-node/= :: contains the probe reader script and node
74
Added:
service file. The Pi Zeros handle this role.
75
Added:
- =roles/daq-hub/= :: contains MQTT broker configuration. The Pi 5
76
Added:
handles this role.
77
Added:
- =roles/daq-recorder/= :: contains the MQTT-to-database recorder.
78
Added:
The VPS handles this role.
79
Added:
- =roles/dashboard/= :: contains the Mojolicious dashboard. The VPS
80
Added:
handles this role.
81
Added:
- =roles/vpn/= :: contains WireGuard notes and host configs. The VPN
82
Added:
is instantiated between the Pi 5 and the VPS, so that the VPS may
83
Added:
subscribe to MQTT messages as if it were on the farm LAN.
84
Added:
- =t/= :: contains cross-host smoke tests and shared test support.
85
Added:
- =CAD/= :: contains enclosure design files.
86
Added:
87
Added:
* Code
88
Added:
89
Added:
The public code repo is hosted at [[https://git.mlnp.fr/FAPG/fapg-daq]].
90
Added:
91
Added:
** Versions
92
Added:
93
Added:
- The project SHALL target Perl v5.32.1.
94
Added:
- The project SHALL implement tests based on the Test2::V0 Perl
95
Added:
module.
96
Added:
97
Added:
** Structure
98
Added:
99
Added:
- Shared DAQ behavior SHALL appear under =lib/perl5/FAPG/DAQ/= when it
100
Added:
is used by more than one role.
101
Added:
- Role-local code SHALL stay under that role's =lib/perl5=, =bin=,
102
Added:
=etc=, or =t= tree.
103
Added:
104
Added:
** Perl
105
Added:
106
Added:
- Perl code SHALL use strict/warnings.
107
Added:
- Perl script STDOUT and STDERR SHALL provide useful diagnostics in
108
Added:
the Systemd journal.
109
Added:
- Perl scripts SHALL be linted against Perl-Critic, as severely as
110
Added:
possible.
111
Added:
- Perl scripts SHALL be reformatted using Perl-Tidy.
112
Added:
113
Added:
** Shell
114
Added:
115
Added:
- Shell scripts SHALL be written in Bash.
116
Added:
- Shell scripts SHALL adhere to Google's Bash shell style guide
117
Added:
([[https://google.github.io/styleguide/shellguide.html]]).
118
Added:
- Bash scripts SHOULD be checked with =shellcheck= for critical
119
Added:
warnings.
120
Added:
121
Added:
** Conventions
122
Added:
123
Added:
- All scripts SHALL begin with an appropriate shebang line.
124
Added:
- MQTT readings SHALL use the =fapg.daq.reading.v1= schema and topics
125
Added:
shaped like:
126
Added:
127
Added:
#+begin_src text
128
Added:
fapg/daq/<probe>/<node>/reading
129
Added:
#+end_src
130
Added:
131
Added:
- Probe keys SHALL be in lowercase in payloads and topics: =ph=, =do=,
132
Added:
=orp=, and =ec=.
133
Added:
- Structured JSON parsing and generation SHALL be handled through
134
Added:
=JSON::PP=.
135
Added:
- Broad refactors SHALL be avoided while touching deployment scripts
136
Added:
or host-specific configuration.
137
Added:
- Refactors impacting Perl files SHALL be followed by a call to
138
Added:
=perltidy= to ensure homogenous Perl code style.
139
Added:
140
Added:
** Tests
141
Added:
142
Added:
The project SHALL use TAP tests through =prove= for functional
143
Added:
testing. Perl-Critic SHALL be used to verify all Perl syntax and
144
Added:
idioms.
145
Added:
146
Added:
Useful commands:
147
Added:
148
Added:
#+begin_src bash
149
Added:
prove -l
150
Added:
prove -l t
151
Added:
prove -l roles/dashboard/t
152
Added:
prove -l roles/daq-node/t
153
Added:
perlcritic --brutal fapg-daq/
154
Added:
#+end_src
155
Added:
156
Added:
Some tests are integration or hardware smoke tests:
157
Added:
158
Added:
- =t/00-ping-from-dev.t= :: expects configured hosts to be reachable.
159
Added:
- =t/01-ssh-from-dev.t= :: expects SSH access to those hosts.
160
Added:
- =roles/daq-node/t/01-ezo-usb.t= and =roles/daq-node/t/02-probe.t= ::
161
Added:
expect a probe on =/dev/ttyUSB0=.
162
Added:
- MQTT tests MAY require the configured broker and credentials.
163
Added:
- Perl unit tests MAY be added following the update of corresponding
164
Added:
Perl operational code.
165
Added:
166
Added:
** Version control system
167
Added:
168
Added:
- The project SHALL use Git as its version control system.
169
Added:
- Commits created by an AI agent SHALL indicate so in the =user.name=
170
Added:
and =user.email= fields.
171
Added:
172
Added:
* Deployment and host safety
173
Added:
174
Added:
- Files under =roles/*/etc=, =roles/*/deploy=, =roles/vpn=, and
175
Added:
=configure-sd-card= SHALL be treated as operational code.
176
Added:
- Credentials, hostnames, usernames, IP addresses, WireGuard keys,
177
Added:
MQTT ACLs, and systemd unit names MUST NOT be rotated, unless the
178
Added:
task explicitly asks for it.
179
Added:
- Service names SHOULD be kept stable, unless all dependent deployment
180
Added:
scripts and docs are updated together.
181
Added:
- Executable bits on scripts SHOULD be preserved.
182
Added:
183
Added:
* Dashboard notes
184
Added:
185
Added:
- The dashboard is a Mojolicious app under =roles/dashboard=.
186
Added:
- API responses SHALL not be stable for now. Code in
187
Added:
=roles/dashboard/public/js= SHALL be updated following backend API
188
Added:
modifications.
189
Added:
- The dashboard database path MAY be overridden with =FAPG_DAQ_DB=.
190
Added:
191
Added:
* Documentation
192
Added:
193
Added:
- This repository SHALL use Org Mode for project documentation. New
194
Added:
project docs SHALL use =.org= files.
195
Added:
- Architecture docs SHALL be updated when MQTT topics, payload schema,
196
Added:
host roles, or data flow change.
AGENTS.override.md
@@ -0,0 +1,3 @@
1
Added:
# AGENTS.override.md
2
Added:
3
Added:
Use the AGENTS.org file.