M8-T06: add meter source management API

This commit is contained in:
2026-08-23 21:22:05 +02:00
parent 1ea2f659e0
commit 5855fff451
10 changed files with 3857 additions and 8 deletions
+1372
View File
File diff suppressed because it is too large Load Diff
+875
View File
@@ -1211,6 +1211,398 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/source-profiles:
get:
tags:
- api-energy-meter-sources
summary: Source Profiles
description: Return profile metadata; default secrets are never populated with
stored values.
operationId: source_profiles_api_energy_source_profiles_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SourceProfilesResponse'
/api/energy/commodities:
get:
tags:
- api-energy-meter-sources
summary: Commodities
operationId: commodities_api_energy_commodities_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CommoditiesResponse'
/api/energy/sources:
get:
tags:
- api-energy-meter-sources
summary: Get Sources
operationId: get_sources_api_energy_sources_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceListResponse'
post:
tags:
- api-energy-meter-sources
summary: Post Source
operationId: post_source_api_energy_sources_post
parameters:
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/sources/{source_uuid}:
get:
tags:
- api-energy-meter-sources
summary: Get Source Detail
operationId: get_source_detail_api_energy_sources__source_uuid__get
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- api-energy-meter-sources
summary: Patch Source
operationId: patch_source_api_energy_sources__source_uuid__patch
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourcePatch'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- api-energy-meter-sources
summary: Remove Source
operationId: remove_source_api_energy_sources__source_uuid__delete
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/sources/{source_uuid}/discover:
post:
tags:
- api-energy-meter-sources
summary: Discover Source
operationId: discover_source_api_energy_sources__source_uuid__discover_post
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DiscoverResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/sources/{source_uuid}/channels:
get:
tags:
- api-energy-meter-sources
summary: Source Channels
operationId: source_channels_api_energy_sources__source_uuid__channels_get
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MeterSourceChannelListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/sources/{source_uuid}/channels/{channel_uuid}/readings:
get:
tags:
- api-energy-meter-sources
summary: Channel Readings
operationId: channel_readings_api_energy_sources__source_uuid__channels__channel_uuid__readings_get
parameters:
- name: source_uuid
in: path
required: true
schema:
type: string
title: Source Uuid
- name: channel_uuid
in: path
required: true
schema:
type: string
title: Channel Uuid
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
default: 100
title: Limit
- name: start
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Start
- name: end
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: End
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChannelReadingsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/meters/{meter_id}/bindings:
get:
tags:
- api-energy-meter-sources
summary: Meter Bindings
operationId: meter_bindings_api_energy_meters__meter_id__bindings_get
parameters:
- name: meter_id
in: path
required: true
schema:
type: integer
title: Meter Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BindingListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- api-energy-meter-sources
summary: Post Meter Binding
operationId: post_meter_binding_api_energy_meters__meter_id__bindings_post
parameters:
- name: meter_id
in: path
required: true
schema:
type: integer
title: Meter Id
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BindingCreate'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BindingResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/energy/bindings/{binding_uuid}:
patch:
tags:
- api-energy-meter-sources
summary: Patch Binding
operationId: patch_binding_api_energy_bindings__binding_uuid__patch
parameters:
- name: binding_uuid
in: path
required: true
schema:
type: string
title: Binding Uuid
- name: X-CSRF-Token
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Csrf-Token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BindingPatch'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BindingResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/expose:
get:
tags:
@@ -2096,6 +2488,102 @@ paths:
schema: {}
components:
schemas:
BindingCreate:
properties:
source_channel_uuid:
type: string
maxLength: 36
minLength: 1
title: Source Channel Uuid
started_at:
type: string
format: date-time
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
type: object
required:
- source_channel_uuid
- started_at
title: BindingCreate
BindingListResponse:
properties:
items:
items:
$ref: '#/components/schemas/BindingResponse'
type: array
title: Items
total:
type: integer
title: Total
type: object
required:
- items
- total
title: BindingListResponse
BindingPatch:
properties:
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
type: object
title: BindingPatch
BindingResponse:
properties:
uuid:
type: string
title: Uuid
meter_id:
type: integer
title: Meter Id
source_channel_uuid:
type: string
title: Source Channel Uuid
source_uuid:
type: string
title: Source Uuid
started_at:
type: string
format: date-time
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- uuid
- meter_id
- source_channel_uuid
- source_uuid
- started_at
- ended_at
- created_at
- updated_at
title: BindingResponse
CatalogEntrySchema:
properties:
entity:
@@ -2109,6 +2597,72 @@ components:
- enabled
title: CatalogEntrySchema
description: An entity from the catalog with its current toggle state.
ChannelReadingResponse:
properties:
recorded_at:
type: string
format: date-time
title: Recorded At
value:
anyOf:
- type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- type: 'null'
title: Value
quality:
anyOf:
- type: string
- type: 'null'
title: Quality
type: object
required:
- recorded_at
title: ChannelReadingResponse
ChannelReadingsResponse:
properties:
items:
items:
$ref: '#/components/schemas/ChannelReadingResponse'
type: array
title: Items
total:
type: integer
title: Total
type: object
required:
- items
- total
title: ChannelReadingsResponse
CommoditiesResponse:
properties:
items:
items:
$ref: '#/components/schemas/CommodityResponse'
type: array
title: Items
type: object
required:
- items
title: CommoditiesResponse
CommodityResponse:
properties:
key:
type: string
title: Key
unit:
type: string
title: Unit
capabilities:
items:
type: string
type: array
title: Capabilities
type: object
required:
- key
- unit
- capabilities
title: CommodityResponse
ConfigField:
properties:
env_name:
@@ -2496,6 +3050,28 @@ components:
- name
title: DeviceInfoSchema
description: HA device grouping info for an exposable entity.
DiscoverResponse:
properties:
requested:
type: boolean
title: Requested
supported:
type: boolean
title: Supported
status:
type: string
title: Status
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
required:
- requested
- supported
- status
title: DiscoverResponse
DsmrLatestResponse:
properties:
found:
@@ -2736,6 +3312,36 @@ components:
Prices are the *effective* buy prices as used by the billing engine
(energy_buy_x + energy_tax + ode) and the raw sell prices.'
MeterBindingSummary:
properties:
uuid:
type: string
title: Uuid
source_channel_uuid:
type: string
title: Source Channel Uuid
source_uuid:
type: string
title: Source Uuid
started_at:
type: string
format: date-time
title: Started At
ended_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Ended At
type: object
required:
- uuid
- source_channel_uuid
- source_uuid
- started_at
- ended_at
title: MeterBindingSummary
description: Stable, non-sensitive binding identity embedded in meter responses.
MeterDeclareRequest:
properties:
label:
@@ -2766,6 +3372,15 @@ components:
title: Commodity
description: Energy commodity this meter measures. Defaults to 'electricity'.
default: electricity
source_channel_uuid:
anyOf:
- type: string
maxLength: 36
minLength: 1
- type: 'null'
title: Source Channel Uuid
description: Optional compatible source channel to bind atomically to this
meter.
type: object
required:
- label
@@ -2897,6 +3512,11 @@ components:
type: string
format: date-time
title: Created At
bindings:
items:
$ref: '#/components/schemas/MeterBindingSummary'
type: array
title: Bindings
type: object
required:
- id
@@ -2912,6 +3532,195 @@ components:
``ended_at`` is ``null`` for the currently active meter.'
MeterSourceChannelListResponse:
properties:
items:
items:
$ref: '#/components/schemas/MeterSourceChannelResponse'
type: array
title: Items
total:
type: integer
title: Total
type: object
required:
- items
- total
title: MeterSourceChannelListResponse
MeterSourceChannelResponse:
properties:
uuid:
type: string
title: Uuid
label:
type: string
title: Label
suggested_commodity:
anyOf:
- type: string
- type: 'null'
title: Suggested Commodity
unit:
type: string
title: Unit
device_type:
anyOf:
- type: string
- type: 'null'
title: Device Type
latest_value:
anyOf:
- type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- type: 'null'
title: Latest Value
latest_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Latest At
latest_quality:
anyOf:
- type: string
- type: 'null'
title: Latest Quality
binding_count:
type: integer
title: Binding Count
bound_meter_ids:
items:
type: integer
type: array
title: Bound Meter Ids
type: object
required:
- uuid
- label
- suggested_commodity
- unit
- device_type
- latest_value
- latest_at
- latest_quality
- binding_count
- bound_meter_ids
title: MeterSourceChannelResponse
MeterSourceCreate:
properties:
name:
type: string
maxLength: 255
minLength: 1
title: Name
kind:
type: string
maxLength: 64
minLength: 1
title: Kind
config:
additionalProperties: true
type: object
title: Config
enabled:
type: boolean
title: Enabled
default: true
type: object
required:
- name
- kind
title: MeterSourceCreate
MeterSourceListResponse:
properties:
items:
items:
$ref: '#/components/schemas/MeterSourceResponse'
type: array
title: Items
total:
type: integer
title: Total
type: object
required:
- items
- total
title: MeterSourceListResponse
MeterSourcePatch:
properties:
name:
anyOf:
- type: string
maxLength: 255
minLength: 1
- type: 'null'
title: Name
config:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Config
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
type: object
title: MeterSourcePatch
MeterSourceResponse:
properties:
uuid:
type: string
title: Uuid
name:
type: string
title: Name
kind:
type: string
title: Kind
enabled:
type: boolean
title: Enabled
config:
additionalProperties: true
type: object
title: Config
status:
type: string
title: Status
last_seen_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Seen At
last_error:
anyOf:
- type: string
- type: 'null'
title: Last Error
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- uuid
- name
- kind
- enabled
- config
- status
- last_seen_at
- last_error
- created_at
- updated_at
title: MeterSourceResponse
MetricInfo:
properties:
key:
@@ -3649,6 +4458,72 @@ components:
- message
title: SmtpTestResponse
description: Response from POST /api/config/smtp/test.
SourceConfigFieldResponse:
properties:
name:
type: string
title: Name
value_type:
type: string
title: Value Type
default:
title: Default
required:
type: boolean
title: Required
secret:
type: boolean
title: Secret
type: object
required:
- name
- value_type
- required
- secret
title: SourceConfigFieldResponse
SourceProfileResponse:
properties:
kind:
type: string
title: Kind
fields:
items:
$ref: '#/components/schemas/SourceConfigFieldResponse'
type: array
title: Fields
defaults:
additionalProperties: true
type: object
title: Defaults
capabilities:
items:
type: string
type: array
title: Capabilities
allowed_units:
items:
type: string
type: array
title: Allowed Units
type: object
required:
- kind
- fields
- defaults
- capabilities
- allowed_units
title: SourceProfileResponse
SourceProfilesResponse:
properties:
items:
items:
$ref: '#/components/schemas/SourceProfileResponse'
type: array
title: Items
type: object
required:
- items
title: SourceProfilesResponse
StatusResponse:
properties:
status: