docs(who2): document LN4660M2 centralized control and advanced automation commands

[GreenGrassBlueOcean]

Overview

This PR documents the BTicino LN-4660M2 (and sibling models H4660M2, AM5860M2, 067558) centralized cover controller, OpenWebNet Advanced Automation (WHO 2) General frames, and reconciles the Machine KB with reviewed atomic claims.

Changes

1. functional/who-2-automation/what.md:

   • Clarified and separated the Published command session grammar (*2*10#PRIORITY*WHERE##, *2*11#STEP#PRIORITY*WHERE##, *2*12#STEP#PRIORITY*WHERE##) from the Published event session grammar (*2*10#PRIORITY#SELECTOR*WHERE##, etc.).
   • Documented observed on-wire frames emitted by centralized transmitters targeting General scope (WHERE = 0), which emit event-style multi-parameter frames with SELECTOR = 1.
   • Added stable trace provenance links referencing public MyHomeServer1/LN4660M2 traces contributed by Francesco Montorsi on MyHOME issues #445 and #466.
   • Documented the dual-function middle button behavior (Advanced Stop when in motion, PRESET recall when stationary).

2. functional/who-2-automation/addressing.md:

   • Documented centralized transmitters configured with A=GEN targeting General scope WHERE = 0.
   • Clarified that command frames on WHERE = 0 do not identify the transmitter source address and expand into point-to-point status telemetry (DIMENSION 10) from downstream actuators, with links to the public trace fixture.

3. device-model/physical-devices.md:

   • Added LN4660M2 to the N_CONF physical configurator positions table as 6 (corroborated) from installation documentation (A, PL, Ar, PLr, M, Pre).
   • Added catalogue example for SKUs LN4660M2, H4660M2, AM5860M2, and 067558 resolving to Item 1579, model object 46, firmware 205, and single slot key object 529 ("Shutter control").

4. Machine Knowledge Base:

   • Reconciled Machine KB with 12 reviewed atomic claims (c007494–c007505) across the 4 new sections.
   • Updated test assertions in test_claim_framework.py, test_build_infrastructure.py, and test_phase12_consistency.py.

5. Repository Infrastructure (.gitattributes):

   • Added *.jsonl text eol=lf and knowledge/** text eol=lf to enforce deterministic LF line endings across platforms for Machine KB artifacts and hashing.

Verification

• Machine KB build (python build.py) and validation (python check.py): PASSED.
• Unit test suite (54 tests in knowledge/tests/ and knowledge/tools/): 54/54 PASSED.
• Editorial compliance (check_esg.py and check_ecv.py): 0 objective failures across all 146 pages.

[anotherjulien]

Thanks for putting this together — there’s useful material here, and the catalogue/device work looks solid. I also reran the repo checks locally and everything passes mechanically.

I do think we need a few changes before merging, mostly around evidence boundaries rather than the core content:

• Could we separate the published WHO 2 command grammar from the observed physical-controller/event frames? The ...#SELECTOR... forms you captured look valuable, but the spec distinguishes command and event-side forms, so I’d like that distinction to stay explicit.
• Could you add a stable provenance link/reference for the “observed live frames”? Right now the text says they were observed, but doesn’t point back to the capture.
• A few new factual sections are currently marked nonclaim in the Machine KB coverage. Since they contain real assertions, they should get reviewed atomic claims instead.
• For N_CONF = 6, the six physical configurator positions are well supported, but unless we have a diagnostic capture showing the returned N_CONF value directly, I’d phrase that as corroborated rather than observed.
• The branch is now behind current main, so it’ll need a rebase and Machine KB regeneration after the above changes.

One smaller thing: the .gitattributes LF change looks reasonable, but it’s a fairly broad infrastructure change for this PR. I’d either split that out or add a short note explaining why it’s needed here.

The LN4660M2 material itself is definitely worth keeping — I mainly want to preserve the Encyclopedia’s usual distinction between specified, observed, and inferred behavior, and make sure the Machine KB reflects the same thing.

[GreenGrassBlueOcean]

Thanks for the thoughtful and precise review @anotherjulien! All points have been addressed in the latest rebased commit (e849212):

1. Separation of published command vs event grammar (functional/who-2-automation/what.md):

   • Explicitly divided the reference into:
     • Published command session grammar (client to server): *2*10#PRIORITY*WHERE##, *2*11#STEP#PRIORITY*WHERE##, *2*12#STEP#PRIORITY*WHERE## (where STEP is 1..99 or 100/omitted, and PRIORITY is the 3-digit bitfield p1 p2 p3).
     • Published event session grammar (server to client): *2*10#PRIORITY#SELECTOR*WHERE##, *2*11#STEP#PRIORITY#SELECTOR*WHERE##, *2*12#STEP#PRIORITY#SELECTOR*WHERE## (with SELECTOR flag 0 = Clear, 1 = Set priority).
     • Observed physical transmitter frames: Documented that physical centralized transmitters (like LN4660M2) broadcasting to WHERE = 0 emit the event-style multi-parameter frame with SELECTOR = 1 directly onto the bus.

2. Stable provenance links for observed live frames:

   • Added permanent, permalinked references to the public MyHomeServer1/LN4660M2 bus monitor traces contributed by Francesco Montorsi (@f18m) on MyHOME issue #445 and #466 (comment 5853591733), linking to the stable commit tree OpenWebNet-HA/MyHOME/tree/198a848e73edd2a887b993b98beffa98f3f20e36/tests/fixtures/traces/issue_445 in both what.md and addressing.md.

3. Machine KB reviewed atomic claims:

   • Converted all 4 new sections (d000006:s000019, d000049:s000005, d000051:s000009, d000051:s000010) from nonclaim to 12 fully reviewed atomic claims (c007494 through c007505) with complete context, namespace boundaries, and evidence review records in claim-records.json, claim-context.json, and claim-coverage.json.
   • Updated unit tests (test_claim_framework.py, test_build_infrastructure.py, test_phase12_consistency.py) to assert the new corpus totals (7,427 claims across 1,173 chunks).

4. Corroborated N_CONF = 6 wording (device-model/physical-devices.md):

   • Rephrased the table entry and explanatory text to explicitly state that N_CONF = 6 is corroborated from independent installation documentation (the 6 hardware configurator sockets A, PL, Ar, PLr, M, and Pre) rather than directly observed on wire in diagnostic response frames.

5. Rebase & Machine KB Regeneration:

   • Rebased cleanly onto latest main (408f1d8), regenerated the full Machine KB manifest and artifacts (build.py), and confirmed that check.py, all 54 unit tests, and both ESG and ECV linters pass with 0 objective failures across all 146 pages.

6. Regarding .gitattributes:

   • The Machine KB build pipeline enforces strict LF normalization and canonical SHA-256 digests across all .jsonl files and knowledge/** generated artifacts. Adding *.jsonl text eol=lf and knowledge/** text eol=lf ensures that contributors checking out or building on Windows hosts (where core.autocrlf = true is commonly enabled) do not inadvertently introduce CRLF line endings that invalidate deterministic artifact hashes or cause check.py schema/privacy scan failures.

[anotherjulien]

Thanks a lot for taking the time to work through the review so thoroughly — the update addresses the main points really well. The command/event distinction is much clearer, the public trace provenance is now present, N_CONF = 6 is appropriately qualified, the branch is cleanly rebased, and the previously missing Machine KB claims are there. Much appreciated.

I only spotted a couple of small things left:

• the summary table at the top of what.md still reads as though the selector is part of the Advanced command parameters, while the detailed section now correctly separates command and event grammar;
• the observed Machine KB claims are marked as observed, but their provenance still resolves to the canonical documentation rather than directly to the public capture that supports them.

Neither feels worth asking you to go through another substantial round of changes. I’m happy to take care of those last inconsistencies myself and make sure the human-facing Encyclopedia and Machine KB end up aligned.

This PR is also a nice concrete example of the question we’ve started discussing in the canonical-evidence discussion. We collect traces like these specifically to understand and document protocol and device behaviour, so there’s a strong argument that the canonical, sanitized evidence should live alongside the knowledge it supports in the Encyclopedia.

That would make this kind of provenance much easier to preserve mechanically: an Encyclopedia claim could point directly to a stable evidence ID/hash, while MyHOME could derive or generate its test fixtures from the same evidence. In other words, the Encyclopedia would own the evidence and the documented knowledge derived from it, while MyHOME would own the tests derived from that evidence.

No need to solve that architectural question in this PR, of course — I just think this is a good real-world example of why the discussion matters.

Thanks again for the careful follow-up — this is in very good shape now.

[GreenGrassBlueOcean]

thx!