What's needed?

Currently, the set-power commands from clients are invalidated after 60s, by the service. The API could be extended to allow clients specify their own durations for this, instead of having to always rely on the default 60s.

Allowing more choices for the valid-until time allows the following:

• It provides more control to the user, which is what we intend as a principle.
• It makes it more transparent that issued commands are stopped after a finite amout of time. Users can then refer to the protocol definition, and not just the API documentation.

Note that the commands will still be invalidates by the Microgrid Service after 60s by default (if the duration is not specified in the request).

Use cases

• Clients could opt for commands having valid-until durations shorter than the current default of 60s, and not care about stopping their last command. This could help simplify some of their logic.

Proposed solution

Solution 1

Update the request parameter to provide an arbitrary duration, but specify lower and upper limits of the parameter in docs.

message SetComponentPowerActiveRequest {
  uint64 component_id = 1;
  float power = 2;

  // This field will be added.
  // The duration, in seconds, until which the request will stay in effect.
  // This duration has to be between 10 seconds and 15 minutes (including both limits), otherwise the request will be rejected.
  // If not provided, it defaults to 60s.
  optional uint64 effect_duration = 3;
}

Solution 2

Update the request parameter to provide durations from an enum.

enum CommandEffectDuration {
  COMMAND_EFFECT_DURATION_DEFAULT = 0;
  COMMAND_EFFECT_DURATION_10_SECONDS = 1;
  COMMAND_EFFECT_DURATION_60_SECONDS = 2;
  COMMAND_EFFECT_DURATION_5_MINUTES = 3;
  COMMAND_EFFECT_DURATION_10_MINUTES = 4;
  COMMAND_EFFECT_DURATION_15_MINUTES = 5;
}

message SetComponentPowerActiveRequest {
  uint64 component_id = 1;
  float power = 2;

  // This field will be added.
  // The duration, in seconds, until which the request will stay in effect.
  // If not provided or set to the default variant, it defaults to 60s.
  optional CommandEffectDuration effect_duration = 3;
}

Alternatives and workarounds

No response

Additional context

No response