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
    • Process
    • Products
    • Reference
    • Decisions
    • Work
    • Operations
    bf-dev
    • Home
      • Process Handbook
      • BetterFleet Workflow Map
      • Product Development System
      • Product Engineering Workflow
        • Process Workflows
        • Work Intake and Weekly Planning
        • Product Engineering Workflow in Linear
        • Product Engineering Delivery
        • Agent Guidance
        • Workflow
        • Skills
        • Skill Sources
        • Process Guides
        • GitLab Feature Flags
        • In-App Docs Authoring
        • Release Notes
        • Process Templates
        • Release Plan: <title>
      • Process Publishing
      • Product overview
        • General Reference
          • Core Domain Training
          • System Topology
          • Two-Axis Ontology Model
          • Ontology Primer
          • Worked Example
          • Evidence, Ownership, and Lineage
          • Energy Management
          • Standards and Protocol Map
          • Charging, Roaming, and Commercial Model
          • Charge Planning and Operations
          • Cross-Cutting Domains
          • Domain Coverage Matrix
        • BetterFleet Product Ontology
        • Core Operations Data Ontology
        • BetterFleet R&D Plan
        • Index
        • Architecture
        • Manage Product Capabilities
        • Manage Data and State
        • Manage Service Interaction Flows
        • Manage Reference
        • Manage Internal Application Diagrams
          • Manage Authorization And Permissions
          • bf-manage-core Auth and Authorization Model
          • Manage Authorization and Permissions
          • bf-manage-web Auth and Permission Model
          • Manage Service Catalog
          • bf-depot-sim
          • bf-digital-twin (Manage Role)
          • bf-fleet-health
          • bf-manage-connect
          • bf-manage-core
          • bf-manage-incidents
          • bf-manage-roaming
          • bf-manage-sitepwrmon
          • bf-manage-web
          • bf-schedule-creator (Manage Role)
          • bf-support-microsite
          • bf-telematics
        • Index
        • Architecture
        • Plan Reference
        • Plan Internal Application Diagrams
        • Plan Migration and Flags
        • Plan Simulation Request Lifecycle
          • Plan Service Catalog
          • bf-bnl-schedule-analysis-compute
          • bf-bnl-settings
          • bf-bnl-ui
          • bf-digital-twin (Plan Role)
          • bf-route-modelling
          • bf-schedule-creator (Plan Role)
      • Where to Ask Product Questions
      • Reference
        • Platform Reference
        • Platform Architecture
        • Script Runtime Model
        • Compose Profiles and Modes
        • Repository Map
        • Monolithic Git Transition FAQ
        • Monolithic Git Sizing
        • CI and Release Integration
        • Shared Reference
        • Shared Infrastructure Architecture
        • Secrets and Env Strategy
        • Vendors and Local Dependencies
        • System Reference
        • Cloud Data Dependencies
        • Ports and URLs
        • Service Matrix
          • API Docs
          • OCPI API Docs
          • OCPP API Docs
          • OSCP API Docs
          • VDV API Docs
          • Yard State API Docs
        • System Design
        • System Design: BBA Microgrid Controller Generic Packet Translation
        • System Design: Depot Simulation
        • System Design: IoT Sensor Packet
        • System Design: Microgrid Energy Orchestration
          • System Design: OCPP Profile 3 And ISO 15118 PKI
          • Architecture: BetterFleet OCPP Profile 3 and ISO 15118 PKI
          • Specification: BetterFleet OCPP Profile 3 and ISO 15118 Certificate Lifecycle Management
          • System Design: On-Prem Control
          • Challenge
          • Specification: BetterFleet On-Prem Continuity Control
          • System Design: OSCP
          • OSCP Protocol Documentation
          • Depot Sim Testing Requirements
          • System Design: OSCP Flexibility Provider Domain
      • Decisions
        • Architecture Decision Records
        • 0001 - Record architecture decisions
        • 0002 - Cognito for Authentication and Authorisation
        • 0003 - AWS Amplify for Authentication
        • 0004 - DynamoDB for default database
        • 0005 - Data Persistence
        • 0006 - Trunk-Based Development
        • 0007 - Generalised principle for automation
        • 0008 - Naming Repositories, Services, and URLs
        • 0009 - Use Timezone Aware DateTimes and UTC
        • 0010 - Use semantic release
        • 0011 - Centralized feature flag repository
        • 0012 - Use Named Exports in Storybook
        • 0013 - RESTful TITLE GraphQL
        • 0014 - Service Granularity
        • 0015 - Async/co-routine exception handling pattern
        • 0016 - Logging & log levels
        • 0017 - Instantiated Models
        • 0018 - Repository Pattern for Database Access
        • 0019 - Use of Design Tokens in TypeScript React Application
        • 0020 - API backwards compatibility and versioning
        • 0021 - Alembic Migration strategy
        • 0022 - Consistent react-hook-form usage
        • 0023 - Domain Event-Driven Architecture
        • 0024 - Domain Event Bus Tech Stack
        • 0025 - No enum types in DB table columns
        • 0026 - In-Memory Ormar Stores for Repository testing
        • 0027 - Storing Tab State in Query and Local Storage
        • 0028 - Adopt OpenTelemetry Semantic Conventions for Structured Logging
        • 0029 - Adopt RFC 9457 for HTTP Error Responses
        • 0030 - Use GitLab registry and Terraform state for ECS services
        • 0031 - Adopt DDD, Hexagonal Architecture, and CQRS for Python Domain Services
      • Work
        • Active Work
          • Work: Bba Microgrid Controller
          • Implementation Specification: BBA Microgrid Controller
          • BBA Microgrid Controller Deliverables (Stories)
            • 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
          • Work: BFDev Monolithic Git
          • Challenge
          • Specification: BFDev Monolithic Git v2
          • BFDev Monolithic Git v2 Stories
          • Work: Complex Circuit Load Balancing
          • Implementation Specification: Complex Circuit Load Balancing
          • Complex Circuit Load Balancing Deliverables (Stories)
            • COR-10 and COR-11 Consolidation Review
          • Work: Dispatch Reliability and Reconciliation
          • Challenge
          • Specification: Dispatch Reliability and Reconciliation
          • Dispatch Reliability and Reconciliation (Unit User Stories)
            • Dispatch populated vehicle cards grey surface snapshot
            • Dispatch Visual Review
          • Work: Enable Scheduled Managed Charger Access
          • Challenge: Enable Scheduled Managed Charger Access
          • Specification Exploration Dossier: Enable Scheduled Managed Charger Access
          • Specification Review: Enable Scheduled Managed Charger Access
          • Specification: Enable Scheduled Managed Charger Access
          • Work: Guided Cut-Off and Release Orchestration
          • Specification: Guided Cut-Off and Release Orchestration
          • Guided Cut-Off and Release Orchestration (Unit User Stories)
          • Work: Production Deployment Validation
          • Challenge
          • Work: Scheduled Report Parity
          • Specification: Scheduled Report Parity
          • Work: Telematics
          • Telematics EventBridge Path
          • Telematics Ingress Architecture
          • Specification: Telematics Migration into bf-manage-core with 5-Minute Freshness and Health Visibility
          • Telematics Core Migration MVP (Implementation-Time BDD)
          • Work: Vector Derms
          • Implementation Specification: Vector DERMS
          • Vector DERMS Deliverables (Stories)
          • Work: Visiting Vehicle Charging Visibility
          • Specification: Visiting Vehicle Charging Visibility
          • Visiting Vehicle Charging Visibility (Unit User Stories)
          • Work: Workspace Owned Stripe Roaming
          • Specification: Workspace-Owned Stripe Credentials for Roaming Payments
        • Backlog Work
          • Work: Microgrid
          • Microgrid Backlog Stories
          • Work: Mobile Ops Companion
          • Challenge
          • Specification: Mobile Operations Companion v1
          • Mobile Operations Companion Deliverables (Stories)
          • Work: Oscp
          • OSCP Backlog Stories
        • Archived Work
          • Work: Code Canonical Orchestration
          • Challenge
          • Specification: Product Engineering Workflow
          • Product Engineering Workflow Deliverables (Unit User Stories)
          • Work: Release Notes Automation
          • Release Plan: Release Notes Automation
          • Release Notes Automation Backlog Stories
      • Operations
      • Onboarding Runbook
        • Operations Runbooks
        • Production Hotfix Release
        • Staging Hotfix Release
        • Manage Staging Release Validation
        • Terraform Plan Dry Runs
        • Operations Tooling
        • Code Indexing
        • Operations Evidence
        • Database Restoration Test Report
      • Daily Operations Runbook
      • Testing Guide
      • Troubleshooting
    • 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
    1. Home
    2. Work
    3. Active
    4. Bba microgrid controller

    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/work/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, dispatch state, 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, DISPATCH_STATE, 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/reference/system-design/iot-sensor-packet.md.
    • Scenario coverage includes the full BESS_OPERATIONAL_MODE truth table defined in docs/reference/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 DER, and provides inspectable emitted packet evidence for fields such as DISPATCH_STATE 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
    BFDev Docs Assistant
    New conversation?
    Ask one focused question at a time, this helps the assistant provide accurate answers about what's been implemented in BetterFleet.