Google Sign-In Required

Use your company Google account to access the BetterFleet private content.

Back to private home

BetterFleet Support Private
Skip to content
BetterFleet Dev Wiki
BBA Microgrid Controller Deliverables (Stories)
Initializing search
    bf-dev
    • Home
    • Product Capabilities
    • Process
    • Current Work
    • System Design
    • Software Reference
    • Operations
    bf-dev
    • Home
      • Overview
      • Manage
      • Overview
      • Product Engineering Workflow
      • Product Engineering Delivery
      • Product Engineering Workflow in Linear
        • GitLab Feature Flags
        • In-App Docs Authoring
        • Release Notes
      • Templates
      • Publishing
      • Workflow Companions
      • Overview
      • Active Artifacts
      • Backlog Artifacts
      • Archived Artifacts
      • Overview
      • Microgrid
      • OSCP
        • Challenge
        • Specification
        • Spec
        • Architecture
        • Overview
        • Script Runtime Model
        • Compose Profiles and Modes
        • Repo Topology
        • CI and Release Integration
        • Overview
        • Internal Application Diagrams
          • Overview
          • Web Model
          • Core Model
        • Service Interaction Flows
        • Data and State
          • Index
          • bf-manage-web
          • bf-manage-core
          • bf-manage-connect
          • bf-manage-sitepwrmon
          • bf-manage-incidents
          • bf-telematics
          • bf-depot-sim
          • bf-manage-roaming
          • bf-support-microsite
          • bf-digital-twin
          • bf-schedule-creator
        • Overview
        • Internal Application Diagrams
        • Migration and Flags
        • Simulation Request Lifecycle
          • Index
          • bf-bnl-ui
          • bf-bnl-settings
          • bf-bnl-schedule-analysis-compute
          • bf-route-modelling
          • bf-schedule-creator
          • bf-digital-twin
        • Overview
        • Secrets and Env Strategy
        • Vendors and Local Dependencies
        • ADRs
        • Service Matrix
        • Cloud Dependencies
        • Ports and URLs
      • Onboarding
      • Daily Operations Runbook
        • Overview
        • Staging Hotfix Release
        • Production Hotfix Release
        • Terraform Plan Dry Runs
      • Troubleshooting
      • Testing Guide
    • Context Summary
    • Microgrid Provisioning and Management
      • User Story
      • Dependencies
      • Major Development Pieces
      • Acceptance Criteria
    • External Capability Status to Microgrid Card
      • User Story
      • Dependencies
      • Major Development Pieces
      • Acceptance Criteria
    • Microgrid Card Capability Timeliness Visibility
      • User Story
      • Dependencies
      • Acceptance Criteria
    • General Microgrid Controller Configuration
      • User Story
      • Dependencies
      • Acceptance Criteria
    • Depot Sim BBA Microgrid Controller Sensor Packet Scenarios
      • User Story
      • Dependencies
      • Major Development Pieces
      • Acceptance Criteria

    BBA Microgrid Controller Deliverables (Stories)¶

    Context Summary¶

    • Product area: BetterFleet Manage.
    • Primary systems: bf-manage-core (domain + APIs), bf-manage-web (operator UX), and bf-manage-sitepwrmon (external status source).
    • Scope basis: docs/artifacts/active/bba-microgrid-controller/spec.md.
    • Delivery intent: thin, vertical stories with externally observable outcomes. No story exists solely to expose a backend API without a usable or observable outcome.
    • This story set reflects the confirmed post-production BBA deltas ahead of the broader spec and UAT refresh.

    Microgrid Provisioning and Management¶

    Linear issue: COR-8

    User Story¶

    As a support or configuration user, I want BetterFleet Manage to provision one canonical microgrid per depot and keep its first-level grid connections in sync with top-level depot circuits so that the microgrid remains a reliable site identity without manual topology maintenance.

    Dependencies¶

    None.

    Major Development Pieces¶

    • Backend: microgrid backfill for existing depots with one or more top-level circuits, automatic microgrid creation during depot creation, persistence of initial first-level GRID_CONNECTION nodes sourced from those circuits, and automatic resync whenever top-level circuit structure changes.
    • UI: a System Admin Microgrid tab that shows the current electrical structure from grid connections down and provides a Resync repair action.

    Acceptance Criteria¶

    • Running the project backfill creates one microgrid for every existing depot that already has one or more top-level circuits.
    • Creating a depot through the normal Manage flow automatically creates one microgrid for that depot.
    • The current bootstrap/admin API may locate the canonical microgrid by depot_id, but the returned entity still exposes its own canonical microgrid_id.
    • Creating a new top-level circuit automatically adds a corresponding persisted GRID_CONNECTION node to the depot microgrid.
    • Reparenting a circuit to or from top-level automatically reconciles the depot microgrid's persisted GRID_CONNECTION nodes.
    • Deleting a top-level circuit automatically removes the corresponding persisted GRID_CONNECTION node from the depot microgrid.
    • Renaming a top-level circuit is reflected in the depot microgrid after the sync path runs.
    • Manage UI exposes a System Admin Microgrid tab that loads the microgrid by depot and renders the structure from grid connections downward rather than showing the internal microgrid root.
    • Manage UI provides a Resync action for repair or recovery if the persisted grid-connection nodes drift from the legacy circuit model.
    • The system prevents more than one active microgrid from existing for the same depot at the same time.
    • The sync path is idempotent and does not change version when the set and order of persisted first-level GRID_CONNECTION nodes is unchanged.
    • Depots that do not yet have any valid top-level circuits produce a deterministic validation or provisioning failure outcome rather than a partial microgrid record.

    External Capability Status to Microgrid Card¶

    Linear issue: COR-9

    User Story¶

    As an operations user, I want bf-manage-sitepwrmon to update Peak Shaving and DER status for a depot's microgrid and see that status on the Manage UI Microgrid card so that external site state is demonstrable without log inspection.

    Dependencies¶

    • Microgrid Provisioning and Management

    Major Development Pieces¶

    • Backend: canonical depot-to-microgrid read contract plus external capability-status ingest, append-only history in shared event infrastructure, latest derived read state, and device-to-microgrid routing from bf-manage-sitepwrmon. Phase 1 keeps single-source-per-capability as an operational assumption; explicit competing-source conflict handling is follow-on backlog scope.
    • UI: reuse existing device sensor-action configuration with a new Update Microgrid State action, and show PEAK_SHAVING / DER status on the load-page Microgrid card once capability status exists for the selected microgrid. Initial rollout is behind the new-microgrid-fields-load-chart feature flag. Timeliness/freshness presentation is follow-on scope.

    Acceptance Criteria¶

    • Selecting a depot with an existing or newly provisioned microgrid opens a Manage UI Microgrid card for that site without requiring circuit-centric identity from the user.
    • The persisted microgrid for the selected depot remains the canonical site identity even though detailed electrical structure is still derived from the depot's existing circuits.
    • Device configuration supports a new Update Microgrid State sensor action generated through the existing sitepwrmon capability/config flow so a configured external controller device can publish PEAK_SHAVING and DER state without a second parallel mapping surface.
    • Sensor-action-based power source updates work even when the gateway site_model_name is None.
    • Update Power Source State and Update Power Source Load resolve their target power source by direct asset routing rather than requiring gateway output_translation.
    • In this milestone, direct power source routing uses the first applicable rule in this order: one power source on the sensor device's linked circuit, then one battery power source in the same depot, then gateway output_translation as compatibility fallback.
    • Sites that do not satisfy the direct-routing assumptions (for example multiple candidate battery power sources in one depot with no same-circuit match) produce deterministic remediation outcomes rather than silently writing to the wrong power source.
    • bf-manage-sitepwrmon can post PEAK_SHAVING and DER status for the selected depot's microgrid through the canonical microgrid capability-status path.
    • Accepted status updates are recorded as append-only domain-event history and folded into one latest-status read view per capability for UI consumption.
    • Phase 1 capability status is recorded at whole-microgrid scope rather than at a per-subtree scope.
    • Phase 1 external controller values for PEAK_SHAVING and DER are boolean true / false values that are normalized to deterministic ON / OFF operational status for UI display.
    • Re-sending the same provider event reference may append duplicate stored history temporarily, but it must not create a conflicting visible latest-status result for the same capability.
    • After a new external status is posted, refreshing the Microgrid card shows the latest projected PEAK_SHAVING and DER operational status values without manual data reshaping.
    • The Microgrid card still renders PEAK_SHAVING and DER sections for a depot that does not have a local PowerSource or BESS record once those capability statuses exist for the selected microgrid.
    • Requesting or navigating to a depot without a resolvable microgrid returns a deterministic not-found outcome.

    Microgrid Card Capability Timeliness Visibility¶

    Linear issue: COR-38

    User Story¶

    As an operations user, I want the Manage UI Microgrid card to show timeliness context for capability status so that I can tell whether the displayed controller state is recent enough to trust.

    Dependencies¶

    • External Capability Status to Microgrid Card

    Acceptance Criteria¶

    • When PEAK_SHAVING or DER status is displayed on the load-page Microgrid card, the card also shows freshness or last-updated context derived from the canonical capability-status timestamps.
    • The card lets an operator distinguish fresh from stale displayed capability status without leaving the load page.
    • Timeliness presentation is available for both supported capability types and remains legible alongside the existing microgrid card content on supported screen sizes.
    • The timeliness presentation reflects the same latest capability-status record that drives the displayed operational status.

    General Microgrid Controller Configuration¶

    Linear issue: COR-39

    User Story¶

    As a support or configuration user, I want a dedicated microgrid controller configuration surface so that controller bindings can be understood and managed without relying only on sensor-action implementation detail.

    Dependencies¶

    • External Capability Status to Microgrid Card

    Acceptance Criteria¶

    • Manage provides a controller configuration view that shows the selected depot or microgrid, the bound controller device, supported capability types, and enablement state.
    • A configuration user can create, review, update, and disable the controller binding used for microgrid capability ingest without editing hidden translation rules.
    • The configuration view shows which capability types are currently bound for the selected microgrid and which source device owns them.
    • Incomplete or invalid controller configuration changes fail with deterministic feedback rather than silently accepting unusable setup.

    Depot Sim BBA Microgrid Controller Sensor Packet Scenarios¶

    Linear issue: COR-40

    User Story¶

    As a QA or system test engineer, I want bf-depot-sim scenarios to publish the BBA microgrid controller telemetry packet shapes used by BetterFleet sensor actions so that all supported controller fields can be validated end-to-end before customer-facing tests.

    Dependencies¶

    • External Capability Status to Microgrid Card

    Major Development Pieces¶

    • Depot Sim: add a generic IoT sensor packet projection that can publish deterministic controller telemetry from simulation state instead of relying on hard-coded packet fixtures.
    • Depot Sim: add BBA microgrid controller scenario state and presets that cover capacity, heartbeat, peak shaving, DER export, BESS state of charge, device power state, and BESS operational mode.
    • Integration: allow scenario packet generation to use the same device and sensor-action binding details configured in BetterFleet Manage so the simulated packets follow the real integration path.
    • Testability: expose emitted packet or measurand history so automated and manual tests can assert the exact translated fields sent for each scenario step.

    Acceptance Criteria¶

    • bf-depot-sim can run scenarios that publish generic sensor packets through the same BetterFleet sensor-action path used by external BBA microgrid controller integrations.
    • Scenario configuration can deterministically drive AVAILABLE_CHARGING_CAPACITY, FAIL_SAFE_CAPACITY, HEARTBEAT_STATUS, LIMIT_PEAK_SHAVING, LIMIT_DER_EXPORT, SOC, DEVICE_POWER_STATE, and BESS_OPERATIONAL_MODE for a selected test site or microgrid.
    • Emitted packets use the exact measurand keys, casing, and units defined in docs/system-design/iot-sensor-packet/spec.md.
    • Scenario coverage includes the full BESS_OPERATIONAL_MODE truth table defined in docs/system-design/bba-microgrid-controller/generic-packet-translation.md.
    • AVAILABLE_CHARGING_CAPACITY and HEARTBEAT_STATUS are present for scenarios that exercise the microgrid controller circuit-capacity update path.
    • Scenario packet generation can be configured from BetterFleet Manage device and sensor-action configuration details rather than requiring hard-coded per-scenario transport mappings.
    • Running the scenario produces visible downstream BetterFleet behaviour for supported fields such as PEAK_SHAVING and DER, and provides inspectable emitted packet evidence for fields that are not yet surfaced in the UI.
    • The simulation path works when the target gateway site_model_name is None.
    • Re-running the same scenario produces the same emitted measurand sequence and the same downstream BetterFleet outcomes needed for repeatable test evidence.
    Made with Material for MkDocs