[Perl] DAQ system for the FAPG.
Update agent guidance for project testing.
AGENTS.org
@@ -1,4 +1,4 @@
1
Removed:
#+TITLE: Agent Notes
1
Added:
#+TITLE: Agent Guildance
2
2
#+AUTHOR: Marius Peter
3
3
#+DATE: <2026-07-07 Tue>
4
4
@@ -8,9 +8,11 @@
8
8
- SHOULD :: expected unless there is a documented reason not to.
9
9
- MAY :: optional.
10
10
- MUST NOT :: prohibited.
11
Removed:
11
Added:
12
Added:
12
13
* Context
13
14
15
Added:
14
16
** Scope
15
17
16
18
- This project SHALL implement a data acquisition (DAQ) system for an
@@ -20,6 +22,7 @@
20
22
21
23
[[https://www.lafermeaquaponique.com/]]
22
24
25
Added:
23
26
** Users
24
27
25
28
- This project's customers are aquaponic farmers.
@@ -29,8 +32,10 @@
29
32
- Their level of aquaponic farm design and operation expertise SHALL
30
33
be assumed to correspond to deep expertise.
31
34
35
Added:
32
36
* Architecture
33
37
38
Added:
34
39
** Hosts and roles
35
40
36
41
All hosts are on the same farm LAN.
@@ -41,6 +46,7 @@
41
46
- 1 DAQ hub :: 1 Raspberry Pi 5 unit
42
47
- 1 DAQ recorder :: 1 remote VPS
43
48
49
Added:
44
50
** OS versions
45
51
46
52
| Host | OS | Version |
@@ -50,6 +56,7 @@
50
56
| DAQ recorder | Debian 11 | Bullseye |
51
57
| Dev machine | Gentoo | <latest> |
52
58
59
Added:
53
60
** Sensor nodes
54
61
55
62
The sensor nodes feature Atlas Scientific probe circuits for:
@@ -59,6 +66,7 @@
59
66
- [[https://atlas-scientific.com/embedded-solutions/ezo-dissolved-oxygen-circuit/][Dissolved Oxygen]],
60
67
- and [[https://atlas-scientific.com/embedded-solutions/ezo-orp-circuit/][ORP]].
61
68
69
Added:
62
70
** DAQ messaging
63
71
64
72
- The DAQ nodes SHALL publish readings over MQTT.
@@ -66,8 +74,9 @@
66
74
- The DAQ recorder SHALL persist all MQTT messages to a relational
67
75
database.
68
76
69
Removed:
* Repository Map
70
77
78
Added:
* Repository map
79
Added:
71
80
- =README.org= :: describes the overall architecture.
72
81
- =lib/FAPG/DAQ/= :: contains shared Perl modules.
73
82
- =roles/daq-node/= :: contains the probe reader script and node
@@ -81,19 +90,23 @@
81
90
- =roles/vpn/= :: contains WireGuard notes and host configs. The VPN
82
91
is instantiated between the Pi 5 and the VPS, so that the VPS may
83
92
subscribe to MQTT messages as if it were on the farm LAN.
84
Removed:
- =t/= :: contains cross-host smoke tests and shared test support.
93
Added:
- =t/= :: contains end-to-end smoke tests, and tests involving
94
Added:
multiple roles.
85
95
- =CAD/= :: contains enclosure design files.
86
96
97
Added:
87
98
* Code
88
99
89
100
The public code repo is hosted at [[https://git.mlnp.fr/FAPG/fapg-daq]].
90
101
102
Added:
91
103
** Versions
92
104
93
105
- The project SHALL target Perl v5.32.1.
94
106
- The project SHALL implement tests based on the Test2::V0 Perl
95
107
module.
96
108
109
Added:
97
110
** Structure
98
111
99
112
- Shared DAQ behavior SHALL appear under =lib/FAPG/DAQ/= when it
@@ -101,6 +114,7 @@
101
114
- Role-local code SHALL stay under that role's =lib=, =bin=,
102
115
=etc=, or =t= tree.
103
116
117
Added:
104
118
** Perl
105
119
106
120
- Perl code SHALL use strict/warnings.
@@ -112,6 +126,7 @@
112
126
- Perl scripts SHALL be reformatted with Perl-Tidy using the
113
127
=.perltidyrc= config file at the root of the project.
114
128
129
Added:
115
130
** Shell
116
131
117
132
- Shell scripts SHALL be written in Bash.
@@ -121,6 +136,7 @@
121
136
- Bash scripts SHOULD be checked with ~shellcheck~ for critical
122
137
warnings.
123
138
139
Added:
124
140
** Conventions
125
141
126
142
- All scripts SHALL begin with an appropriate shebang line.
@@ -136,38 +152,36 @@
136
152
- Structured JSON parsing and generation SHALL be handled through
137
153
=JSON::PP=.
138
154
155
Added:
139
156
** Tests
140
157
141
Removed:
The project SHALL use TAP tests through =prove= for functional
142
Removed:
testing. Perl-Critic SHALL be used to verify all Perl syntax and
143
Removed:
idioms.
144
158
145
Removed:
Useful commands:
159
Added:
*** Basic requirements
146
160
147
Removed:
#+begin_src bash
148
Removed:
prove -l
149
Removed:
prove -l t
150
Removed:
prove -l roles/dashboard/t
151
Removed:
prove -l roles/daq-node/t
152
Removed:
perlcritic --brutal fapg-daq/
153
Removed:
#+end_src
161
Added:
- The project SHALL implement TAP tests using the =Test2::V0= package.
162
Added:
- Tests SHALL be ran using the =prove= command.
163
Added:
- Tests SHALL be ran with the =.proverc= configuration file located at
164
Added:
the project root.
165
Added:
- All tests in a given directory SHALL be ran after modifying one or
166
Added:
more files in that directory. In case of modifications spanning
167
Added:
multiple directories, tests in each of those directories SHALL be
168
Added:
ran.
154
169
155
Removed:
Some tests are integration or hardware smoke tests:
156
170
157
Removed:
- =t/00-ping-from-dev.t= :: expects configured hosts to be reachable.
158
Removed:
- =t/01-ssh-from-dev.t= :: expects SSH access to those hosts.
159
Removed:
- =roles/daq-node/t/01-ezo-usb.t= and =roles/daq-node/t/02-probe.t= ::
160
Removed:
expect a probe on =/dev/ttyUSB0=.
161
Removed:
- MQTT tests MAY require the configured broker and credentials.
162
Removed:
- Perl unit tests MAY be added following the update of corresponding
163
Removed:
Perl operational code.
171
Added:
*** Test layouts
164
172
173
Added:
- =t/= :: end-to-end smoke tests, and tests involving more than one
174
Added:
role.
175
Added:
- =roles/*/t/= :: role-specific tests.
176
Added:
177
Added:
165
178
** Version control system
166
179
167
180
- The project SHALL use Git as its version control system.
168
181
- Commits created by an AI agent SHALL indicate so in the =user.name=
169
182
and =user.email= fields.
170
183
184
Added:
171
185
* Deployment and host safety
172
186
173
187
- Files under =roles/*/etc=, =roles/*/deploy=, =roles/vpn=, and
@@ -179,6 +193,7 @@
179
193
scripts and docs are updated together.
180
194
- Executable bits on scripts SHOULD be preserved.
181
195
196
Added:
182
197
* Dashboard notes
183
198
184
199
- The dashboard is a Mojolicious app under =roles/dashboard=.
@@ -186,6 +201,7 @@
186
201
=roles/dashboard/public/js= SHALL be updated following backend API
187
202
modifications.
188
203
- The dashboard database path MAY be overridden with =FAPG_DAQ_DB=.
204
Added:
189
205
190
206
* Documentation
191
207