From 2921fade58e8e3ece8c9ba89118c0d72ea3c0fa1 Mon Sep 17 00:00:00 2001 From: Mike Degatano Date: Wed, 23 Jul 2025 16:55:18 -0400 Subject: [PATCH 1/3] Document nvme device status APIs --- docs/api/supervisor/endpoints.md | 48 +++++++++++++++++++++++++++++++- docs/api/supervisor/models.md | 7 +++++ 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index 19d93a20386..ba36eb718e6 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -1693,6 +1693,7 @@ Return information about the host. | llmnr_hostname | string or null | The hostname currently exposed on the network via LLMNR for host | | operating_system | string | The operating system on the host | | startup_time | float | The time in seconds it took for last boot | +| nvme_devices | list | A list of [NVMe devices](api/supervisor/models.md#nvme-device) available on host | **Example response:** @@ -1714,7 +1715,13 @@ Return information about the host. "boot_timestamp": 1234567788, "startup_time": 12.345, "broadcast_llmnr": true, - "broadcast_mdns": false + "broadcast_mdns": false, + "nvme_devices": [ + { + "id": "00000000-0000-0000-0000-000000000000", + "path": "/dev/nvme0n1" + } + ] } ``` @@ -1906,6 +1913,45 @@ Shutdown the host + + +Returns the status and lifetime information of the specified NVMe device. +See `nvme_devices` field in `/host/info` for a list of devices. This API supports +providing either the `id` or `path` as the identifier for an NVMe device. + +**Returned data:** + +| key | type | description | +| ------------------------------- | ---- | ------------------------------------------------------------------------------------------- | +| critical_warning | int | Critical warnings raised over device lifetime | +| available_spare | int | Percentage of remaining spare capacity available | +| data_units_read | int | Thousands of 512 byte data units read by host over device lifetime | +| data_units_written | int | Thousands of 512 byte data units written by host over device lifetime | +| percent_used | int | Estimate of percent of device's life used based on manufacturer's prediction | +| temperature_kelvin | int | Current temperature in Kelvins calculated from sensors | +| host_read_commands | int | Read commands completed over device lifetime | +| host_write_commands | int | Write commands completed over device lifetime | +| controller_busy_minutes | int | Minutes the device was busy with I/O commands over device lifetime | +| power_cycles | int | Power cycles over device lifetime | +| power_on_hours | int | Power-on hours over device lifetime | +| unsafe_shutdowns | int | Unsafe shutdowns over device lifetime | +| media_errors | int | Data integrity errors detected over device lifetime | +| number_error_log_entries | int | Error entries in log over device lifetime | +| warning_temp_minutes | int | Minutes temperature has been greater then warning threshold over device lifetime | +| critical_composite_temp_minutes | int | Minutes temperature has been greater then critical composite threshold over device lifetime | + + + + + +Returns the status and lifetime information of the datadisk if the datadisk is +an NVMe device and Home Assistant Operating System is in use. + +**Returned data:** +See `/host/nvme//status` above, response is identical. + + + ### Ingress diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md index cb00f0dd928..8632e1681d6 100644 --- a/docs/api/supervisor/models.md +++ b/docs/api/supervisor/models.md @@ -355,3 +355,10 @@ Response only fields will be in responses but cannot be included in requests. | name | string | Name of the filesystem (if known) | | system | boolean | `true` if filesystem considered a system/internal device | | mount_points | list | List of paths where the filesystem is mounted. | + +## NVMe Device + +| key | type | description | +| ---- | ------- | ------------------------------------------------ | +| id | string | Unique UUID for the device | +| path | string | Device path on host system (e.g. `/dev/nvme0n1`) | From fa49da0ecef55b64c31ed53c4e20f77ce3617063 Mon Sep 17 00:00:00 2001 From: Mike Degatano Date: Thu, 24 Jul 2025 12:10:42 -0400 Subject: [PATCH 2/3] Add placeholder and fix other missing ones --- docs/api/supervisor/endpoints.md | 37 +++++++++++++++++++------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index ba36eb718e6..c3104805dab 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -2235,7 +2235,7 @@ Value in `name` must be unique and can only consist of letters, numbers and unde - + Update an existing mount in Supervisor and remount it **Payload:** @@ -2259,12 +2259,12 @@ name, it cannot be changed. Delete and re-add the mount to change the name. - + Unmount and delete an existing mount from Supervisor. - + Unmount and remount an existing mount in Supervisor using the same configuration. @@ -2485,7 +2485,7 @@ Return a list of available [Access Points](api/supervisor/models.md#access-point - + Create a new VLAN *id* on this network interface. @@ -2931,7 +2931,7 @@ Execute a healthcheck and autofix & notifcation. - + Set options for this check. @@ -2943,7 +2943,7 @@ Set options for this check. - + Execute a specific check right now. @@ -3524,13 +3524,20 @@ Update the supervisor Some of the endpoints uses placeholders indicated with `<...>` in the endpoint URL. -| placeholder | description | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| addon | The slug for the addon, to get the slug you can call `/addons`, to call endpoints for the add-on calling the endpoints you can use `self`as the slug. | +| placeholder | description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| addon | The slug for the addon, to get the slug you can call `/addons`, to call endpoints for the add-on calling the endpoints you can use `self` as the slug. | | application | The name of an application, call `/audio/info` to get the correct name | -| interface | A valid interface name, example `eth0`, to get the interface name you can call `/network/info`. You can use `default` to get the primary interface | -| registry | A registry hostname defined in the container registry configuration, to get the hostname you can call `/docker/registries` | -| service | The service name for a service on the host. | -| backup | A valid backup slug, example `skuwe823`, to get the slug you can call `/backups` | -| suggestion | A valid suggestion, example `clear_full_backup`, to get the suggestion you can call `/resolution` | -| uuid | The UUID of a discovery service, to get the UUID you can call `/discovery` | +| backup | A valid backup slug, example `skuwe823`, to get the slug you can call `/backups` | +| bootid | An identifier for a specific boot of host system or an integer offset from the current boot. See `/host/logs/boots/` for more details | +| check | The slug for a check in Supervisor's resolution manager, call `/resolution/info` to see the list of options in the `checks` field | +| device | A UUID or device path for an NVMe device available on the host, call `/host/info` to get a list of options in the `nvme_devices` field | +| identifier | A syslog identifier from systemd journal, call `/host/logs/identifiers` to get a complete list of options | +| interface | A valid interface name, example `eth0`, to get the interface name you can call `/network/info`. You can use `default` to get the primary interface | +| mount | Name of a mount that exists in Supervisor, call `/mounts` to get a list of options | +| registry | A registry hostname defined in the container registry configuration, to get the hostname you can call `/docker/registries` | +| respository | The slug for a respository in Supervisor's add-on store, call `/store/repositories` to get a list of options | +| service | The service name for a service on the host, call `/host/services` to get a list of options | +| suggestion | A valid suggestion, example `clear_full_backup`, to get the suggestion you can call `/resolution` | +| uuid | The UUID of a discovery service, to get the UUID you can call `/discovery` | +| vlan | The id for a vlan network device in network manager on the host. Should be an integer | From 199d34eecfcd307dd0de346f500d90a20a1f9b25 Mon Sep 17 00:00:00 2001 From: Mike Degatano Date: Thu, 24 Jul 2025 12:18:59 -0400 Subject: [PATCH 3/3] Fixes from coderabbits nitpick suggestions --- docs/api/supervisor/endpoints.md | 59 ++++++++++++++++++++++---------- docs/api/supervisor/models.md | 8 ++--- 2 files changed, 45 insertions(+), 22 deletions(-) diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md index c3104805dab..cba442012f6 100644 --- a/docs/api/supervisor/endpoints.md +++ b/docs/api/supervisor/endpoints.md @@ -1921,24 +1921,47 @@ providing either the `id` or `path` as the identifier for an NVMe device. **Returned data:** -| key | type | description | -| ------------------------------- | ---- | ------------------------------------------------------------------------------------------- | -| critical_warning | int | Critical warnings raised over device lifetime | -| available_spare | int | Percentage of remaining spare capacity available | -| data_units_read | int | Thousands of 512 byte data units read by host over device lifetime | -| data_units_written | int | Thousands of 512 byte data units written by host over device lifetime | -| percent_used | int | Estimate of percent of device's life used based on manufacturer's prediction | -| temperature_kelvin | int | Current temperature in Kelvins calculated from sensors | -| host_read_commands | int | Read commands completed over device lifetime | -| host_write_commands | int | Write commands completed over device lifetime | -| controller_busy_minutes | int | Minutes the device was busy with I/O commands over device lifetime | -| power_cycles | int | Power cycles over device lifetime | -| power_on_hours | int | Power-on hours over device lifetime | -| unsafe_shutdowns | int | Unsafe shutdowns over device lifetime | -| media_errors | int | Data integrity errors detected over device lifetime | -| number_error_log_entries | int | Error entries in log over device lifetime | -| warning_temp_minutes | int | Minutes temperature has been greater then warning threshold over device lifetime | -| critical_composite_temp_minutes | int | Minutes temperature has been greater then critical composite threshold over device lifetime | +| key | type | description | +| ------------------------------- | ---- | ----------------------------------------------------------------------------------------------- | +| critical_warning | int | Critical warnings raised over device lifetime | +| available_spare | int | Percentage of remaining spare capacity available | +| data_units_read | int | Thousands of 512 byte data units read by host over device lifetime | +| data_units_written | int | Thousands of 512 byte data units written by host over device lifetime | +| percent_used | int | Estimate of percent of device's life used based on manufacturer's prediction | +| temperature_kelvin | int | Current temperature in Kelvin calculated from sensors | +| host_read_commands | int | Read commands completed over device lifetime | +| host_write_commands | int | Write commands completed over device lifetime | +| controller_busy_minutes | int | Minutes the device was busy with I/O commands over device lifetime | +| power_cycles | int | Power cycles over device lifetime | +| power_on_hours | int | Power-on hours over device lifetime | +| unsafe_shutdowns | int | Unsafe shutdowns over device lifetime | +| media_errors | int | Data integrity errors detected over device lifetime | +| number_error_log_entries | int | Error entries in log over device lifetime | +| warning_temp_minutes | int | Minutes temperature has been greater than the warning threshold over device lifetime | +| critical_composite_temp_minutes | int | Minutes temperature has been greater than the critical composite threshold over device lifetime | + +**Example response:** + +```json +{ + "available_spare": 100, + "critical_warning": 0, + "data_units_read": 44707691, + "data_units_written": 54117388, + "percent_used": 1, + "temperature_kelvin": 312, + "host_read_commands": 428871098, + "host_write_commands": 900245782, + "controller_busy_minutes": 2678, + "power_cycles": 652, + "power_on_hours": 3192, + "unsafe_shutdowns": 107, + "media_errors": 0, + "number_error_log_entries": 1069, + "warning_temp_minutes": 0, + "critical_composite_temp_minutes": 0 +} +``` diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md index 8632e1681d6..61c27d4c598 100644 --- a/docs/api/supervisor/models.md +++ b/docs/api/supervisor/models.md @@ -358,7 +358,7 @@ Response only fields will be in responses but cannot be included in requests. ## NVMe Device -| key | type | description | -| ---- | ------- | ------------------------------------------------ | -| id | string | Unique UUID for the device | -| path | string | Device path on host system (e.g. `/dev/nvme0n1`) | +| key | type | description | +| ---- | ------- | ---------------------------------------------------- | +| id | string | UUID (unique identifier) for the device | +| path | string | Device path on the host system (e.g. `/dev/nvme0n1`) |