GuideVault Home Assistant Integration

v0.6.4

This release repairs the reader-control state path that caused the sensor, select, and number entities to appear unavailable while command buttons still worked.

Changes

• Keeps Page, Zoom, Background, Display Mode, and Background Brightness available when GuideVault is reachable but its status endpoint rejects polling.
• Applies successful commands optimistically so Page, Zoom, Display Mode, Background, Brightness, Fullscreen, and reader state update immediately in Home Assistant.
• Reads the current GuideVault 1.3.1 nested reader status payload and its background catalog.
• Maps friendly background labels to GuideVault's actual background filenames.
• Rejects false-positive connection tests caused by HTTP 401, 403, or 404 responses.
• Loads control platforms before diagnostic sensors.
• Adds examples/guidevault-controls-card.yaml with the requested control order.
• Includes patches/GuideVault-1.3.1-home-assistant-status-token.patch for authenticated live reader polling.

Why the buttons worked while state was unavailable

The command buttons use:

POST /api/home-assistant/command

GuideVault accepts the command token on that route. GuideVault 1.3.1 currently places this status route behind its browser-session middleware:

GET /api/home-assistant/status

Home Assistant has the command token, not the GuideVault browser cookie, so polling receives HTTP 401. The integration can remain usable with cached and optimistic state, but accurate state changes made directly in the GuideVault browser require the bundled server patch.

Install the Home Assistant integration

Copy:

custom_components/guidevault

to:

/config/custom_components/guidevault

Restart Home Assistant, then add or reload:

Settings > Devices & services > GuideVault

Use the GuideVault Command Token in the field labeled GuideVault command token.

Apply the GuideVault 1.3.1 live-status patch

From the root of the GuideVault source repository:

git apply --check "C:\Path\To\GuideVault-HomeAssistant-Integration\patches\GuideVault-1.3.1-home-assistant-status-token.patch"
git apply "C:\Path\To\GuideVault-HomeAssistant-Integration\patches\GuideVault-1.3.1-home-assistant-status-token.patch"
dotnet build .\src\Guidevault.Web\Guidevault.Web.csproj

The patch does two things:

1. Allows GET /api/home-assistant/status through the browser-session middleware.
2. Requires the existing GuideVault command token at the endpoint and removes the token from the returned status object.

After deploying the patched GuideVault build, this PowerShell check should return live JSON:

$GuideVaultUrl = "http://YOUR-GUIDEVAULT-HOST:5478"
$CommandToken = "YOUR-GUIDEVAULT-COMMAND-TOKEN"

Invoke-RestMethod `
    -Uri "$GuideVaultUrl/api/home-assistant/status" `
    -Headers @{ Authorization = "Bearer $CommandToken" }

Requested control order

Use:

examples/guidevault-controls-card.yaml

It lists:

1. Background
2. Display Mode
3. Page
4. Zoom
5. First Page
6. Last Page
7. Next Page
8. Previous Page
9. Focus Fullscreen
10. Toggle Overlay
11. Zoom In
12. Zoom Out
13. Close Reader
14. Background Brightness

Home Assistant does not provide integrations with a cross-domain sort property for the native device page, so its UI may regroup selects, numbers, and buttons. The bundled dashboard card is the reliable way to preserve the exact order.

Existing installations may retain button.guidevault_fullscreen as the entity ID after its displayed name changes to Focus Fullscreen. Replace that one line in the example card when necessary.

Status entities

The integration exposes:

• Currently reading
• Reader state
• Content type
• Page
• Page count
• Zoom
• Display mode
• Background
• Background brightness
• Fullscreen
• Version

The Currently reading entity includes diagnostic attributes:

• live_status_available
• status_source
• status_error
• status_endpoint

When status_source is live, values came from GuideVault. When it is cached_fallback or optimistic, the server is reachable but live status polling still needs correction.

Reader controls

The integration creates:

• Background select
• Display Mode select
• Page number
• Zoom number
• Background Brightness slider
• First Page
• Last Page
• Next Page
• Previous Page
• Focus Fullscreen
• Toggle Overlay
• Zoom In
• Zoom Out
• Close Reader

Services/actions

Examples:

action: guidevault.next_page

action: guidevault.go_to_page
data:
  page: 12

action: guidevault.set_zoom
data:
  zoom: 125

action: guidevault.set_display_mode
data:
  display_mode: "2 page"

action: guidevault.set_background
data:
  background: "librarydesk.png"

action: guidevault.set_background_brightness
data:
  background_brightness: 72

HACS

The repository remains HACS-compatible. Add it as a custom repository of type Integration when it is not already installed.