Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 finn.markwitz
|
b3471a308a | ||
|
finn.markwitz
|
bf36f935e8 | ||
|
finn.markwitz
|
7bfbf4de9a | ||
|
finn.markwitz
|
28b23fe9f2 | ||
|
finn.markwitz
|
f5f8e88966 | ||
|
finn.markwitz
|
bf874d962a |
@@ -0,0 +1,189 @@
|
||||
# Alexa Media Player Integration — Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Package the `alexa_media_player` HACS component declaratively on jupiter's Home Assistant so HA can drive the household Echo devices (TTS/announce, media, sensors).
|
||||
|
||||
**Architecture:** Add one `buildHomeAssistantComponent` entry to `services.home-assistant.customComponents` (same pattern as the existing `ha-sourdough`). The component has real Python deps, so the module's `let` block also defines two supporting derivations built against HA's own interpreter: a new `dictor` package and an `alexapy` version bump. No HACS runtime, no YAML config — the integration is added through the HA UI after the rebuild.
|
||||
|
||||
**Tech Stack:** NixOS, `pkgs.buildHomeAssistantComponent`, `buildPythonPackage`, `fetchFromGitHub`/`fetchFromGitLab`/`fetchPypi`.
|
||||
|
||||
## Global Constraints
|
||||
|
||||
- Target machine: **jupiter** only. All edits live in `modules/environments/home-assistant/default.nix`.
|
||||
- Python dep derivations MUST build against Home Assistant's interpreter set — `pkgs.home-assistant.python3Packages` — the same set `buildHomeAssistantComponent` uses. Do not use top-level `pkgs.python3Packages`.
|
||||
- Manifest requirements are enforced at build time by `manifestCheckPhase` and again by HA at runtime. Every requirement must resolve to an installed dist satisfying its specifier. Exact pins (verbatim from `alexa_media_player` v5.15.7 `manifest.json`):
|
||||
- `alexapy==1.29.25`
|
||||
- `dictor>=0.1.12,<0.2`
|
||||
- `wrapt>=1.14.0` (nixpkgs 1.17.2 — already satisfied)
|
||||
- `packaging>=20.3` (nixpkgs 26.1 — already satisfied)
|
||||
- Pinned artifacts (all three hashes verified to build during planning):
|
||||
|
||||
| Artifact | Fetcher | Ref / version | Hash |
|
||||
| ------------------ | ---------------- | ------------- | ------------------------------------------------- |
|
||||
| alexa_media_player | fetchFromGitHub | `v5.15.7` | `sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=` |
|
||||
| alexapy | fetchFromGitLab | `v1.29.25` | `sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=` |
|
||||
| dictor | fetchPypi (sdist)| `0.1.12` | `sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=` |
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
Single file touched: `modules/environments/home-assistant/default.nix`.
|
||||
- Its `let` block gains `haPython`, `dictor`, and `alexapy` bindings.
|
||||
- Its `services.home-assistant.customComponents` list gains a second entry (`alexa_media`) alongside the existing `sourdough` entry.
|
||||
|
||||
No new files. The two supporting derivations are small and specific to this component, so they live inline in the module's `let` block next to their only consumer (files that change together live together).
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Package `alexa_media_player` with its Python dependencies
|
||||
|
||||
**Files:**
|
||||
- Modify: `modules/environments/home-assistant/default.nix` (the `let` block, currently lines 9-12; and the `customComponents` list, currently lines 29-41)
|
||||
|
||||
**Interfaces:**
|
||||
- Consumes: `pkgs.home-assistant.python3Packages` (HA interpreter set), `pkgs.buildHomeAssistantComponent`, `pkgs.fetchFromGitHub`, `pkgs.fetchFromGitLab`.
|
||||
- Produces: a second `customComponents` entry with `domain = "alexa_media"`. No other module consumes these `let` bindings.
|
||||
|
||||
- [ ] **Step 1: Add the supporting derivations to the `let` block**
|
||||
|
||||
Edit the `let` block so it reads exactly:
|
||||
|
||||
```nix
|
||||
let
|
||||
cfg = config.my.profiles.home-assistant;
|
||||
hostName = config.networking.hostName;
|
||||
|
||||
# Python deps for the alexa_media_player custom component (Task: Alexa).
|
||||
# Built against Home Assistant's own interpreter — the same set
|
||||
# buildHomeAssistantComponent uses — so HA's build-time and runtime
|
||||
# manifest-requirement checks are satisfied.
|
||||
haPython = pkgs.home-assistant.python3Packages;
|
||||
|
||||
# dictor is not in nixpkgs; alexa_media_player needs dictor>=0.1.12,<0.2.
|
||||
# Pure-Python, no runtime deps, legacy setup.py.
|
||||
dictor = haPython.buildPythonPackage {
|
||||
pname = "dictor";
|
||||
version = "0.1.12";
|
||||
format = "setuptools";
|
||||
src = haPython.fetchPypi {
|
||||
pname = "dictor";
|
||||
version = "0.1.12";
|
||||
hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=";
|
||||
};
|
||||
build-system = [ haPython.setuptools ];
|
||||
doCheck = false;
|
||||
pythonImportsCheck = [ "dictor" ];
|
||||
};
|
||||
|
||||
# nixpkgs ships alexapy 1.29.22; the manifest pins ==1.29.25. Patch bump.
|
||||
# nixpkgs fetches alexapy from GitLab (keatontaylor/alexapy), tag v<version>.
|
||||
alexapy = haPython.alexapy.overridePythonAttrs (old: {
|
||||
version = "1.29.25";
|
||||
src = pkgs.fetchFromGitLab {
|
||||
owner = "keatontaylor";
|
||||
repo = "alexapy";
|
||||
tag = "v1.29.25";
|
||||
hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=";
|
||||
};
|
||||
});
|
||||
in
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Add the `alexa_media` entry to `customComponents`**
|
||||
|
||||
In `services.home-assistant.customComponents`, immediately after the closing `)` of the existing `sourdough` entry (current line 40) and before the list's closing `]` (current line 41), add:
|
||||
|
||||
```nix
|
||||
(pkgs.buildHomeAssistantComponent {
|
||||
owner = "Alandtse";
|
||||
domain = "alexa_media";
|
||||
version = "5.15.7";
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "Alandtse";
|
||||
repo = "alexa_media_player";
|
||||
rev = "v5.15.7";
|
||||
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
|
||||
};
|
||||
# Every manifest requirement must be importable at a satisfying
|
||||
# version or manifestCheckPhase fails the build.
|
||||
dependencies = [
|
||||
alexapy
|
||||
dictor
|
||||
haPython.wrapt
|
||||
haPython.packaging
|
||||
];
|
||||
})
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Format the file**
|
||||
|
||||
Run: `nixfmt-rfc-style modules/environments/home-assistant/default.nix`
|
||||
Expected: exits 0, no diff surprises (re-read the file if unsure).
|
||||
|
||||
- [ ] **Step 4: Build the component in isolation first (fast feedback)**
|
||||
|
||||
This is the real test: it runs `manifestCheckPhase`, which fails loudly if any of the four requirements is unmet. It was verified to succeed during planning.
|
||||
|
||||
Run:
|
||||
```bash
|
||||
nix build --impure --no-link --print-out-paths --expr '
|
||||
let
|
||||
pkgs = (builtins.getFlake (toString ./.)).nixosConfigurations.jupiter.pkgs;
|
||||
py = pkgs.home-assistant.python3Packages;
|
||||
dictor = py.buildPythonPackage {
|
||||
pname = "dictor"; version = "0.1.12"; format = "setuptools";
|
||||
src = py.fetchPypi { pname = "dictor"; version = "0.1.12"; hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs="; };
|
||||
build-system = [ py.setuptools ]; doCheck = false; pythonImportsCheck = [ "dictor" ];
|
||||
};
|
||||
alexapy = py.alexapy.overridePythonAttrs (old: {
|
||||
version = "1.29.25";
|
||||
src = pkgs.fetchFromGitLab { owner = "keatontaylor"; repo = "alexapy"; tag = "v1.29.25"; hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4="; };
|
||||
});
|
||||
in pkgs.buildHomeAssistantComponent {
|
||||
owner = "Alandtse"; domain = "alexa_media"; version = "5.15.7";
|
||||
src = pkgs.fetchFromGitHub { owner = "Alandtse"; repo = "alexa_media_player"; rev = "v5.15.7"; hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI="; };
|
||||
dependencies = [ alexapy dictor py.wrapt py.packaging ];
|
||||
}'
|
||||
```
|
||||
Expected: prints a `/nix/store/...-Alandtse-alexa_media-5.15.7` path, exit 0. If it fails with `<pkg><specifier> not satisfied by version ...`, a dependency version drifted — re-check the manifest pin against the provided dep.
|
||||
|
||||
- [ ] **Step 5: Build the whole jupiter system (integration gate)**
|
||||
|
||||
Run: `nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'`
|
||||
Expected: builds to completion, exit 0. This confirms the module edits evaluate and the component is wired into HA's package.
|
||||
|
||||
- [ ] **Step 6: Commit**
|
||||
|
||||
```bash
|
||||
git add modules/environments/home-assistant/default.nix
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(home-assistant): add alexa_media_player custom component
|
||||
|
||||
Package the Alexa Media Player HACS component declaratively (v5.15.7),
|
||||
so HA can drive the Echo devices (TTS/announce, media, sensors). Needs
|
||||
dictor 0.1.12 (absent from nixpkgs) and an alexapy 1.29.22 -> 1.29.25
|
||||
bump to satisfy the manifest's exact requirement pins; both build
|
||||
against HA's interpreter. Config-flow based: add via the HA UI and sign
|
||||
in with the Amazon account after rebuild.
|
||||
|
||||
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-implementation (manual, by the user — not an automatable step)
|
||||
|
||||
After `sudo nixos-rebuild switch --flake '.#jupiter'`:
|
||||
1. Settings → Devices & Services → Add Integration → **Alexa Media Player**.
|
||||
2. Sign in with the Amazon account; complete any 2FA / app-password prompt in the UI flow.
|
||||
3. Confirm media_player entities and sensors appear; test a TTS/announce service call to an Echo.
|
||||
|
||||
## Self-Review
|
||||
|
||||
- **Spec coverage:** goal (alexa_media_player packaging) → Task 1; alexapy bump → Step 1; dictor packaging → Step 1; component entry → Step 2; wrapt/packaging already-satisfied → included as deps in Step 2; build-time manifest check → Steps 4-5; runtime config-flow → Post-implementation. Deferred Alexa→HA scope: intentionally absent. No gaps.
|
||||
- **Placeholder scan:** none — every step has concrete code/commands and the verified hashes.
|
||||
- **Type/name consistency:** `haPython`, `dictor`, `alexapy` defined in Step 1 and referenced by those exact names in Step 2; domain `alexa_media` consistent throughout; hashes identical across plan, spec, and the verified build.
|
||||
@@ -1,105 +0,0 @@
|
||||
# mibook: choose terminal-only vs desktop at boot
|
||||
|
||||
## Goal
|
||||
|
||||
Let mibook offer a choice, each time it boots, between the normal KDE desktop
|
||||
and a terminal-only ("server") mode with no graphical session — decided at
|
||||
boot, without rebuilding the system.
|
||||
|
||||
## Background: why the first attempt failed
|
||||
|
||||
The first implementation booted mibook to a text console by default
|
||||
(`systemd.defaultUnit = "multi-user.target"`, display manager not started) and
|
||||
provided a `desktop` command to start KDE on demand. On real hardware this
|
||||
locked the machine out:
|
||||
|
||||
- **No SSH.** mibook is WiFi-only and its WiFi credentials are stored per-user
|
||||
in KWallet ("agent-owned"). NetworkManager only receives the password once a
|
||||
desktop session is running, so a headless boot never joins the network and
|
||||
the machine has no IP — nothing to SSH into.
|
||||
- **No usable console.** The boot appeared to "hang" with no login prompt:
|
||||
`NetworkManager-wait-online` stalled waiting for a network that never came
|
||||
up, and the `getty` login prompt on tty1 was buried under later service
|
||||
messages.
|
||||
|
||||
Conclusion: a headless WiFi laptop cannot be reached remotely, and the plain
|
||||
console was hard to use. The design must (a) keep the desktop as the reliable
|
||||
default, (b) make the terminal path a deliberate, self-sufficient choice, and
|
||||
(c) not depend on the network being up.
|
||||
|
||||
## Behavior
|
||||
|
||||
- The **default GRUB entry** boots straight into KDE — unchanged from the
|
||||
known-working baseline.
|
||||
- A **separate GRUB entry, `mibook (terminal)`** (a NixOS *specialisation*),
|
||||
boots to a text console with **autologin** for `finn`. From there the user
|
||||
can work in the shell or run `desktop` to bring KDE up (via SDDM).
|
||||
- The choice is made in the GRUB menu at boot — matching the original request
|
||||
to "decide each time I boot."
|
||||
- Booting never stalls on the network.
|
||||
|
||||
### Known limitation (documented, not fixed in config)
|
||||
|
||||
In terminal mode WiFi will not connect on its own, because the password is
|
||||
stored per-user in KWallet. To reach mibook over SSH from terminal mode, the
|
||||
user must first save the WiFi as a **system** connection in KDE:
|
||||
network settings → the WiFi network → "All users may connect to this network".
|
||||
Until then, terminal mode is local-console-only. This is a one-time manual
|
||||
step outside the scope of the Nix config.
|
||||
|
||||
## Implementation
|
||||
|
||||
### `machines/mibook/configuration.nix`
|
||||
|
||||
- Add a NixOS specialisation `specialisation.terminal.configuration`:
|
||||
- `system.nixos.tags = [ "terminal" ];` — labels the generated boot entry.
|
||||
- `systemd.defaultUnit = lib.mkForce "multi-user.target";` — boots to the
|
||||
text console. `graphical.target` is what pulls in the display manager (via
|
||||
its embedded `Wants=display-manager.service`), so defaulting to
|
||||
`multi-user.target` leaves SDDM installed but not started at boot.
|
||||
- `services.getty.autologinUser = "finn";` — guarantees a usable shell on
|
||||
the console instead of a login prompt that can scroll off screen.
|
||||
- A `desktop` command via
|
||||
`pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service"`
|
||||
in `environment.systemPackages`, to start KDE on demand.
|
||||
- Add `systemd.services.NetworkManager-wait-online.enable = false;` (applies to
|
||||
both the default and terminal boots) so boot never stalls waiting for the
|
||||
network.
|
||||
|
||||
### Reverted from the first attempt
|
||||
|
||||
- `modules/environments/kde-desktop/default.nix` — remove the `startOnBoot`
|
||||
option and its `mkMerge`/`mkIf` machinery; back to the original profile that
|
||||
simply enables SDDM + Plasma 6.
|
||||
- `machines/mibook/environments.nix` — remove `kde-desktop.startOnBoot = false;`
|
||||
(back to just `kde-desktop.enable = true;`).
|
||||
|
||||
## Why a specialisation
|
||||
|
||||
A specialisation generates a second boot-menu entry automatically from a
|
||||
modified copy of the configuration. It is the idiomatic NixOS mechanism for a
|
||||
boot-time choice and avoids fragile hand-written GRUB `extraEntries` that would
|
||||
need to track kernel/initrd paths across generations. The default entry remains
|
||||
byte-for-byte the working desktop configuration.
|
||||
|
||||
## Testing / verification
|
||||
|
||||
- `nix build '.#nixosConfigurations.mibook.config.system.build.toplevel'`
|
||||
builds both `nixos-system-mibook` and `nixos-system-mibook-terminal`.
|
||||
- Verified on the built closures:
|
||||
- Parent `default.target` → `graphical.target`; no console autologin
|
||||
(identical to the pre-change baseline).
|
||||
- Specialisation `default.target` → `multi-user.target`; tty1 getty wrapper
|
||||
contains `--autologin finn`; `desktop` present in the system profile.
|
||||
- `NetworkManager-wait-online` disabled in both.
|
||||
- Post-`switch` manual check on mibook: default GRUB entry boots to KDE; the
|
||||
`terminal` entry boots to an autologged-in console; running `desktop` there
|
||||
starts SDDM and a working Plasma session.
|
||||
|
||||
## Trade-offs
|
||||
|
||||
- Autologin on the terminal console means physical access grants a shell
|
||||
without a password. Acceptable for a personal laptop the user controls; the
|
||||
desktop (default) boot is unaffected.
|
||||
- `desktop` relies on `sudo`; the user has sudo access, so no extra config is
|
||||
required.
|
||||
@@ -0,0 +1,152 @@
|
||||
# Amazon Alexa integration for Home Assistant (jupiter) — design
|
||||
|
||||
**Date:** 2026-07-29
|
||||
**Machine:** jupiter
|
||||
**Status:** approved, ready for implementation plan
|
||||
|
||||
## Goal
|
||||
|
||||
Let Home Assistant control and read the household Amazon Echo devices via the
|
||||
unofficial [`alexa_media_player`](https://github.com/Alandtse/alexa_media_player)
|
||||
integration: text-to-speech / announcements, media control, and per-device
|
||||
sensors (last-called device, next alarm/timer, DND state, etc.).
|
||||
|
||||
This uses the user's Amazon account through an unofficial API. It is a
|
||||
config-flow integration: after the rebuild it is added through the HA UI, not
|
||||
via YAML.
|
||||
|
||||
## Non-goals (deferred)
|
||||
|
||||
Alexa → HA voice control ("Alexa, turn on the light") is **out of scope**. It
|
||||
would need either `emulated_hue` bound to port 80 on the LAN, or a public HTTPS
|
||||
endpoint plus the AWS-Lambda Smart Home Skill. The user chose to decide on that
|
||||
later. Nothing in this change touches the firewall, port 80, systemd unit
|
||||
capabilities, or network exposure.
|
||||
|
||||
## Approach
|
||||
|
||||
Package the integration declaratively, following the existing `ha-sourdough`
|
||||
pattern in `modules/environments/home-assistant/default.nix` (a
|
||||
`buildHomeAssistantComponent` entry in `services.home-assistant.customComponents`).
|
||||
No HACS runtime.
|
||||
|
||||
Unlike sourdough, `alexa_media_player` has real Python dependencies. Its
|
||||
`manifest.json` (v5.15.7) declares:
|
||||
|
||||
```
|
||||
alexapy==1.29.25
|
||||
packaging>=20.3
|
||||
wrapt>=1.14.0
|
||||
dictor>=0.1.12,<0.2
|
||||
```
|
||||
|
||||
`buildHomeAssistantComponent` runs `manifestCheckPhase` at build time
|
||||
(`check_manifest.py`): every requirement must resolve to an installed
|
||||
distribution **whose version satisfies the specifier**, or the build fails.
|
||||
Home Assistant repeats this check at runtime. Therefore each requirement must be
|
||||
satisfied exactly — the exact `==1.29.25` pin in particular.
|
||||
|
||||
Dependency status in the pinned nixpkgs (`nixos-25.11`):
|
||||
|
||||
| Requirement | nixpkgs today | Action |
|
||||
| ---------------------- | ------------- | --------------------------------------- |
|
||||
| `alexapy==1.29.25` | 1.29.22 | **Bump** to 1.29.25 via override |
|
||||
| `dictor>=0.1.12,<0.2` | *absent* | **Package** dictor 0.1.12 (new) |
|
||||
| `wrapt>=1.14.0` | 1.17.2 | none — already satisfied |
|
||||
| `packaging>=20.3` | 26.1 | none — already satisfied |
|
||||
|
||||
`authcaptureproxy` (in nixpkgs at 1.3.7) is a transitive dependency of
|
||||
`alexapy`, not listed in the manifest, so it needs no direct handling.
|
||||
|
||||
## Components
|
||||
|
||||
All changes live in `modules/environments/home-assistant/default.nix` (plus the
|
||||
hashes below). Three small pieces, wired together in the module's `let` block:
|
||||
|
||||
### 1. `dictor` package (new)
|
||||
|
||||
Not in nixpkgs. Pure-Python, no runtime dependencies (`requires_dist: null`),
|
||||
ships a `setup.py`. A minimal `pkgs.python3Packages.buildPythonPackage`:
|
||||
|
||||
- pname `dictor`, version `0.1.12`
|
||||
- `src = fetchPypi { pname = "dictor"; version = "0.1.12"; hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs="; }`
|
||||
- setuptools format (legacy `setup.py`); `build-system = [ setuptools ]`
|
||||
- `doCheck = false` (no meaningful test suite); `pythonImportsCheck = [ "dictor" ]`
|
||||
|
||||
Build against the HA Python set so the version lands in HA's venv — i.e. use
|
||||
`config.services.home-assistant.package.python.pkgs` (the same interpreter the
|
||||
component check and HA runtime use), not the top-level `pkgs.python3Packages`.
|
||||
|
||||
### 2. `alexapy` 1.29.25 (override)
|
||||
|
||||
nixpkgs `alexapy` is fetched from **GitLab** (`keatontaylor/alexapy`, tag
|
||||
`v<version>`), not PyPI. Override just the version + src via
|
||||
`overridePythonAttrs`, reusing the existing build-system and dependency list:
|
||||
|
||||
- `version = "1.29.25"`
|
||||
- `src = fetchFromGitLab { owner = "keatontaylor"; repo = "alexapy"; tag = "v1.29.25"; hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4="; }`
|
||||
|
||||
This is a patch bump (1.29.22 → 1.29.25); the dependency set is expected to be
|
||||
unchanged. Override the HA-Python-set `alexapy` so it shares the interpreter
|
||||
with dictor and the component.
|
||||
|
||||
### 3. `alexa_media_player` component (new `customComponents` entry)
|
||||
|
||||
```
|
||||
buildHomeAssistantComponent {
|
||||
owner = "Alandtse";
|
||||
domain = "alexa_media";
|
||||
version = "5.15.7";
|
||||
src = fetchFromGitHub {
|
||||
owner = "Alandtse";
|
||||
repo = "alexa_media_player";
|
||||
rev = "v5.15.7";
|
||||
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
|
||||
};
|
||||
dependencies = [ alexapy' dictor' wrapt packaging ]; # HA-python-set packages
|
||||
}
|
||||
```
|
||||
|
||||
`dependencies` must make every manifest requirement importable at the required
|
||||
version for `manifestCheckPhase` to pass. Include all four (the two custom ones
|
||||
plus `wrapt` and `packaging` from the HA Python set) to be explicit.
|
||||
|
||||
## Data flow
|
||||
|
||||
1. `nixos-rebuild switch` builds the component; `manifestCheckPhase` validates
|
||||
the four requirements against the provided `dependencies`.
|
||||
2. HA starts; the custom component is present but not configured.
|
||||
3. User adds **Alexa Media Player** in Settings → Devices & Services, signs in
|
||||
with the Amazon account (email/password; 2FA or app-password handled in the
|
||||
UI flow at runtime).
|
||||
4. HA creates media_player entities and per-device sensors; TTS/announce
|
||||
services become available for automations.
|
||||
|
||||
## Error handling / risks
|
||||
|
||||
- **Version-pin drift.** If a future `alexa_media_player` bump changes the
|
||||
`alexapy==` pin, `alexapy` must be re-bumped in lockstep, or the build fails
|
||||
loudly at `manifestCheckPhase` (fail-safe, not silent).
|
||||
- **Amazon login fragility.** The unofficial API can break on Amazon's side
|
||||
(captcha/2FA changes). This is a runtime concern, independent of packaging;
|
||||
not addressed here.
|
||||
- **`dictor` upper bound `<0.2`.** 0.1.12 is the current release and satisfies
|
||||
it. If nixpkgs later gains a `dictor` ≥ 0.2, prefer our pinned 0.1.12 for
|
||||
this component.
|
||||
|
||||
## Verification
|
||||
|
||||
- `nix build '.#nixosConfigurations.jupiter.config.system.build.toplevel'`
|
||||
succeeds — this exercises the build-time manifest-requirements check for all
|
||||
three new/overridden derivations.
|
||||
- `nixfmt-rfc-style` clean on the edited module.
|
||||
- Post-deploy (manual, by the user): the integration appears under Add
|
||||
Integration, and a TTS/announce call reaches an Echo.
|
||||
|
||||
## Pinned artifacts
|
||||
|
||||
| Artifact | Source | Ref / version | Hash |
|
||||
| --------------------------- | ---------- | ------------- | ------------------------------------------------- |
|
||||
| alexa_media_player | GitHub | v5.15.7 | sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI= |
|
||||
| alexapy | GitLab | v1.29.25 | sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4= |
|
||||
| dictor | PyPI sdist | 0.1.12 | sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs= |
|
||||
@@ -20,6 +20,7 @@
|
||||
useOSProber = true;
|
||||
};
|
||||
|
||||
|
||||
# Configure keymap in X11
|
||||
services.xserver.xkb = {
|
||||
layout = "de";
|
||||
@@ -33,6 +34,7 @@
|
||||
services.printing.enable = true;
|
||||
nixpkgs.config.allowUnfree = true;
|
||||
|
||||
|
||||
hardware.nvidia.prime = {
|
||||
sync.enable = false;
|
||||
|
||||
@@ -42,37 +44,6 @@
|
||||
|
||||
services.openssh.enable = true;
|
||||
|
||||
# Don't let boot stall waiting for a network that may never come up
|
||||
# (WiFi credentials live in KWallet and need a desktop session), which
|
||||
# otherwise hangs the terminal boot before the login prompt appears.
|
||||
systemd.services.NetworkManager-wait-online.enable = false;
|
||||
|
||||
# Boot-time choice: the default GRUB entry boots straight into KDE.
|
||||
# A separate "terminal" entry (a NixOS specialisation) boots to a text
|
||||
# console with autologin, where you can work or run `desktop` to bring
|
||||
# KDE up. Pick the entry you want in the GRUB menu at boot.
|
||||
#
|
||||
# NOTE: in terminal mode WiFi will not connect on its own (the password
|
||||
# is stored per-user in KWallet). To reach the machine over SSH from
|
||||
# terminal mode, first save the WiFi as a system connection in KDE:
|
||||
# network settings -> your WiFi -> "All users may connect to this network".
|
||||
specialisation.terminal.configuration = {
|
||||
system.nixos.tags = [ "terminal" ];
|
||||
|
||||
# Boot to a text console. graphical.target is what pulls in the display
|
||||
# manager (via its embedded Wants=display-manager.service), so defaulting
|
||||
# to multi-user.target leaves SDDM installed but not started at boot.
|
||||
systemd.defaultUnit = lib.mkForce "multi-user.target";
|
||||
|
||||
# Guarantee a usable shell on the console (no login prompt to hunt for).
|
||||
services.getty.autologinUser = "finn";
|
||||
|
||||
# Bring the desktop up on demand from the terminal.
|
||||
environment.systemPackages = [
|
||||
(pkgs.writeShellScriptBin "desktop" "exec sudo systemctl start display-manager.service")
|
||||
];
|
||||
};
|
||||
|
||||
# KDE (PowerDevil) power settings: do nothing on lid close while on AC power.
|
||||
# Shipped as a system-wide default; KConfig cascades so a user's own
|
||||
# ~/.config/powerdevilrc will override this if present.
|
||||
|
||||
@@ -9,6 +9,39 @@
|
||||
let
|
||||
cfg = config.my.profiles.home-assistant;
|
||||
hostName = config.networking.hostName;
|
||||
|
||||
# Python deps for the alexa_media_player custom component. Built against
|
||||
# Home Assistant's own interpreter — the same set buildHomeAssistantComponent
|
||||
# uses — so HA's build-time and runtime manifest-requirement checks pass.
|
||||
haPython = pkgs.home-assistant.python3Packages;
|
||||
|
||||
# dictor is not in nixpkgs; alexa_media_player needs dictor>=0.1.12,<0.2.
|
||||
# Pure-Python, no runtime deps, legacy setup.py.
|
||||
dictor = haPython.buildPythonPackage {
|
||||
pname = "dictor";
|
||||
version = "0.1.12";
|
||||
format = "setuptools";
|
||||
src = haPython.fetchPypi {
|
||||
pname = "dictor";
|
||||
version = "0.1.12";
|
||||
hash = "sha256-bbSDda4eU9ye2EToWzj04/v79qTmC+yjd1Fa0URTuRs=";
|
||||
};
|
||||
build-system = [ haPython.setuptools ];
|
||||
doCheck = false;
|
||||
pythonImportsCheck = [ "dictor" ];
|
||||
};
|
||||
|
||||
# nixpkgs ships alexapy 1.29.22; the manifest pins ==1.29.25. Patch bump.
|
||||
# nixpkgs fetches alexapy from GitLab (keatontaylor/alexapy), tag v<version>.
|
||||
alexapy = haPython.alexapy.overridePythonAttrs (old: {
|
||||
version = "1.29.25";
|
||||
src = pkgs.fetchFromGitLab {
|
||||
owner = "keatontaylor";
|
||||
repo = "alexapy";
|
||||
tag = "v1.29.25";
|
||||
hash = "sha256-P/hvgqZVaBJF5dbmHrDjQMC+pwV3EEhKyFIS5KmhgD4=";
|
||||
};
|
||||
});
|
||||
in
|
||||
{
|
||||
|
||||
@@ -23,6 +56,42 @@ in
|
||||
services.home-assistant = {
|
||||
enable = true;
|
||||
openFirewall = true;
|
||||
|
||||
# HACS-style custom components, packaged declaratively (no HACS runtime).
|
||||
# Config-flow based: add via Settings > Devices & Services after rebuild.
|
||||
customComponents = [
|
||||
(pkgs.buildHomeAssistantComponent {
|
||||
owner = "Matts-Baps";
|
||||
domain = "sourdough";
|
||||
version = "1.1.3";
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "Matts-Baps";
|
||||
repo = "ha-sourdough";
|
||||
rev = "v1.1.3";
|
||||
hash = "sha256-Uoid/2f6GxZMuE5Keu2VjHPYuOxnYG8hsCD6BYcaTvM=";
|
||||
};
|
||||
})
|
||||
(pkgs.buildHomeAssistantComponent {
|
||||
owner = "Alandtse";
|
||||
domain = "alexa_media";
|
||||
version = "5.15.7";
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "Alandtse";
|
||||
repo = "alexa_media_player";
|
||||
rev = "v5.15.7";
|
||||
hash = "sha256-1rcZVSX1xA1Lc4qSu39MOitVEciZFhoPQy2y5+PpoAI=";
|
||||
};
|
||||
# Every manifest requirement must be importable at a satisfying
|
||||
# version or manifestCheckPhase fails the build.
|
||||
dependencies = [
|
||||
alexapy
|
||||
dictor
|
||||
haPython.wrapt
|
||||
haPython.packaging
|
||||
];
|
||||
})
|
||||
];
|
||||
|
||||
extraComponents = [
|
||||
"matter"
|
||||
"mobile_app"
|
||||
|
||||
Reference in New Issue
Block a user