edgeengine-aware 0.4.0__py3-none-any.whl

edgeengine_aware/policies.py

@@ -0,0 +1,285 @@
+"""Policies implementing the Gymnasium-independent ``Policy`` protocol.
+
+All policies here consume the *normalised observation vector* produced by
+``ObservationBuilder`` and return a MultiDiscrete action array. Because they
+only use the observation (never the environment object), the very same code
+can drive the simulator or the deployment runtime in ``deployment.py``, and
+the rule-based policy translates line by line into C on a microcontroller.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .actions import DEFAULT_N_MODES, SENSE_HIGH, SENSE_LOW, SENSE_NONE, TX_NO, TX_YES, encode_action, n_flat_actions, unflatten_action
+from .observation import OBSERVATION_FIELDS, NodeProfile
+
+_IDX = {f.name: i for i, f in enumerate(OBSERVATION_FIELDS)}
+
+
+@dataclass
+class RuleBasedParams:
+    """Thresholds of the interpretable baseline (observation units unless noted)."""
+
+    soc_critical: float = 0.20
+    """Below this SoC: deep economy - one report every ``deep_eco_interval_h``,
+    nothing else, unless the application is urgent and starving."""
+
+    soc_low: float = 0.50
+    """Below this SoC: economy mode (report interval stretched, no checks).
+    Half of the storage is the trigger because a 300 J buffer covers only a
+    few cloudy days: waiting for the battery to be nearly empty is too late."""
+
+    deep_eco_interval_h: float = 8.0
+    """Report interval below ``soc_critical`` (still high-quality samples: a
+    cheap noisy sample is worth little to the application)."""
+
+    soc_high: float = 0.70
+    """Above this SoC (or under strong harvesting): generous mode."""
+
+    harvest_strong: float = 0.5
+    """Normalised recent-harvest level considered 'strong sun'."""
+
+    report_interval_h: tuple[float, float, float] = (2.0, 1.0, 0.5)
+    """Scheduled report interval per priority (routine / elevated / urgent)."""
+
+    report_interval_eco_factor: float = 2.0
+    """Economy mode stretches the report interval by this factor."""
+
+    eco_sensing_level: int = 2
+    """Sensing level used for reports in economy mode (2 = keep high quality)."""
+
+    report_interval_generous_factor: float = 0.75
+    """Generous mode shrinks the routine report interval by this factor."""
+
+    check_interval_h: float = 1.0
+    """Between reports, take a cheap low-cost sample this often to detect
+    sudden changes (disabled in economy mode)."""
+
+    event_delta: float = 0.08
+    """A low-cost check deviating from the reported value by more than this
+    triggers an immediate high-quality report (2 sigma of the low-cost noise)."""
+
+    importance_immediate: float = 0.7
+    """Report at once when the node-side importance exceeds this and the
+    stored value differs from the reported one by more than ``importance_delta``."""
+
+    importance_delta: float = 0.03
+
+    retry_age_h: float = 0.3
+    """A high-quality sample younger than this that has not been acknowledged
+    is retransmitted."""
+
+    age_scale_h: float = 24.0
+    """Must equal ObservationConfig.age_scale_s / 3600 (de-normalisation of ages)."""
+
+    link_margin_target_db: float = 4.0
+    """Radio mode choice: the cheapest mode whose expected margin (from the
+    node's path-loss estimate) is at least this is used; the most robust mode
+    when none qualifies; the reference mode when there is no estimate yet."""
+
+    link_quality_escalate: float = 0.7
+    """Below this ACK-EWMA the node escalates one mode (recent failures)."""
+
+    retry_min_link_quality: float = 0.5
+    """Immediate retries are suppressed below this ACK-EWMA (link down: back off
+    to the scheduled reports instead of burning energy every step)."""
+
+
+class RuleBasedPolicy:
+    """Interpretable heuristic controller.
+
+    The action space lets the node sense *and* transmit in the same step, and
+    the transmission always carries the freshest stored sample - so a
+    "scheduled report" is one action ``(SENSE_HIGH, TX_YES)``: wake up, take
+    a good sample, send it. Between reports the node may take cheap
+    low-cost *checks* without transmitting; if a check reveals a large change
+    the node confirms it with a high-quality sample and reports immediately.
+
+    Rules, in order:
+      1. **Deep economy** - SoC below ``soc_critical``: one high-quality report
+         every ``deep_eco_interval_h`` (urgent priority: every urgent interval),
+         nothing else.
+      2. **Retry** - a fresh high-quality sample that was not acknowledged is
+         retransmitted (no new sensing), unless the link looks down.
+      3. **Scheduled report** - when the estimated information age at the
+         application exceeds the report interval (shorter under higher
+         priority, stretched in economy mode, shrunk in generous mode):
+         high-quality sample + transmit. Economy mode (SoC below ``soc_low``)
+         keeps the sample quality and saves energy by reporting less often and
+         by skipping the checks - a cheap noisy sample is worth little to the
+         application, a missed hour is cheap.
+      4. **Event report** - the stored check differs from the reported value
+         by more than ``event_delta``, or the stored value is important
+         (near/below a threshold) and differs by more than ``importance_delta``:
+         high-quality sample + transmit.
+      5. **Check** - outside economy mode, a low-cost sample every
+         ``check_interval_h`` (no transmission).
+      6. Otherwise sleep.
+
+    **Radio mode** (when the profile has several): the cheapest mode whose
+    expected margin, computed from the node's path-loss estimate and the
+    flash link-budget table, is at least ``link_margin_target_db``; one mode
+    up when recent uplinks failed; the reference mode before the first
+    estimate. Without a profile the policy always uses the default mode.
+    """
+
+    def __init__(self, params: RuleBasedParams | None = None, profile: "NodeProfile | None" = None):
+        self.p = params or RuleBasedParams()
+        self.profile = profile
+        if profile is not None:  # keep the de-normalisation constant in sync with the node profile
+            self.p.age_scale_h = profile.observation.age_scale_s / 3600.0
+
+    def _tx(self, o: np.ndarray) -> int:
+        """Transmit action value: 1 + chosen radio mode."""
+        prof = self.profile
+        if prof is None or prof.n_modes == 1:
+            return TX_YES if prof is None else 1 + prof.reference_mode
+        oc = prof.observation
+        pl_norm = float(o[_IDX["path_loss_est"]])
+        if pl_norm >= 1.0:  # no estimate yet
+            return 1 + prof.reference_mode
+        pl_db = oc.path_loss_min_db + pl_norm * (oc.path_loss_max_db - oc.path_loss_min_db)
+        order = sorted(range(prof.n_modes), key=lambda k: prof.tx_energy_j[k])  # cheapest first
+        chosen = order[-1]
+        for k in order:
+            if prof.margin_for_mode(k, pl_db) >= self.p.link_margin_target_db:
+                chosen = k
+                break
+        if float(o[_IDX["link_quality"]]) < self.p.link_quality_escalate:
+            pos = order.index(chosen)
+            chosen = order[min(pos + 1, len(order) - 1)]
+        return 1 + chosen
+
+    def reset(self) -> None:  # stateless
+        pass
+
+    def act(self, observation) -> np.ndarray:
+        o = np.asarray(observation, dtype=np.float32)
+        p = self.p
+        soc = float(o[_IDX["battery_soc"]])
+        harvest_recent = float(o[_IDX["harvest_recent"]])
+        meas = float(o[_IDX["measurement"]])
+        quality = float(o[_IDX["measurement_quality"]])
+        has_measurement = quality > 0.0
+        high_quality = quality > 0.5
+        meas_age_h = float(o[_IDX["measurement_age"]]) * p.age_scale_h
+        since_ack_h = float(o[_IDX["time_since_tx_success"]]) * p.age_scale_h
+        app_age_h = float(o[_IDX["app_info_age"]]) * p.age_scale_h
+        reported = float(o[_IDX["reported_value"]])
+        has_reported = float(o[_IDX["time_since_tx_success"]]) < 1.0
+        priority = int(round(float(o[_IDX["app_priority"]]) * 2))  # 0 / 1 / 2
+        importance = float(o[_IDX["importance"]])
+        urgent = priority >= 2
+        eco = soc < p.soc_low and not urgent
+        generous = (soc > p.soc_high or harvest_recent > p.harvest_strong) and not eco
+        unreported = has_measurement and (since_ack_h > meas_age_h + 1e-6)
+        delta = abs(meas - reported) if (has_measurement and has_reported) else (1.0 if has_measurement else 0.0)
+
+        interval_h = p.report_interval_h[priority]
+        if eco:
+            interval_h *= p.report_interval_eco_factor
+        elif generous and priority == 0:
+            interval_h *= p.report_interval_generous_factor
+
+        # 1. deep economy
+        if soc < p.soc_critical:
+            limit_h = p.report_interval_h[2] if urgent else p.deep_eco_interval_h
+            if app_age_h >= limit_h:
+                return encode_action(SENSE_HIGH, self._tx(o))
+            return encode_action(SENSE_NONE, TX_NO)
+        # 2. retry a fresh, unacknowledged *report* (high-quality sample); cheap
+        #    low-cost checks are never retried, they are confirmed by rule 4.
+        #    No retry while the link looks down (recent ACKs mostly missing):
+        #    the next scheduled report will try again.
+        link_ok = float(o[_IDX["link_quality"]]) >= p.retry_min_link_quality
+        if unreported and high_quality and link_ok and meas_age_h < p.retry_age_h and app_age_h > interval_h:
+            return encode_action(SENSE_NONE, self._tx(o))
+        # 3. scheduled report
+        if app_age_h >= interval_h:
+            return encode_action(p.eco_sensing_level if eco else SENSE_HIGH, self._tx(o))
+        # 4. event / importance report
+        if unreported and (delta > p.event_delta or (importance > p.importance_immediate and delta > p.importance_delta)):
+            return encode_action(SENSE_HIGH, self._tx(o))
+        # 5. cheap check between reports
+        if not eco and (not has_measurement or meas_age_h >= p.check_interval_h):
+            return encode_action(SENSE_LOW, TX_NO)
+        return encode_action(SENSE_NONE, TX_NO)
+
+
+class RandomPolicy:
+    """Uniform random actions (lower bound reference)."""
+
+    def __init__(self, seed: int | None = None, n_modes: int = DEFAULT_N_MODES):
+        self.rng = np.random.default_rng(seed)
+        self.n_modes = n_modes
+
+    def reset(self) -> None:
+        pass
+
+    def act(self, observation) -> np.ndarray:
+        return unflatten_action(int(self.rng.integers(n_flat_actions(self.n_modes))), self.n_modes)
+
+
+class PeriodicPolicy:
+    """Sense (at a fixed level) and transmit every ``period_steps`` steps -
+    the classic duty-cycled firmware, oblivious to energy and application."""
+
+    def __init__(self, period_steps: int = 4, sensing_level: int = SENSE_LOW, tx: int = TX_YES):
+        self.period = max(1, int(period_steps))
+        self.level = sensing_level
+        self.tx = tx  # 1 + radio mode
+        self._t = 0
+
+    def reset(self) -> None:
+        self._t = 0
+
+    def act(self, observation) -> np.ndarray:
+        fire = self._t % self.period == 0
+        self._t += 1
+        return encode_action(self.level if fire else SENSE_NONE, self.tx if fire else TX_NO)
+
+
+class AlwaysOnPolicy:
+    """High-quality sensing and transmission at every step (upper bound on
+    information, lower bound on energy prudence)."""
+
+    def __init__(self, tx: int = TX_YES):
+        self.tx = tx
+
+    def reset(self) -> None:
+        pass
+
+    def act(self, observation) -> np.ndarray:
+        return encode_action(SENSE_HIGH, self.tx)
+
+
+@dataclass
+class EpisodeResult:
+    total_reward: float
+    metrics: dict
+    log: object
+    infos: list = field(default_factory=list)
+
+
+def run_episode(env, policy, *, seed: int | None = None, render: bool = False, render_every: int = 1, keep_infos: bool = False) -> EpisodeResult:
+    """Roll out one episode of ``policy`` in ``env`` (Gymnasium loop)."""
+    obs, info = env.reset(seed=seed)
+    policy.reset()
+    total = 0.0
+    infos: list = []
+    done = False
+    step = 0
+    while not done:
+        action = policy.act(obs)
+        obs, reward, terminated, truncated, info = env.step(action)
+        total += reward
+        if keep_infos:
+            infos.append(info)
+        if render and step % render_every == 0:
+            env.render()
+        done = terminated or truncated
+        step += 1
+    return EpisodeResult(total_reward=total, metrics=env.metrics.as_dict(), log=env.log, infos=infos)

edgeengine_aware/process.py

@@ -0,0 +1,136 @@
+"""Domain-independent pieces of the hidden world: the state every monitored
+process reports and the weekly activity schedule shared by the indoor and
+industrial domains.
+
+A *monitored process* is anything the node's sensor samples and the
+application wants to track: soil moisture (``agriculture.FieldEnvironment``),
+the CO2 concentration of a room (``indoor.IndoorAirProcess``), the temperature
+of a motor bearing (``industrial.BearingProcess``). Each of them implements
+
+    reset(rng, start_time_s)      -> None
+    step(time_s)                  -> ProcessState   (advance over [t, t + dt])
+    state()                       -> ProcessState
+    value                         -> float           (normalised, in [0, 1]; what the sensor samples)
+
+and reports its physical extras in ``ProcessState.aux``. Everything is
+simulator-only: the node sees the process through the noisy sensor only.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from .config import ScheduleConfig
+
+DAY_S = 86400.0
+HOUR_S = 3600.0
+
+
+@dataclass
+class ProcessState:
+    """Snapshot of a monitored process (privileged information)."""
+
+    value: float
+    """Normalised value of the monitored quantity in [0, 1]."""
+
+    last_step_change: float
+    """Change of the value during the last step."""
+
+    event_occurred: bool
+    """A sudden change or a zone crossing happened in the last step."""
+
+    zone: int
+    """0 = normal, 1 = warning, 2 = critical (direction given by QuantityConfig)."""
+
+    aux: dict[str, Any] = field(default_factory=dict)
+    """Domain-specific extras (temperatures, occupancy, health, counters, ...)."""
+
+    # backwards-compatible alias used by the agriculture code paths
+    @property
+    def soil_moisture(self) -> float:
+        return self.value
+
+
+class ActivitySchedule:
+    """Hidden weekly activity level in [0, 1] (people in a room, a machine on
+    shift). Drives both the monitored process and the harvesting source of a
+    domain, so that energy and information relevance are coupled the way they
+    are in reality.
+
+    ``level(t)`` is deterministic given the per-day draws made at ``reset``
+    (day factors, days off, extra days) plus a within-day AR(1) perturbation
+    advanced by ``step()`` once per environment step.
+    """
+
+    def __init__(self, cfg: ScheduleConfig, start_weekday: int = 0, horizon_days: int = 10):
+        self.cfg = cfg
+        self.start_weekday = int(start_weekday)
+        self.horizon_days = int(horizon_days)
+        self._rng = np.random.default_rng()
+        self._day_factor = np.ones(self.horizon_days + 2)
+        self._day_active = np.ones(self.horizon_days + 2, dtype=bool)
+        self._noise = 0.0
+        self.reset(self._rng, 0.0)
+
+    def reset(self, rng: np.random.Generator, start_time_s: float) -> None:
+        c = self.cfg
+        self._rng = rng
+        n = self.horizon_days + 2
+        first_day = int(start_time_s // DAY_S)
+        self._first_day = first_day
+        self._day_factor = np.clip(1.0 + rng.normal(0.0, c.day_factor_std, size=n), 0.3, 1.5)
+        active = np.array([self.weekday(first_day + k) in c.active_days for k in range(n)])
+        flips = rng.random(n)
+        self._day_active = np.where(active, flips >= c.p_day_off, flips < c.p_extra_day)
+        self._noise = 0.0
+
+    # -- calendar -----------------------------------------------------------------
+    def weekday(self, day_index: int) -> int:
+        return (self.start_weekday + day_index) % 7
+
+    def is_active_day(self, time_s: float) -> bool:
+        k = int(time_s // DAY_S) - self._first_day
+        if not 0 <= k < len(self._day_active):
+            return self.weekday(int(time_s // DAY_S)) in self.cfg.active_days
+        return bool(self._day_active[k])
+
+    def _day_factor_at(self, time_s: float) -> float:
+        k = int(time_s // DAY_S) - self._first_day
+        if not 0 <= k < len(self._day_factor):
+            return 1.0
+        return float(self._day_factor[k])
+
+    # -- level --------------------------------------------------------------------
+    def nominal_level(self, time_s: float) -> float:
+        """Deterministic window shape (ramps and dip) for the day type of ``time_s``."""
+        c = self.cfg
+        if not self.is_active_day(time_s):
+            return 0.0
+        h = (time_s % DAY_S) / HOUR_S
+        if h <= c.start_hour - c.ramp_h or h >= c.end_hour + c.ramp_h:
+            return 0.0
+        ramp_in = min(1.0, max(0.0, (h - (c.start_hour - c.ramp_h)) / max(c.ramp_h, 1e-6)))
+        ramp_out = min(1.0, max(0.0, ((c.end_hour + c.ramp_h) - h) / max(c.ramp_h, 1e-6)))
+        shape = min(ramp_in, ramp_out)
+        if c.dip_hours is not None and c.dip_hours[0] <= h < c.dip_hours[1]:
+            shape *= c.dip_level / max(c.base_level, 1e-6)
+        return c.base_level * shape * self._day_factor_at(time_s)
+
+    def step(self) -> None:
+        """Advance the within-day perturbation by one environment step."""
+        c = self.cfg
+        rho = c.noise_autocorr
+        self._noise = rho * self._noise + math.sqrt(max(0.0, 1 - rho**2)) * self._rng.normal(0.0, c.noise_std)
+
+    def level(self, time_s: float) -> float:
+        nominal = self.nominal_level(time_s)
+        if nominal <= 0.0:
+            return 0.0
+        return float(np.clip(nominal * (1.0 + self._noise), 0.0, 1.0))
+
+
+__all__ = ["ProcessState", "ActivitySchedule"]

edgeengine_aware/rendering.py

@@ -0,0 +1,199 @@
+"""Matplotlib dashboard renderer.
+
+One figure is created lazily and updated in place at every ``render()`` call.
+``human`` shows the figure interactively (no-op on a non-interactive backend,
+so headless training scripts are never blocked); ``rgb_array`` draws on an
+Agg canvas and returns an ``(H, W, 3)`` uint8 array; ``ansi`` returns a
+compact text dashboard. Only privileged information that the *user* is
+allowed to see is plotted (true moisture, true harvest); nothing here feeds
+the policy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .env import EdgeEngineAwareEnv
+
+PRIORITY_NAMES = ("routine", "elevated", "URGENT")
+SENSE_NAMES = ("-", "low", "HIGH")
+_MODE_COLORS = ("#eda100", "#2a78d6", "#4a3aa7", "#1baf7a", "#e87ba4", "#008300")
+
+
+def plt_mode_color(k: int, n_modes: int) -> str:
+    return _MODE_COLORS[k % len(_MODE_COLORS)]
+
+
+def text_dashboard(env: "EdgeEngineAwareEnv") -> str:
+    """Compact one-screen textual status of the environment."""
+    gt = env.ground_truth()
+    ns = env.node_state()
+    last = env._last_step
+    if not last["tx_attempted"]:
+        tx = "-"
+    else:
+        mode_name = env.cfg.communication.modes[last["tx_mode"]].name if last["tx_mode"] >= 0 else "?"
+        tx = f"{mode_name}:{'ok' if last['tx_success'] else 'FAIL'}"
+    meas = f"{ns.measurement_value:.3f}" if ns.has_measurement else "  n/a"
+    app = f"{gt['app_last_value']:.3f}" if gt["app_last_value"] is not None else "  n/a"
+    day, hour = env.clock.day_index(), env.clock.hour_of_day()
+    q = env.quantity
+    activity = f"   activity {gt['activity']:.2f}" if gt.get("activity") is not None else ""
+    lines = [
+        f"EdgeEngine AWARE [{env.cfg.domain}] | step {env._step_count:4d} | day {day} {int(hour):02d}:{int((hour % 1) * 60):02d}{activity}",
+        f"  battery SoC        : {ns.soc():6.1%}   ({ns.stored_energy_j:7.1f} J / {ns.capacity_j:.0f} J)",
+        f"  harvest (meas/true): {ns.harvest_power_w*1e3:6.3f} / {gt['harvest_power_true_w']*1e3:6.3f} mW   recent {ns.harvest_power_recent_w*1e3:.3f} mW   last step {env._last_harvested_j:.3f} J",
+        f"  {q.name[:19]:19s}: true {gt['value']:.3f} ({gt['physical_value']:.0f} {q.unit[:12]}) | node {meas} (age {ns.measurement_age_s/3600:.1f} h) | app {app} (AoI {gt['app_aoi_s']/3600:.1f} h)",
+        f"  zone / priority    : {('normal','warning','CRITICAL')[gt['zone']]} / {PRIORITY_NAMES[gt['app_priority']]}   path loss {gt['path_loss_db']:.0f} dB (node est. {ns.path_loss_est_db:.0f} dB)",
+        f"  action             : sense={SENSE_NAMES[last['sensing_level']]}  tx={tx}",
+        f"  reward             : {last['reward']:+.3f}   (utility {last['utility']:.3f})",
+    ]
+    return "\n".join(lines)
+
+
+class DashboardRenderer:
+    def __init__(self, env: "EdgeEngineAwareEnv"):
+        self.env = env
+        self.fig = None
+        self._interactive = False
+        self._pyplot_managed = False
+
+    # ------------------------------------------------------------------
+    def _ensure_figure(self, mode: str):
+        import matplotlib
+
+        if self.fig is not None:
+            return
+        if mode == "rgb_array":
+            # Do not touch the global backend; draw on a private Agg canvas.
+            from matplotlib.backends.backend_agg import FigureCanvasAgg
+            from matplotlib.figure import Figure
+
+            self.fig = Figure(figsize=(12, 10), dpi=80)
+            FigureCanvasAgg(self.fig)
+        else:
+            import matplotlib.pyplot as plt
+
+            self._interactive = matplotlib.get_backend().lower() not in ("agg", "pdf", "svg", "ps", "template")
+            if self._interactive:
+                plt.ion()
+            self.fig = plt.figure(figsize=(12, 10), dpi=80)
+            self._pyplot_managed = True
+        self.axes = self.fig.subplots(4, 2, sharex=True)
+        self.fig.subplots_adjust(hspace=0.4, wspace=0.25, top=0.84, bottom=0.06)
+        self._title = self.fig.text(0.02, 0.985, "", fontsize=9, family="monospace", ha="left", va="top")
+
+    def _draw(self) -> None:
+        env = self.env
+        log = env.log
+        cfg = env.cfg
+        t = np.asarray(log.time_s) / 86400.0 if len(log) else np.zeros(0)
+        axes = self.axes
+        for ax in axes.ravel():
+            ax.cla()
+            ax.grid(alpha=0.3)
+
+        def step_series(values):
+            return np.asarray(values, dtype=float)
+
+        # battery
+        ax = axes[0, 0]
+        ax.plot(t, step_series(log.soc), color="tab:blue")
+        ax.axhline(cfg.reward.safe_soc, color="tab:red", ls="--", lw=0.8)
+        ax.set_ylim(0, 1.02)
+        ax.set_title("Battery SoC")
+
+        # harvest
+        ax = axes[0, 1]
+        ax.plot(t, step_series(log.harvest_power_w) * 1e3, color="tab:orange", lw=0.9)
+        ax.set_title(f"Measured harvesting power [mW] ({cfg.harvesting_source})")
+
+        # monitored quantity
+        q = env.quantity
+        ax = axes[1, 0]
+        ax.plot(t, step_series(log.true_moisture), color="k", lw=1.0, label="true")
+        ax.plot(t, step_series(log.measured_moisture), color="tab:green", lw=0.9, label="node", drawstyle="steps-post")
+        ax.plot(t, step_series(log.app_moisture), color="tab:purple", lw=0.9, label="application", drawstyle="steps-post")
+        ax.axhline(q.warning_threshold, color="tab:orange", ls=":", lw=0.8)
+        ax.axhline(q.critical_threshold, color="tab:red", ls=":", lw=0.8)
+        ax.set_ylim(0, 1)
+        ax.legend(loc="upper right", fontsize=7, ncol=3)
+        ax.set_title(f"{q.name} (true / node / application), normalised; danger {'above' if q.critical_is_upper else 'below'} the dotted lines")
+
+        # events
+        ax = axes[1, 1]
+        if len(log):
+            lvl = step_series(log.sensing_level)
+            att = step_series(log.tx_attempt)
+            suc = step_series(log.tx_success)
+            ax.vlines(t[lvl == 1], 0, 0.8, color="tab:green", alpha=0.5, lw=0.8, label="sense low")
+            ax.vlines(t[lvl == 2], 0, 1.0, color="darkgreen", alpha=0.8, lw=0.8, label="sense high")
+            mode = step_series(log.tx_mode)
+            n_modes = max(1, len(cfg.communication.modes))
+            for k in range(n_modes):
+                sel = (att == 1) & (suc == 1) & (mode == k)
+                if sel.any():
+                    ax.scatter(t[sel], np.full(int(sel.sum()), 1.15 + 0.15 * k), marker="^", s=12, color=plt_mode_color(k, n_modes), label=f"tx ok ({cfg.communication.modes[k].name})")
+            fail = (att == 1) & (suc == 0)
+            ax.scatter(t[fail], np.full(int(fail.sum()), 1.15 + 0.15 * np.clip(mode[fail], 0, n_modes - 1)), marker="x", s=14, color="tab:red", label="tx fail")
+            ax.legend(loc="upper center", fontsize=6.5, ncol=3)
+        ax.set_ylim(0, 2.4)
+        ax.set_yticks([])
+        ax.set_title("Sensing and transmission events (tx markers by radio mode)")
+
+        # AoI
+        ax = axes[2, 0]
+        ax.plot(t, step_series(log.aoi_s) / 3600.0, color="tab:purple")
+        ax.set_title("Age of information at the application [h]")
+
+        # priority
+        ax = axes[2, 1]
+        ax.step(t, step_series(log.priority), where="post", color="tab:red")
+        ax.set_yticks([0, 1, 2])
+        ax.set_yticklabels(PRIORITY_NAMES, fontsize=7)
+        ax.set_ylim(-0.2, 2.2)
+        ax.set_title("Application priority")
+
+        # reward
+        ax = axes[3, 0]
+        ax.plot(t, step_series(log.reward), color="tab:gray", lw=0.7, label="reward")
+        ax.plot(t, step_series(log.utility), color="tab:blue", lw=0.9, label="utility")
+        ax.legend(loc="upper right", fontsize=7)
+        ax.set_title("Instantaneous reward")
+        ax.set_xlabel("time [days]")
+
+        ax = axes[3, 1]
+        if len(log):
+            ax.plot(t, np.cumsum(step_series(log.reward)), color="tab:gray")
+        ax.set_title("Cumulative reward")
+        ax.set_xlabel("time [days]")
+
+        self._title.set_text(text_dashboard(env))
+
+    # ------------------------------------------------------------------
+    def render(self, mode: str):
+        if mode == "ansi":
+            return text_dashboard(self.env)
+        self._ensure_figure(mode)
+        self._draw()
+        if mode == "rgb_array":
+            self.fig.canvas.draw()
+            buf = np.asarray(self.fig.canvas.buffer_rgba())
+            return buf[..., :3].copy()
+        # human
+        self.fig.canvas.draw_idle()
+        if self._interactive:
+            import matplotlib.pyplot as plt
+
+            plt.pause(1.0 / self.env.metadata["render_fps"])
+        return None
+
+    def close(self) -> None:
+        if self.fig is not None and self._pyplot_managed:
+            import matplotlib.pyplot as plt
+
+            plt.close(self.fig)
+        self.fig = None