Hello Pico on Home Assistant

Layer a Home Assistant graphical ControlSurface over the approved Manifold runtime through the same Python CLI.

See the Open Engineering Language Server (OELS) onboarding guide for the local install and editor setup.

TipOELS in your editor

While you work through this content, keep the Open Engineering Language Server (OELS) active in VS Code (or any LSP-capable editor). See the OELS onboarding guide linked at the top of this page (also linked from the academy Resources page) for the one-time install and configuration steps.

What OELS validates. OELS only recognizes OE-shaped YAML/JSON: files with a mapping root that declare an apiVersion beginning with open-engineering.io/, a non-empty kind, and a DNS-1123 metadata.name. Ordinary academy metadata.yaml, Quarto/QMD pages and front matter, Kubernetes/Crossplane/runtime manifests, JSON payload samples, and shell scripts are intentionally non-OE — OELS ignores them silently and you should not add synthetic apiVersion/kind headers to force recognition.

Where you see diagnostics. OELS surfaces UnknownProperty, MissingRequiredProperty, IncorrectType, InvalidEnumValue, MalformedIdentifier, UnknownDefinition, and reference-shape hints in the editor Problems panel as you type. These are independent of quarto render: OELS diagnostics do not block rendering, and Quarto errors do not appear in the Problems panel.

The executable check still comes from this exercise. OELS speeds up editing, but the exercise’s own parser, verifier, or verify.sh (for example the pico parse … command shown below) remains the authoritative success check. Run it as usual.

Overview

Hello Pico on Home Assistant is the first graphical ControlSurface path of the Open Engineering Academy. It layers a small Home Assistant integration over the same Hello Pico on Manifold lab runtime and the same pico runtime Python CLI you already use as a scriptable ControlSurface. Home Assistant here is a control/visualization surface — it does not host the runtime, does not own the ontology, and does not bypass Kubernetes, Manifold, Wrangler, or the Python CLI.

The lab exposes exactly two surfaces:

  • One honest observation surface — a Home Assistant command_line sensor whose state is the current Pico engine Pod phase, read by delegating to pico runtime inspect against the same Manifold RuntimeEnvironment the underlying lab deploys.
  • One safe control action — a Home Assistant input_button in the default dashboard that fires a shell_command invoking pico runtime emit to send exactly one Hello, Pico! event onto the same Wrangler-declared hello Channel.
ImportantScope

This lab covers one sensor and one button wired to the approved Python CLI ControlSurface, layered over the approved single Manifold RuntimeEnvironment on local minikube. Home dashboards, multi-Pico visualization, fleet orchestration, non-Kubernetes runtime paths, and any HA integration that reads or writes Kubernetes state directly (bypassing the CLI) are explicitly out of scope.

Structure

What you will produce

A single artifact directory named hello-world-pico-home-assistant containing:

  • the merged Home Assistant configuration.yaml snippet you added,
  • the shipped helper script hello-pico-ha-phase.sh as installed inside the Home Assistant container,
  • a copy of event.json (byte-identical to the underlying Manifold lab’s payload — the single event on the wire is the same one),
  • a captured screenshot or terminal transcript of the Home Assistant sensor state and the observed Pico response after the button press.

Downloads and screenshots

Starter files live under downloads/: the Home Assistant configuration snippet, the sensor helper script, the same event.json the underlying Manifold lab uses, a README.md operator note, and verify.sh — the automatable shape check the walkthrough runs. Screenshots referenced from the walkthrough live under screenshots/.

Metadata

Machine-readable descriptor: metadata.yaml. Fields follow the schema documented in the source repository under templates/README.qmd, including the Phase 7 fields runtime_substrate, runs_on, interaction_topology, and control_surfaces (which here lists both home-assistant and python-cli because HA is layered over the CLI).

Constructive realization

This lab is a Realization of the graphical-ControlSurface role that Phase 7 of the constructive-realization contract assigns to Home Assistant. The role mapping is:

  • Definition (Phase 7 contract in templates/README.qmd): Home Assistant is a ControlSurface for graphical OperatorIntent, layered over the same declared runtime truth the Python CLI operates on. It never replaces Sandcastle, Crossplane, Kubernetes, Manifold, Wrangler, or the CLI.
  • Realization (this lab): a merged Home Assistant configuration snippet that adds one command_line sensor, one shell_command, one input_button, and one automation — with every read and write delegating to pico runtime.
  • Element: hello-world-pico-home-assistant — the captured HA snippet, helper script, event payload, and the observed sensor and Pico response.

Referenced from

  • Hello Pico on Manifold lab — the underlying runtime path this lab observes and controls.
  • bin/pico — the Python CLI ControlSurface whose runtime subcommand is the sole read/write channel this lab uses.
  • Manifold course — the runtime course whose scope explicitly excludes graphical ControlSurfaces; this lab is the follow-up path that adds one, narrowly.