Ver código fonte

say in AGENTS.md what the Vial path rests on

The rule the previous commit should have carried with it. Three readings
of Vial's source that are not assumptions and that each break the feature
quietly if they are wrong: VialRGB is addressed through the channel byte
and not through the prefix, the discriminator is stock QMK's unhandled
marker and not the absence of one, and the IDs that come back are Vial's
namespace, so the QMK-indexed spellings may not be listed beside them.
Paul-Dieter Klumpp 1 semana atrás
pai
commit
2b9c86080c
1 arquivos alterados com 23 adições e 0 exclusões
  1. 23 0
      AGENTS.md

+ 23 - 0
AGENTS.md

@@ -335,6 +335,29 @@ definitions generate` writes the first and leaves the second open, and a name it
 wrote itself would be indistinguishable from the manufacturer's, because nothing in
 a file can be read back off a keyboard to check it.
 
+**Vial is answered before the keyboard is written to, and the answer is in Vial's
+namespace.** `internal/via/vial.go` is written from Vial's source and has never
+run against Vial firmware; the command says `experimental` in its help and on
+stdout, and that word is not to be dropped before someone has. Three things about
+it are readings of Vial's source rather than assumptions, and getting any of them
+wrong makes the feature silently useless:
+
+- VialRGB is **not** behind Vial's `0xFE` prefix. It answers VIA's ordinary
+  `0x08` lighting command and carries its own command **in the channel byte**, so
+  asking for the supported IDs is a custom get with a channel of `0x42`. Vial's
+  handlers take `msg = &data[1]`, so they echo neither channel nor value ID and
+  `readResponse`'s echoed-byte checks would reject a correct answer.
+- The discriminator is stock QMK's `default: { *command_id = id_unhandled; }`.
+  Vial's own default case does not set that marker, which is what makes `0xFE`
+  worth asking about. A version of zero means the request was echoed.
+- The IDs it sends are `VIALRGB_EFFECT_*` and the mapping to QMK's stays inside
+  the firmware. The spellings in `spotted.json` are indexed by QMK's numbers and
+  **must not** be listed beside them. The note says why instead.
+- With `VIALRGB_ENABLE` set, QMK does not compile `VIA_QMK_RGB_MATRIX_ENABLE`, so
+  VIA's `id_qmk_rgb_matrix_effect` is not served at all and an effect set by
+  number on such a board addresses Vial's field. That is a claim about Vial
+  builds, not a measurement on one, and it is why the path is experimental.
+
 The names other keyboards use are evidence and travel with their counts.
 `internal/spotted/spotted.json` is generated by `internal/spotted/generate` from a
 checkout of VIA's collection and carries the commit it was measured from. Three