Skip to content

Better support for NanoKVM Pro#15

Open
puddly wants to merge 6 commits intodevfrom
puddly/nanokvm-pro
Open

Better support for NanoKVM Pro#15
puddly wants to merge 6 commits intodevfrom
puddly/nanokvm-pro

Conversation

@puddly
Copy link
Copy Markdown
Owner

@puddly puddly commented Mar 21, 2026

This PR was lovingly hand-crafted by CC, I don't own the Pro hardware and have no way to runtime test this change. Unfortunately, it looks like the Pro has its own independent API that has starting diverging from the non-Pro variant.

I've condensed the Home Assistant-relevant breaking changes below:

  • get_virtual_device_status() returns GetVirtualDeviceRsp | GetVirtualDeviceProRsp - caller must check type
  • get_hdmi_state(), reset_hdmi(), enable_hdmi(), disable_hdmi() raise NanoKVMNotSupportedError on Pro
  • get_swap_size(), set_swap_size(), enable_swap(), disable_swap() raise NanoKVMNotSupportedError on Pro
  • get_memory_limit(), set_memory_limit() raise NanoKVMNotSupportedError on Pro
  • get_cdrom_status() raises NanoKVMNotSupportedError on Pro
  • update_virtual_device() returns None instead of UpdateVirtualDeviceRsp; accepts new disk_type kwarg for Pro

And the expected HA integration breaks:

  • Skip get_hdmi_state() on Pro (or wrap with NanoKVMNotSupportedError catch)
  • Skip get_swap_size() on Pro
  • Store client.is_pro for entity-level branching
  • Skip get_cdrom_status() on Pro — read mounted_image.cdrom and mounted_image.read_only instead
  • Virtual Network: on Pro, read virtual_device_info.is_network_enabled instead of .network
  • Virtual Disk: on Pro, read virtual_device_info.mounted_disk != "" instead of .disk; pass disk_type to update_virtual_device()
  • HDMI Output: already gated on HWVersion.PCIE, no change needed
  • Swap Size: don't create on Pro (client.is_pro guard)
  • CD-ROM Mode: on Pro, read mounted_image.cdrom instead of separate cdrom_status; or don't create and rely on GetMountedImageRsp fields
  • reset_hdmi: guard with is_pro check or let it raise and surface as HomeAssistantError

Related issue: Wouter0100/homeassistant-nanokvm#66

Normalize `/storage/image` responses where `data.files` is `null` instead of a list.

On a real NanoKVM Pro (app 1.2.14 / image v1.0.14), the endpoint can return:

{"code":0,"msg":"success","data":{"files":null}}

That caused `GetImagesRsp` validation to fail with `NanoKVMInvalidResponseError`.
This change coerces `files=None` to `[]` while keeping the public Python type as `list[str]`.
@chiconws
Copy link
Copy Markdown
Collaborator

I tested this branch against a real NanoKVM Pro (application 1.2.14, image v1.0.14) and the only immediate pre-merge client issue I found was the /storage/image response shape, where the device can return data.files = null. That caused GetImagesRsp validation to fail, so I pushed a small fix to normalize that case.

Other than that, the Pro support in this PR behaved as intended on real hardware. The shared/Pro reads, the reversible Pro setters I exercised, MJPEG, and the WebSocket mouse helpers all worked correctly, and the non-Pro-only methods correctly reported NanoKVMNotSupportedError on Pro hardware. I did also see a few device-side API -1 responses on my firmware (/vm/web-title, /vm/edid/custom, /vm/menubar), but those appear to be firmware/API behavior rather than client bugs in this PR.

From my testing, the files = null handling was the only blocking change needed before merge.

Of course, we can add support for additional API endpoints later, but for now this should be sufficient.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants