Managing NvGrid#

Overview#

This guide provides step-by-step instructions for managing power constraints using DPS NvGrid.

For more information, refer to NvGrid Concepts.

Note: NvGrid is typically integrated with grid management systems or demand response platforms. This guide demonstrates manual operations for testing and understanding the workflow. For complete integration examples, refer to the Grid Integrator Guide.

Prerequisites#

  • DPS server running with NvGrid enabled

  • dpsctl installed and authenticated

  • Active topology with power feed configuration

Basic NvGrid Workflow#

Step 1: Discover Power Feeds#

# Get feed metadata
dpsctl nvgrid get-metadata

Output shows:

  • Feed tags (identifiers for electrical circuits)

  • Power minimum and maximum limits

  • Default constraints

Step 2: Schedule Load Target#

# Set 6MW target for 1 hour
dpsctl nvgrid set-load-target \
  --value=6 \
  --unit=megawatt \
  --start-time="2025-10-24T15:00:00Z" \
  --end-time="2025-10-24T16:00:00Z" \
  --best-effort=true

# Target specific feeds
dpsctl nvgrid set-load-target \
  --value=5 \
  --unit=megawatt \
  --start-time="2025-10-24T15:00:00Z" \
  --end-time="2025-10-24T16:00:00Z" \
  --feed-tags="feed-a1,feed-a2" \
  --correlation-id="curtailment-001"

# Reset to default constraint
dpsctl nvgrid set-load-target --default

Step 3: Query Schedule#

# View load schedule for next 4 hours
dpsctl nvgrid get-schedule \
  --start-time="2025-10-24T14:00:00Z" \
  --end-time="2025-10-24T18:00:00Z"

# Get current active target
dpsctl nvgrid get-current

Step 4: Monitor Status#

# Check current power status
dpsctl nvgrid get-status

Status shows:

  • Current load target per feed

  • Calculated power consumption

  • In-flight status (whether power adjustment is in progress)

  • Correlation ID of active constraint

Webhook Integration#

Register Webhook#

# Register webhook for all events
dpsctl nvgrid register-webhook \
  --url="https://grid-solution.example.com/nvgrid/webhook"

# Register for specific events
dpsctl nvgrid register-webhook \
  --url="https://grid-solution.example.com/nvgrid/webhook" \
  --events="start-ramp-down,end-ramp-down"

Webhook Requirements:

  • URL must be in the NvGrid webhook whitelist (configured in Helm values)

  • Endpoint must accept HTTP POST with JSON payload

  • Must return 200 OK for successful receipt

Unregister Webhook#

dpsctl nvgrid unregister-webhook \
  --url="https://grid-solution.example.com/nvgrid/webhook"

Advanced Scenarios#

Overlapping Schedules#

Most recently scheduled target takes precedence:

# Schedule 6MW from 4pm-7pm
dpsctl nvgrid set-load-target --value=6 --unit=megawatt \
  --start-time="2025-10-24T16:00:00Z" --end-time="2025-10-24T19:00:00Z"

# Schedule 8MW from 5pm-6pm (overrides previous)
dpsctl nvgrid set-load-target --value=8 --unit=megawatt \
  --start-time="2025-10-24T17:00:00Z" --end-time="2025-10-24T18:00:00Z"

Result:

  • 4pm-5pm: 6MW active

  • 5pm-6pm: 8MW active (most recent override)

  • 6pm-7pm: 6MW active (reverts to earlier schedule)

  • After 7pm: Default constraint

Resetting to Default Constraint#

# Reset to default power constraint for a time period (using --default)
dpsctl nvgrid set-load-target \
  --default \
  --start-time="2025-10-24T16:00:00Z" \
  --end-time="2025-10-24T19:00:00Z"

# Reset to default (using --value=0, equivalent)
dpsctl nvgrid set-load-target \
  --value=0 \
  --unit=watt \
  --start-time="2025-10-24T16:00:00Z" \
  --end-time="2025-10-24T19:00:00Z"

# Reset immediately and indefinitely
dpsctl nvgrid set-load-target --default

# Reset specific feeds
dpsctl nvgrid set-load-target \
  --default \
  --feed-tags="feed-a1,feed-a2"

Note: The --default flag resets the power constraint to the default (zero) value. This is mutually exclusive with --value and --unit. Alternatively, you can achieve the same result by setting --value=0 with any unit (e.g., --value=0 --unit=watt).

Monitoring#

Prometheus Metrics#

NvGrid exposes metrics for monitoring:

  • grpc_duration - API response time

  • grpc_requests - API request count

  • nvgrid_system_status_load_target_watts - Current load target per feed

  • nvgrid_system_status_calculated_load_watts - Actual power consumption

  • nvgrid_system_status_in_flight - Power event status

  • nvgrid_feed_schedule_load_target_watts - Scheduled targets with status

Query these metrics from Prometheus to track grid integration health and power management effectiveness.

Troubleshooting#

Webhook Registration Fails#

Error: “webhook URL not whitelisted”

Solution: Add the webhook URL to the whitelist in DPS Helm values:

dps:
  nvgrid:
    webhook:
      whitelist:
        - "https://your-grid-solution.example.com/webhook"

Load Target Not Applied#

Check:

  1. Verify schedule is active: dpsctl nvgrid get-current

  2. Check system status: dpsctl nvgrid get-status

  3. Ensure DPM is enabled on resource groups

  4. Verify workloads are running (power can only be reduced from active jobs)

Target Not Met#

NvGrid uses best_effort strategy:

  • Target may not be achieved if it requires terminating jobs

  • Check in_flight status - power adjustment may still be in progress

  • Verify sufficient DPM-enabled workloads exist for power reduction

Further Reading#