smart_plug.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334
  1. from datetime import datetime
  2. from typing import Literal
  3. from pydantic import BaseModel, Field, field_validator, model_validator
  4. from backend.app.schemas.not_null import IgnoresNullForRequiredColumns
  5. from backend.app.services.secret_fields import SECRET_PLACEHOLDER
  6. # A REST plug's URLs and request bodies, shown only to those who may edit plugs.
  7. REST_EDITOR_FIELDS = (
  8. "rest_on_url",
  9. "rest_off_url",
  10. "rest_status_url",
  11. "rest_power_url",
  12. "rest_energy_url",
  13. "rest_on_body",
  14. "rest_off_body",
  15. )
  16. class SmartPlugBase(BaseModel):
  17. name: str = Field(..., min_length=1, max_length=100)
  18. plug_type: Literal["tasmota", "homeassistant", "mqtt", "rest"] = "tasmota"
  19. # Tasmota fields (required when plug_type="tasmota")
  20. ip_address: str | None = Field(default=None, pattern=r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")
  21. username: str | None = None
  22. password: str | None = None
  23. # Home Assistant fields (required when plug_type="homeassistant")
  24. ha_entity_id: str | None = Field(default=None, pattern=r"^(switch|light|input_boolean|script)\.[a-z0-9_]+$")
  25. # Home Assistant energy sensor entities (optional, for separate energy sensors)
  26. ha_power_entity: str | None = Field(default=None, pattern=r"^sensor\.[a-z0-9_]+$")
  27. ha_energy_today_entity: str | None = Field(default=None, pattern=r"^sensor\.[a-z0-9_]+$")
  28. ha_energy_total_entity: str | None = Field(default=None, pattern=r"^sensor\.[a-z0-9_]+$")
  29. # MQTT fields (required when plug_type="mqtt")
  30. # Legacy field - kept for backward compatibility
  31. mqtt_topic: str | None = Field(default=None, max_length=200) # Deprecated, use mqtt_power_topic
  32. # Power monitoring
  33. mqtt_power_topic: str | None = Field(default=None, max_length=200) # Topic for power data
  34. mqtt_power_path: str | None = Field(default=None, max_length=100) # e.g., "power_l1" or "data.power"
  35. mqtt_power_multiplier: float = Field(default=1.0, gt=0, le=10000) # Unit conversion for power
  36. # Energy monitoring
  37. mqtt_energy_topic: str | None = Field(default=None, max_length=200) # Topic for energy data
  38. mqtt_energy_path: str | None = Field(default=None, max_length=100) # e.g., "energy_l1"
  39. mqtt_energy_multiplier: float = Field(default=1.0, gt=0, le=10000) # Unit conversion for energy
  40. # State monitoring
  41. mqtt_state_topic: str | None = Field(default=None, max_length=200) # Topic for state data
  42. mqtt_state_path: str | None = Field(default=None, max_length=100) # e.g., "state_l1" for ON/OFF
  43. mqtt_state_on_value: str | None = Field(
  44. default=None, max_length=50
  45. ) # What value means "ON" (e.g., "ON", "true", "1")
  46. # Legacy multiplier - kept for backward compatibility
  47. mqtt_multiplier: float = Field(default=1.0, gt=0, le=10000) # Deprecated, use mqtt_power_multiplier
  48. # REST/Webhook fields (required when plug_type="rest")
  49. rest_on_url: str | None = Field(default=None, max_length=500)
  50. rest_on_body: str | None = None
  51. rest_off_url: str | None = Field(default=None, max_length=500)
  52. rest_off_body: str | None = None
  53. rest_method: Literal["GET", "POST", "PUT", "PATCH"] | None = None
  54. rest_headers: str | None = None # JSON string of custom headers
  55. rest_status_url: str | None = Field(default=None, max_length=500)
  56. rest_status_path: str | None = Field(default=None, max_length=200)
  57. rest_status_on_value: str | None = Field(default=None, max_length=50)
  58. rest_power_url: str | None = Field(default=None, max_length=500)
  59. rest_power_path: str | None = Field(default=None, max_length=200)
  60. rest_power_multiplier: float = Field(default=1.0, gt=0, le=10000)
  61. rest_energy_url: str | None = Field(default=None, max_length=500)
  62. # Today's usage, resetting at midnight.
  63. rest_energy_path: str | None = Field(default=None, max_length=200)
  64. rest_energy_multiplier: float = Field(default=1.0, gt=0, le=10000)
  65. # Lifetime counter that never resets (#2539) — a Shelly's `aenergy.total`.
  66. rest_energy_total_path: str | None = Field(default=None, max_length=200)
  67. rest_energy_total_multiplier: float = Field(default=1.0, gt=0, le=10000)
  68. printer_id: int | None = None
  69. # #2629: only a plug that really feeds the printer may mark it offline when
  70. # it switches off. Accessory plugs (filter fan, lights) are linked to a
  71. # printer purely to follow the print cycle.
  72. controls_printer_power: bool = True
  73. enabled: bool = True
  74. auto_on: bool = True
  75. auto_off: bool = True
  76. auto_off_persistent: bool = False
  77. off_delay_mode: Literal["time", "temperature"] = "time"
  78. off_delay_minutes: int = Field(default=5, ge=0, le=60)
  79. off_temp_threshold: int = Field(default=70, ge=30, le=150)
  80. # #3464: what temperature mode waits for, and the bed's own threshold.
  81. off_temp_source: Literal["nozzle", "bed"] = "nozzle"
  82. off_bed_temp_threshold: int = Field(default=35, ge=20, le=100)
  83. # #1349: auto-off after AMS drying completes. Independent of `auto_off`
  84. # (print-finish). Fires whenever any AMS on the linked printer finishes
  85. # a dry cycle.
  86. auto_off_after_drying: bool = False
  87. off_delay_after_drying_minutes: int = Field(default=10, ge=0, le=120)
  88. # Power alerts
  89. power_alert_enabled: bool = False
  90. power_alert_high: float | None = Field(default=None, ge=0, le=5000) # Alert when power > this (watts)
  91. power_alert_low: float | None = Field(default=None, ge=0, le=5000) # Alert when power < this (watts)
  92. # Schedule
  93. schedule_enabled: bool = False
  94. schedule_on_time: str | None = Field(default=None, pattern=r"^([01]\d|2[0-3]):[0-5]\d$") # HH:MM format
  95. schedule_off_time: str | None = Field(default=None, pattern=r"^([01]\d|2[0-3]):[0-5]\d$") # HH:MM format
  96. # Visibility options
  97. show_in_switchbar: bool = False
  98. show_on_printer_card: bool = True # For scripts: show on printer card
  99. @model_validator(mode="after")
  100. def validate_plug_type_fields(self) -> "SmartPlugBase":
  101. if self.plug_type == "tasmota" and not self.ip_address:
  102. raise ValueError("ip_address is required for Tasmota plugs")
  103. if self.plug_type == "homeassistant" and not self.ha_entity_id:
  104. raise ValueError("ha_entity_id is required for Home Assistant plugs")
  105. if self.plug_type == "mqtt":
  106. # Determine the effective power topic (new field takes priority, fall back to legacy)
  107. power_topic = self.mqtt_power_topic or self.mqtt_topic
  108. # Path is optional - if not set, raw MQTT payload value will be used
  109. has_power = bool(power_topic)
  110. has_energy = bool(self.mqtt_energy_topic)
  111. has_state = bool(self.mqtt_state_topic)
  112. # At least one data source must be configured (path is optional)
  113. if not has_power and not has_energy and not has_state:
  114. raise ValueError("At least one MQTT topic must be configured for power, energy, or state monitoring")
  115. if self.plug_type == "rest":
  116. if not self.rest_on_url and not self.rest_off_url:
  117. raise ValueError("At least one of ON URL or OFF URL is required for REST plugs")
  118. return self
  119. class SmartPlugCreate(SmartPlugBase):
  120. pass
  121. class SmartPlugUpdate(IgnoresNullForRequiredColumns):
  122. __orm_table__ = "smart_plugs"
  123. name: str | None = None
  124. plug_type: Literal["tasmota", "homeassistant", "mqtt", "rest"] | None = None
  125. ip_address: str | None = None
  126. ha_entity_id: str | None = None
  127. # Home Assistant energy sensor entities (optional)
  128. ha_power_entity: str | None = None
  129. ha_energy_today_entity: str | None = None
  130. ha_energy_total_entity: str | None = None
  131. # MQTT fields (legacy)
  132. mqtt_topic: str | None = None
  133. mqtt_multiplier: float | None = Field(default=None, gt=0, le=10000)
  134. # MQTT power fields
  135. mqtt_power_topic: str | None = None
  136. mqtt_power_path: str | None = None
  137. mqtt_power_multiplier: float | None = Field(default=None, gt=0, le=10000)
  138. # MQTT energy fields
  139. mqtt_energy_topic: str | None = None
  140. mqtt_energy_path: str | None = None
  141. mqtt_energy_multiplier: float | None = Field(default=None, gt=0, le=10000)
  142. # MQTT state fields
  143. mqtt_state_topic: str | None = None
  144. mqtt_state_path: str | None = None
  145. mqtt_state_on_value: str | None = None
  146. # REST fields
  147. rest_on_url: str | None = None
  148. rest_on_body: str | None = None
  149. rest_off_url: str | None = None
  150. rest_off_body: str | None = None
  151. rest_method: Literal["GET", "POST", "PUT", "PATCH"] | None = None
  152. rest_headers: str | None = None
  153. rest_status_url: str | None = None
  154. rest_status_path: str | None = None
  155. rest_status_on_value: str | None = None
  156. rest_power_url: str | None = None
  157. rest_power_path: str | None = None
  158. rest_power_multiplier: float | None = Field(default=None, gt=0, le=10000)
  159. rest_energy_url: str | None = None
  160. rest_energy_path: str | None = None
  161. rest_energy_multiplier: float | None = Field(default=None, gt=0, le=10000)
  162. rest_energy_total_path: str | None = None
  163. rest_energy_total_multiplier: float | None = Field(default=None, gt=0, le=10000)
  164. printer_id: int | None = None
  165. # #2629: see SmartPlugBase.controls_printer_power.
  166. controls_printer_power: bool | None = None
  167. enabled: bool | None = None
  168. auto_on: bool | None = None
  169. auto_off: bool | None = None
  170. auto_off_persistent: bool | None = None
  171. off_delay_mode: Literal["time", "temperature"] | None = None
  172. off_delay_minutes: int | None = Field(default=None, ge=0, le=60)
  173. off_temp_threshold: int | None = Field(default=None, ge=30, le=150)
  174. # #3464: see SmartPlugBase.off_temp_source.
  175. off_temp_source: Literal["nozzle", "bed"] | None = None
  176. off_bed_temp_threshold: int | None = Field(default=None, ge=20, le=100)
  177. # #1349: per-plug drying auto-off.
  178. auto_off_after_drying: bool | None = None
  179. off_delay_after_drying_minutes: int | None = Field(default=None, ge=0, le=120)
  180. username: str | None = None
  181. password: str | None = None
  182. # Power alerts
  183. power_alert_enabled: bool | None = None
  184. power_alert_high: float | None = Field(default=None, ge=0, le=5000)
  185. power_alert_low: float | None = Field(default=None, ge=0, le=5000)
  186. # Schedule
  187. schedule_enabled: bool | None = None
  188. schedule_on_time: str | None = Field(default=None, pattern=r"^([01]\d|2[0-3]):[0-5]\d$")
  189. schedule_off_time: str | None = Field(default=None, pattern=r"^([01]\d|2[0-3]):[0-5]\d$")
  190. # Visibility options
  191. show_in_switchbar: bool | None = None
  192. show_on_printer_card: bool | None = None
  193. class SmartPlugResponse(SmartPlugBase):
  194. id: int
  195. last_state: str | None = None
  196. last_checked: datetime | None = None
  197. auto_off_executed: bool = False # True when auto-off was triggered after print
  198. power_alert_last_triggered: datetime | None = None
  199. created_at: datetime
  200. updated_at: datetime
  201. class Config:
  202. from_attributes = True
  203. @field_validator("password", "rest_headers", mode="after")
  204. @classmethod
  205. def _write_only(cls, value: str | None) -> str | None:
  206. """Secrets are write-only: a set one is shown as the placeholder."""
  207. return SECRET_PLACEHOLDER if value else value
  208. @model_validator(mode="after")
  209. def _rest_for_editors(self) -> "SmartPlugResponse":
  210. """Readers get no REST URLs or bodies: they commonly carry the device's
  211. credential, and a plug is switched and polled by its id. After the
  212. base checks, which need them."""
  213. for field in REST_EDITOR_FIELDS:
  214. setattr(self, field, None)
  215. return self
  216. class SmartPlugResponseWithSecret(SmartPlugResponse):
  217. """SmartPlugResponse with the REST URLs and bodies. Returned only to callers
  218. who may edit plugs (or with authentication off)."""
  219. @model_validator(mode="after")
  220. def _rest_for_editors(self) -> "SmartPlugResponseWithSecret":
  221. """Editors keep them, to edit them."""
  222. return self
  223. class SmartPlugControl(BaseModel):
  224. action: Literal["on", "off", "toggle"]
  225. class SmartPlugEnergy(BaseModel):
  226. """Energy monitoring data from a smart plug."""
  227. power: float | None = None # Current watts
  228. voltage: float | None = None # Volts
  229. current: float | None = None # Amps
  230. today: float | None = None # kWh used today
  231. yesterday: float | None = None # kWh used yesterday
  232. total: float | None = None # Total kWh
  233. factor: float | None = None # Power factor (0-1)
  234. apparent_power: float | None = None # VA
  235. reactive_power: float | None = None # VAr
  236. class SmartPlugStatus(BaseModel):
  237. state: str | None = None # "ON", "OFF", or None if unreachable
  238. reachable: bool = True
  239. device_name: str | None = None
  240. energy: SmartPlugEnergy | None = None # Energy data if available
  241. class SmartPlugTestConnection(BaseModel):
  242. ip_address: str = Field(..., pattern=r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$")
  243. username: str | None = None
  244. password: str | None = None
  245. # The saved plug being edited: its stored password fills in the placeholder.
  246. plug_id: int | None = None
  247. # Home Assistant schemas
  248. class HATestConnectionRequest(BaseModel):
  249. """Request to test Home Assistant connection."""
  250. url: str = Field(..., min_length=1)
  251. token: str = Field(..., min_length=1)
  252. class HATestConnectionResponse(BaseModel):
  253. """Response from HA connection test."""
  254. success: bool
  255. message: str | None = None
  256. error: str | None = None
  257. class HAEntity(BaseModel):
  258. """A Home Assistant entity that can be used as a smart plug."""
  259. entity_id: str
  260. friendly_name: str
  261. state: str | None = None
  262. domain: str # "switch", "light", "input_boolean", "script"
  263. class HASensorEntity(BaseModel):
  264. """A Home Assistant sensor entity for energy monitoring."""
  265. entity_id: str
  266. friendly_name: str
  267. state: str | None = None
  268. unit_of_measurement: str | None = None # "W", "kW", "kWh", "Wh"
  269. class RESTTestConnectionRequest(BaseModel):
  270. """Request to test a REST smart plug connection."""
  271. url: str = Field(..., min_length=1)
  272. method: str = Field(default="GET")
  273. headers: str | None = None # JSON string of custom headers
  274. # The saved plug being edited: its stored headers fill in the placeholder.
  275. plug_id: int | None = None
  276. class RESTTestConnectionResponse(BaseModel):
  277. """Response from REST connection test."""
  278. success: bool
  279. error: str | None = None