[PolygonPrincess]

Summary

This branch turns libeverlive-core into the shared foundation for both capture engines and gives the GC570D the same control plane as the GC573.

It removes the duplicated JSON-RPC scanner, socket-path logic, and PCI discovery code, moves the GC573 sources into a src/ layout, adds a unified everlive.sock endpoint to the DUO daemon, consolidates the unit tests, and adds a top-level build/install flow that ships everlive-ctl and the core library system-wide.

The existing everlive.sock wire format is unchanged (proto: 1, newline-delimited JSON-RPC 2.0); GC573 clients keep working, and the GC570D now answers the same protocol alongside its legacy gc570d-ctl socket.

Motivation

• jsmn, JSON escaping, request validation, and socket-path resolution existed only inside the GC573 engine; tests reached them by #include-ing a .c file.
• PCI discovery was duplicated in five places, and gc573_vfio.c accepted 1461:0054 without checking the subsystem — a GC570D could be claimed by the GC573 engine.
• everlive-ctl looked for everlive-experimental.sock, which no engine ever bound.
• The GC570D had no machine-readable status/control API, so the hub had to scrape logs and shell out to gc570d-ctl.
• Nothing installed the core library, everlive-ctl, or the universal everlive.service unit.
• tests/Makefile recompiled core sources and carried merge artifacts (duplicate -D_GNU_SOURCE, duplicate asan target).

What changed

Shared core (tools/libeverlive-core)

• New everlive_json.{c,h}: stateless, jsmn-backed typed getters, raw/id helpers, top-level key detection, JSON escaping, and ID normalisation.
• New everlive_ipc.{c,h}: deterministic socket resolution
  override → $EVERLIVE_SOCKET → $EVERLIVE_CONTROL_SOCKET → $XDG_RUNTIME_DIR → /run/user/<uid> → /tmp/everlive-<uid>,
  plus a prepare variant that creates the runtime directory for the server side.
• everlive_ctl_proto.c now reuses the shared escaper and detects errors with a real top-level key check instead of a strstr heuristic.
• everlive_ctl.c connects to the live everlive.sock; the stale everlive-experimental.sock path is gone.
• everlive_card: added everlive_find_card_by_slug().
• jsmn moved into the core and is compiled into both the static and shared archives.
• Library version bumped to 0.2.0, SONAME libeverlive_core.so.0; headers install with the library.

GC573 (tools/opengc573-userd)

• Sources and headers moved to src/; binaries stay at the module root so play.sh, the installers, and systemd units keep their paths.
• Incremental object build with three flag groups: hardware/base, capture pipeline (FFmpeg + PipeWire), and the SDL2 renderer. probe, everlive_userd, and diag no longer require SDL2/FFmpeg/PipeWire headers.
• Links libeverlive_core.a.
• Discovery uses everlive_detect_installed_cards() and accepts only gc573 descriptors. This fixes the DUO misidentification: 1461:0054 + subsystem 0x5700 is rejected, and an unreadable subsystem file fails safe.
• Control socket resolution uses the core helper, so --ipc-socket, EVERLIVE_SOCKET, and the runtime fallbacks all agree with the hub and everlive-ctl.

GC570D (tools/opengc570d-userd)

• Discovery uses the core registry and accepts only gc570d descriptors.
• New src/gc570d-jsonrpc.{c,h}: persistent AF_UNIX clients, SO_PEERCRED UID check, flock-protected everlive.sock, line-buffered dispatch, no extra thread.
• Methods: hello, ping, status.get, led.set, led.mode.set, audio.volume.set, audio.mute.set, audio.channels.set, osd.set, osd.position.set, aspect.set, scale.set, input.set, pip.set, hotplug, edid.set.
• status.get emits the same schema as the GC573 engine (signal, video, audio, v4l2, osd, aspect, scale, framegen, led, clients), so the Python hub consumes it unchanged.
• GC573-only methods (mode.set, v4l2.set, hdr.*, framegen.set, toast.show) return -32601 explicitly so clients can probe capabilities.
• Support APIs: gc570d_led_set_rgb(), gc570d_led_set_effect() (the sysfs effect attribute delegates to the same code), gc570d_user_diag_action(), frontend getters, and gc570d_user_pipeline_stats().
• Re-init clears the JSON-RPC device pointer before drv->remove() and re-arms it after re-probe.
• The legacy plain-text gc570d-ctl socket is unchanged.

Viewer

• The hub attaches to a running DUO engine; the previous duo_mode guard is gone.
• DUO input, HPD, EDID policy, and LED effects prefer IPC and fall back to gc570d-ctl.
• DUO LED mode numbering is preserved (8 = colorful, 9 = breathing).

Tests

• tests/test_ipc_json.c → tests/test_json_rpc.c; it exercises the core scanners directly.
• Core tests link libeverlive_core.a; GC570D tests still compile their engine modules with -DGC570D_USERSPACE and their own kernel-shim stubs.
• The framegen cadence test moved to tests/ and is part of make test.
• Output is grouped by component; make -C tests asan cleans, rebuilds with ASan/UBSan, and runs.
• tests/run_tests.sh supports --asan.

Build, install, launch, CI

• New top-level Makefile: all, test, check, asan, clean, install, uninstall.
• build.sh is a thin wrapper around the root build.
• install.sh installs the core library, everlive-ctl, everlive-service, headers, the PREFIX-templated everlive.service unit, and the GC573 bind script.
• uninstall.sh removes the core artifacts, stale versioned libraries, the unit, and leftover runtime sockets.
• play.sh prefers everlive-ctl detect (sysfs fallback), rebuilds using real target checks, and preserves the GC573 default when no card is found.
• everlive-service.sh shares the same detection path and finds the GC570D bind helper in libexec.
• CI builds with GCC and Clang, runs the unified tests and sanitizer target, exercises the framegen forwarding target, and checks shell syntax.

Compatibility and behavior changes

• Wire protocol: unchanged (proto: 1, newline-delimited JSON-RPC 2.0 over everlive.sock). The DUO is a new endpoint, not a format change.
• GC573 discovery: a GC570D sharing 1461:0054 is no longer claimed; cards with an unreadable subsystem ID are reported as unsupported instead of being guessed.
• JSON escaping: control characters now use \n, \r, \t short forms (other bytes < 0x20 remain \uXXXX). Semantically identical JSON; textual expectations in tests were updated.
• IDs: non-canonical integers such as "0012" are echoed as strings instead of invalid bare numbers.
• --ipc-socket: the parent directory is now created by the shared helper.
• GC570D LED effect attribute: also accepts "off".
• Hub: now observes DUO engines via IPC; gc570d-ctl remains available.

Verification

Check	Result
make -j"$(nproc)" (GCC)	core + both engines build clean
make -j"$(nproc)" with CC=clang	builds clean
make -C tests clean test	7 suites / 164 assertions pass
make -C tests asan	ASan/UBSan clean
./tests/run_tests.sh / --asan	pass
make install DESTDIR=… PREFIX=/usr	installs core, everlive-ctl, unit, headers, GC570D artefacts
make uninstall DESTDIR=… PREFIX=/usr	removes exactly the installed files
bash -n on all scripts, py_compile on the hub	clean
DUO hardware smoke	engine starts, /run/user/<uid>/everlive.sock binds, legacy socket still serves

Recommended before merge: a GC573 hardware smoke test of play.sh, everlive-ctl runtime status, and the background service.

Reviewer guide

Commit order and focus:

1. e9f4aec — core JSON/IPC extraction. Start here; everything else consumes these APIs.
2. 1f7b450 — GC573 src/ layout, flag split, core discovery. Large diff mostly renames; the behavioural change is the subsystem-aware probe.
3. f4d674f — GC570D JSON-RPC server, LED/diag support APIs, daemon poll integration, viewer attach. Highest-risk commit; review gc570d-jsonrpc.c, re-init/shutdown ordering, and the persistent-client buffering.
4. b17494d — unified tests. Check that GC570D tests still avoid linking the core archive.
5. 594ce97 — root Makefile, installers, launchers, CI. Check PREFIX/DESTDIR handling and service paths.

43 of the 78 files in the integration delta are pure renames; the logical surface is roughly 35 files.

Open items identified during self-review

Before merge, consider addressing:

• install.sh installs everlive.service, but the installed service script resolves the GC573 engine at /usr/local/bin/gc573_user_streamer, which install.sh never installs. On a GC573 system the unit would fail (and Restart=on-failure would loop). Install the GC573 engine (and setcap the installed copy), or resolve the repo path at install time.
• After led.mode.set {"mode":"off"}, the GC570D zeroes led_cdev.brightness; subsequent breathing/colorful effects compute zero components and stay dark until a static RGB led.set. Restore a non-zero brightness when applying a non-off effect.

Lower-priority hardening (not blocking): reject non-finite doubles in everlive_json_get_double() (the GC570D volume handler casts NaN to int), guard everlive_yuy2_to_rgb_scaled() against odd src_w, and derive the runtime UID from SUDO_USER in uninstall.sh.

Checklist

• Builds with GCC and Clang
• Unit tests and sanitizer run pass
• Install/uninstall round-trip verified with DESTDIR
• Shell and Python syntax checks
• README and CHANGELOG updated
• GC573 hardware smoke test (recommended)
• Address the two before-merge items above

[Everlite]

Huge thanks @PolygonPrincess for this fantastic architectural overhaul! Unifying libeverlive-core and aligning the GC570D and GC573 control planes on the same JSON-RPC 2.0 interface is a massive step forward for the entire project.

We took this branch for a spin on real GC573 hardware:

• Live streaming via play.sh is buttery smooth (tested at 1440p @ 59.94/60 Hz with zero dropped frames).
• 7.1 L-PCM audio pipeline and passthrough are rock solid.
• Live queries via everlive-ctl runtime status talk cleanly to /run/user/<uid>/everlive.sock and output verified JSON-RPC responses.
• Headless capture service (everlive-service.sh) initializes the FPGA and audio DMA in ~2.1 s without issues.

I've pushed a commit (7112297) directly to this branch addressing all open items from your self-review:

1. GC573 Install Targets & Service Path Resolution: Added install and uninstall targets to tools/opengc573-userd/Makefile with PREFIX and DESTDIR support, wired them into the top-level Makefile, and updated install.sh and uninstall.sh. everlive-service.sh now checks the repo, /usr/local/bin, and PATH.
2. LED Brightness Recovery on Effect Switch: In gc570d-led.c, when switching from off to an active effect, brightness is restored to GC570D_LED_MAX_BRIGHTNESS if it was zero, ensuring breathing/colorful effects don't compute zero channels.
3. Hardening & Tests:
   • everlive_json_get_double() now rejects NaN and Infinity with !isfinite().
   • everlive_yuy2_to_rgb_scaled() rejects odd src_w input gracefully without buffer corruption.
   • uninstall.sh resolves TARGET_UID from SUDO_USER to reliably clean up the user runtime directory.
   • Unit tests updated (all 7 suites / 167 assertions pass under GCC and Clang; ASan/UBSan clean).

Feel free to undraft whenever you're ready, and we will merge it straight into dev!

[PolygonPrincess]

@Everlite Thanks for addressing the open items and providing testing on your end for GC573!

I think before I undraft this, do we want to include documentation for future contributors on how to implement other capture cards in EverLive by creating a set of standards and procedures to follow? Not sure if that would be considered in-scope for this PR or worthy of its own!

[Everlite]

I think having a dedicated contributor guide (e.g. docs/ADDING_NEW_CARDS.md) on how to implement new cards using libeverlive-core and the JSON-RPC interface is a fantastic idea—especially with community interest in the GC575 / GC555!

That said, since PR #63 is already quite large (+5.6k lines) and all checks and hardware smoke tests are now complete, I'd suggest keeping this PR focused on the architecture and control-plane unification. We can merge #63 now to land the foundation into dev (which also unblocks our Arch packaging in #58), and then open a dedicated PR for the contributor guidelines right after.

If you're happy with that, feel free to mark this ready for review and we'll merge!

[PolygonPrincess]

@Everlite Sounds good to me!