use core::cell::{Cell, RefCell};
use crate::clusters::generated::device_energy_management as spec_dem;
use crate::dm::spec::{Conforming, Optional};
use crate::dm::{Resolved, ResolvedCommand};
use crate::im::{ClusterHandler, ClusterId, CommandId, InteractionContext, Status, StatusIb};
use crate::platform::{Duration, Instant};
use crate::tlv::{Tag, TlvList, TlvWriter, ToTlv};
use super::Cluster;
pub use spec_dem::attribute::{
ABS_MAX_POWER, ABS_MIN_POWER, ESA_CAN_GENERATE, ESA_STATE, ESA_TYPE, FORECAST, OPT_OUT_STATE,
POWER_ADJUSTMENT_CAPABILITY,
};
pub use spec_dem::command::{
CANCEL_POWER_ADJUST_REQUEST, CANCEL_REQUEST, MODIFY_FORECAST_REQUEST, PAUSE_REQUEST,
POWER_ADJUST_REQUEST, REQUEST_CONSTRAINT_BASED_FORECAST, RESUME_REQUEST,
START_TIME_ADJUST_REQUEST,
};
pub use spec_dem::event::{PAUSED, POWER_ADJUST_END, POWER_ADJUST_START, RESUMED};
pub use spec_dem::{
AdjustmentCauseEnum, CauseEnum, ConstraintsStruct, ESAStateEnum, ESATypeEnum, ForecastStruct,
ID, OptOutStateEnum, PICS, PowerAdjustReasonEnum, PowerAdjustStruct, REVISION,
SlotAdjustmentStruct, feature,
};
pub const ADJUSTMENTS_MAX: usize = 10;
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct ForecastSummary {
pub forecast_id: u32,
pub start_time: u32,
pub end_time: u32,
pub earliest_start_time: Option<u32>,
pub latest_end_time: Option<u32>,
pub slot_is_pausable: bool,
pub min_pause_duration: u32,
pub max_pause_duration: u32,
pub adjusted: bool,
}
pub trait DemHooks {
fn esa_type(&self) -> ESATypeEnum;
fn can_generate(&self) -> bool {
false
}
fn base_state(&self) -> ESAStateEnum;
fn abs_min_power(&self) -> i64;
fn abs_max_power(&self) -> i64;
fn opt_out_state(&self) -> OptOutStateEnum {
OptOutStateEnum::NoOptOut
}
fn power_adjust_ranges(&self) -> &[PowerAdjustStruct] {
&[]
}
fn forecast(&self) -> Option<ForecastSummary> {
None
}
fn write_forecast(&self, w: &mut TlvWriter<'_>, tag: Tag) -> crate::error::Result<()> {
w.null(tag)
}
fn power_adjust(
&self,
power_mw: i64,
duration_s: u32,
cause: AdjustmentCauseEnum,
) -> Result<(), Status> {
let _ = (power_mw, duration_s, cause);
Err(Status::Failure)
}
fn may_interrupt_adjustment(&self) -> bool {
true
}
fn end_power_adjust(&self, cause: CauseEnum) {
let _ = cause;
}
fn adjust_start_time(
&self,
requested_start_time: u32,
cause: AdjustmentCauseEnum,
) -> Result<(), Status> {
let _ = (requested_start_time, cause);
Err(Status::Failure)
}
fn pause(&self, duration_s: u32, cause: AdjustmentCauseEnum) -> Result<(), Status> {
let _ = (duration_s, cause);
Err(Status::Failure)
}
fn resume(&self) -> Result<(), Status> {
Ok(())
}
fn modify_forecast(
&self,
adjustments: &[SlotAdjustmentStruct],
cause: AdjustmentCauseEnum,
) -> Result<(), Status> {
let _ = (adjustments, cause);
Err(Status::Failure)
}
fn constraint_based_forecast(
&self,
constraints: &[ConstraintsStruct],
cause: AdjustmentCauseEnum,
) -> Result<(), Status> {
let _ = (constraints, cause);
Err(Status::Failure)
}
fn cancel_adjustments(&self) -> Result<(), Status> {
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Event {
PowerAdjustStart,
PowerAdjustEnd(CauseEnum),
Paused,
Resumed(CauseEnum),
}
#[derive(Debug)]
pub struct DeviceEnergyManagement<'a, H: DemHooks> {
hooks: &'a H,
feature_map: u32,
adjust_reason: Cell<PowerAdjustReasonEnum>,
adjust_until: Cell<Option<Instant>>,
paused_until: Cell<Option<Instant>>,
events: RefCell<heapless::Vec<Event, 8>>,
}
impl<'a, H: DemHooks> DeviceEnergyManagement<'a, H> {
#[must_use]
pub fn new(hooks: &'a H, feature_map: u32) -> Self {
Self {
hooks,
feature_map,
adjust_reason: Cell::new(PowerAdjustReasonEnum::NoAdjustment),
adjust_until: Cell::new(None),
paused_until: Cell::new(None),
events: RefCell::new(heapless::Vec::new()),
}
}
pub fn conforming(
feature_map: u32,
optional: &Optional<'_>,
) -> crate::error::Result<Conforming<8, 8, 0, 4>> {
Conforming::new(&spec_dem::CLUSTER, feature_map, optional)
}
#[must_use]
pub fn state(&self) -> ESAStateEnum {
let base = self.hooks.base_state();
if base != ESAStateEnum::Online {
return base;
}
if self.paused_until.get().is_some() {
return ESAStateEnum::Paused;
}
if self.adjust_reason.get() != PowerAdjustReasonEnum::NoAdjustment {
return ESAStateEnum::PowerAdjustActive;
}
ESAStateEnum::Online
}
#[must_use]
pub fn adjust_reason(&self) -> PowerAdjustReasonEnum {
self.adjust_reason.get()
}
#[must_use]
pub fn wake_at(&self) -> Option<Instant> {
match (self.adjust_until.get(), self.paused_until.get()) {
(Some(a), Some(p)) => Some(if a < p { a } else { p }),
(Some(a), None) => Some(a),
(None, Some(p)) => Some(p),
(None, None) => None,
}
}
pub fn poll(&self, now: Instant) {
if let Some(until) = self.adjust_until.get()
&& now >= until
{
self.finish_adjust(CauseEnum::NormalCompletion);
}
if let Some(until) = self.paused_until.get()
&& now >= until
{
self.paused_until.set(None);
let _ = self.hooks.resume();
self.push(Event::Resumed(CauseEnum::NormalCompletion));
}
}
pub fn abort(&self, cause: CauseEnum) {
if self.paused_until.take().is_some() {
self.push(Event::Resumed(cause));
}
self.finish_adjust(cause);
}
pub fn take_events(&self) -> heapless::Vec<Event, 8> {
core::mem::take(&mut self.events.borrow_mut())
}
fn push(&self, event: Event) {
let mut events = self.events.borrow_mut();
if events.is_full() {
events.remove(0);
}
let _ = events.push(event);
}
fn finish_adjust(&self, cause: CauseEnum) {
if self.adjust_reason.get() == PowerAdjustReasonEnum::NoAdjustment {
return;
}
self.adjust_reason.set(PowerAdjustReasonEnum::NoAdjustment);
self.adjust_until.set(None);
self.hooks.end_power_adjust(cause);
self.push(Event::PowerAdjustEnd(cause));
}
const fn supports(&self, bit: u32) -> bool {
self.feature_map & bit != 0
}
fn permits(&self, cause: AdjustmentCauseEnum) -> bool {
match (self.hooks.opt_out_state(), cause) {
(OptOutStateEnum::NoOptOut, _) => true,
(OptOutStateEnum::OptOut, _) => false,
(OptOutStateEnum::LocalOptOut, cause) => {
cause != AdjustmentCauseEnum::LocalOptimization
}
(OptOutStateEnum::GridOptOut, cause) => cause != AdjustmentCauseEnum::GridOptimization,
}
}
}
fn collect<'a, T: crate::tlv::FromTlv<'a> + Copy, const N: usize>(
list: TlvList<'a, T>,
) -> Result<heapless::Vec<T, N>, Status> {
let mut out: heapless::Vec<T, N> = heapless::Vec::new();
for entry in list.iter() {
let entry = entry.map_err(|_| Status::ConstraintError)?;
out.push(entry).map_err(|_| Status::ConstraintError)?;
}
Ok(out)
}
impl<H: DemHooks> ClusterHandler for DeviceEnergyManagement<'_, H> {
fn read(
&self,
resolved: &Resolved<'_>,
_ctx: &InteractionContext<'_>,
w: &mut TlvWriter<'_>,
tag: Tag,
) -> Result<(), Status> {
let full = |r: crate::error::Result<()>| r.map_err(|_| Status::ResourceExhausted);
match resolved.attribute {
ESA_TYPE => full(w.unsigned(tag, u64::from(self.hooks.esa_type().value()))),
ESA_CAN_GENERATE => full(w.bool(tag, self.hooks.can_generate())),
ESA_STATE => full(w.unsigned(tag, u64::from(self.state().value()))),
ABS_MIN_POWER => full(w.signed(tag, self.hooks.abs_min_power())),
ABS_MAX_POWER => full(w.signed(tag, self.hooks.abs_max_power())),
POWER_ADJUSTMENT_CAPABILITY => {
let ranges = self.hooks.power_adjust_ranges();
if ranges.is_empty() {
return full(w.null(tag));
}
full(w.start_structure(tag))?;
full(w.start_array(Tag::Context(0)))?;
for range in ranges {
full(range.to_tlv(w, Tag::Anonymous))?;
}
full(w.end_container())?;
full(w.unsigned(Tag::Context(1), u64::from(self.adjust_reason.get().value())))?;
full(w.end_container())
}
FORECAST => self
.hooks
.write_forecast(w, tag)
.map_err(|_| Status::ResourceExhausted),
OPT_OUT_STATE => full(w.unsigned(tag, u64::from(self.hooks.opt_out_state().value()))),
_ => Err(Status::UnsupportedAttribute),
}
}
#[allow(clippy::too_many_lines)]
fn invoke(
&self,
resolved: &ResolvedCommand<'_>,
fields: Option<&[u8]>,
ctx: &InteractionContext<'_>,
_w: &mut TlvWriter<'_>,
_tag: Tag,
) -> Result<Option<CommandId>, StatusIb> {
let payload = || fields.ok_or(StatusIb::from(Status::InvalidCommand));
match resolved.command.id {
POWER_ADJUST_REQUEST => {
if !self.supports(feature::POWER_ADJUSTMENT) {
return Err(Status::UnsupportedCommand.into());
}
let decoded: spec_dem::PowerAdjustRequestFields = super::decode_fields(payload()?)?;
if !self.permits(decoded.cause) {
return Err(Status::ConstraintError.into());
}
let running = self.adjust_reason.get() != PowerAdjustReasonEnum::NoAdjustment;
if self.hooks.base_state() != ESAStateEnum::Online {
return Err(Status::Failure.into());
}
let power = i64::from(decoded.power);
let fits = self.hooks.power_adjust_ranges().iter().any(|range| {
power >= i64::from(range.min_power)
&& power <= i64::from(range.max_power)
&& decoded.duration >= range.min_duration
&& decoded.duration <= range.max_duration
});
if !fits {
return Err(Status::ConstraintError.into());
}
if running && !self.hooks.may_interrupt_adjustment() {
return Err(Status::Busy.into());
}
self.hooks
.power_adjust(power, decoded.duration, decoded.cause)
.map_err(StatusIb::from)?;
self.adjust_reason.set(match decoded.cause {
AdjustmentCauseEnum::LocalOptimization => {
PowerAdjustReasonEnum::LocalOptimizationAdjustment
}
AdjustmentCauseEnum::GridOptimization => {
PowerAdjustReasonEnum::GridOptimizationAdjustment
}
});
self.adjust_until
.set(Some(ctx.now.saturating_add(Duration::from_secs(
u64::from(decoded.duration),
))));
if !running {
self.push(Event::PowerAdjustStart);
}
Ok(None)
}
CANCEL_POWER_ADJUST_REQUEST => {
if !self.supports(feature::POWER_ADJUSTMENT) {
return Err(Status::UnsupportedCommand.into());
}
if self.adjust_reason.get() == PowerAdjustReasonEnum::NoAdjustment {
return Err(Status::InvalidInState.into());
}
self.finish_adjust(CauseEnum::Cancelled);
Ok(None)
}
START_TIME_ADJUST_REQUEST => {
if !self.supports(feature::START_TIME_ADJUSTMENT) {
return Err(Status::UnsupportedCommand.into());
}
let decoded: spec_dem::StartTimeAdjustRequestFields =
super::decode_fields(payload()?)?;
if !self.permits(decoded.cause) {
return Err(Status::ConstraintError.into());
}
let Some(forecast) = self.hooks.forecast() else {
return Err(Status::Failure.into());
};
let span = forecast.end_time.saturating_sub(forecast.start_time);
let new_end = decoded.requested_start_time.saturating_add(span);
let too_early = forecast
.earliest_start_time
.is_some_and(|earliest| decoded.requested_start_time < earliest);
let too_late = forecast
.latest_end_time
.is_some_and(|latest| new_end > latest);
if too_early || too_late {
return Err(Status::ConstraintError.into());
}
self.hooks
.adjust_start_time(decoded.requested_start_time, decoded.cause)
.map_err(StatusIb::from)?;
Ok(None)
}
PAUSE_REQUEST => {
if !self.supports(feature::PAUSABLE) {
return Err(Status::UnsupportedCommand.into());
}
let decoded: spec_dem::PauseRequestFields = super::decode_fields(payload()?)?;
if !self.permits(decoded.cause) {
return Err(Status::ConstraintError.into());
}
let Some(forecast) = self.hooks.forecast() else {
return Err(Status::Failure.into());
};
if !forecast.slot_is_pausable {
return Err(Status::Failure.into());
}
if decoded.duration < forecast.min_pause_duration
|| decoded.duration > forecast.max_pause_duration
{
return Err(Status::ConstraintError.into());
}
let state = self.state();
if !matches!(
state,
ESAStateEnum::Online | ESAStateEnum::PowerAdjustActive | ESAStateEnum::Paused
) {
return Err(Status::Failure.into());
}
self.hooks
.pause(decoded.duration, decoded.cause)
.map_err(StatusIb::from)?;
let extra = Duration::from_secs(u64::from(decoded.duration));
let already_paused = self.paused_until.get();
self.paused_until.set(Some(match already_paused {
Some(until) => until.saturating_add(extra),
None => ctx.now.saturating_add(extra),
}));
if already_paused.is_none() {
self.push(Event::Paused);
}
Ok(None)
}
RESUME_REQUEST => {
if !self.supports(feature::PAUSABLE) {
return Err(Status::UnsupportedCommand.into());
}
if self.paused_until.get().is_none() {
return Err(Status::InvalidInState.into());
}
self.hooks.resume().map_err(StatusIb::from)?;
self.paused_until.set(None);
self.push(Event::Resumed(CauseEnum::Cancelled));
Ok(None)
}
MODIFY_FORECAST_REQUEST => {
if !self.supports(feature::FORECAST_ADJUSTMENT) {
return Err(Status::UnsupportedCommand.into());
}
let decoded: spec_dem::ModifyForecastRequestFields<'_> =
super::decode_fields(payload()?)?;
if !self.permits(decoded.cause) {
return Err(Status::ConstraintError.into());
}
let adjustments: heapless::Vec<SlotAdjustmentStruct, ADJUSTMENTS_MAX> =
collect(decoded.slot_adjustments).map_err(StatusIb::from)?;
let Some(forecast) = self.hooks.forecast() else {
return Err(Status::Failure.into());
};
if forecast.forecast_id != decoded.forecast_id {
return Err(Status::Failure.into());
}
self.hooks
.modify_forecast(&adjustments, decoded.cause)
.map_err(StatusIb::from)?;
Ok(None)
}
REQUEST_CONSTRAINT_BASED_FORECAST => {
if !self.supports(feature::CONSTRAINT_BASED_ADJUSTMENT) {
return Err(Status::UnsupportedCommand.into());
}
let decoded: spec_dem::RequestConstraintBasedForecastFields<'_> =
super::decode_fields(payload()?)?;
if !self.permits(decoded.cause) {
return Err(Status::ConstraintError.into());
}
let constraints: heapless::Vec<ConstraintsStruct, ADJUSTMENTS_MAX> =
collect(decoded.constraints).map_err(StatusIb::from)?;
self.hooks
.constraint_based_forecast(&constraints, decoded.cause)
.map_err(StatusIb::from)?;
Ok(None)
}
CANCEL_REQUEST => {
if !(self.supports(feature::START_TIME_ADJUSTMENT)
|| self.supports(feature::FORECAST_ADJUSTMENT)
|| self.supports(feature::CONSTRAINT_BASED_ADJUSTMENT))
{
return Err(Status::UnsupportedCommand.into());
}
let adjusted = self.hooks.forecast().is_some_and(|f| f.adjusted);
if !adjusted {
return Err(Status::InvalidInState.into());
}
self.hooks.cancel_adjustments().map_err(StatusIb::from)?;
Ok(None)
}
_ => Err(Status::UnsupportedCommand.into()),
}
}
}
impl<H: DemHooks> Cluster for DeviceEnergyManagement<'_, H> {
const ID: ClusterId = ID;
}