Confusing Naming of Component State Enums: `ComponentStatus` and `ComponentStateCode`

[tiyash-basu-frequenz]

What's needed?

We currently have two component state enums:

• ComponentStatus: This enum depicts the state of our interaction with a component (e.g., whether we can read from or write to it).
• ComponentStateCode: This enum represents the actual state of the component as derived from the component directly.

The current naming can potentially lead to confusion between ComponentStatus and ComponentStateCode. They could be mistaken for referring to the same entity. Furthermore, ComponentStatus lacks specificity, as it seems to indicate the component's overall status rather than focusing on the aspect of interaction.

We need to address the naming issue to improve readability.

Proposed solution

Proposal 1

We can rename the `ComponentStatus` enum to something more appropriate.

One proposal is ComponentAccessLevel. This correctly depicts the purpose of this entity.

Proposal 2

We flip the concept, and do the following:

Active mode

As soon as a component moves to this mode, we try to start it up. Note that this cannot be guaranteed to succeed, since a component could refuse to start up, e.g., due to the component's internal configuration.

In this mode, clients are allowed to read data from the component, and send commands to it. Sending commands to a component in this mode can be prevented by setting its respective bounds to (0,0), which would make the component read-only.

Disabled mode

As soon as a component moves to this mode, we try to stop it. Again, this cannot be guaranteed to succeed due the same reasons mentioned above.

In this mode, clients do not receive any data from the component, and cannot send any control commands to it.

In this concept, RequestedComponentMode may be a better name.

Proposal 3

This extends Proposal 2, with an intermediate mode for switching the component off while still getting data from it.

Active mode

As soon as a component moves to this mode, we try to start it up. Note that this cannot be guaranteed to succeed, since a component could refuse to start up, e.g., due to the component's internal configuration.

In this mode, clients are allowed to read data from the component, and send commands to it. Sending commands to a component in this mode can be prevented by setting its respective bounds to (0,0), which would make the component read-only.

Off mode

As soon as a component moves to this mode, we try to stop it. Again, this cannot be guaranteed to succeed due the same reasons mentioned above.

In this mode, clients keep receiving data from the component, but cannot send any control commands to it. This mode allows users to receive a feedback that their action to move the component to mode Off has worked or not.

Inaccessible mode

As soon as a component moves to this mode, we assume that the component is not available on the network, and we do not attempt to read from it.

In this mode, clients do not receive any data from the component, and cannot send any control commands to it.

Proposal 4

Enabled mode

As soon as a component moves to this mode, we try to start it up. (Note that this cannot be guaranteed to succeed, since a component could refuse to start up, e.g., due to the component's internal configuration.)

In this mode, clients are allowed to read data from the component, and send commands to it. Sending commands to a component in this mode can be prevented by setting its respective bounds to (0,0), which would make the component read-only.

Disabled mode

As soon as a component moves to this mode, we try to stop it. (Again, this cannot be guaranteed to succeed due the same reasons mentioned above.)

In this mode,

• we will try to disconnect the component from the microgrid, by opening its relays.
• we will prevent applications from sending control commands to the component.
• we will keep getting data from this component.

Use cases

• switch a component on - e.g., closing its AC/DC relays
• switch a component off - e.g., opening its AC/DC relays. Note that depending upon the component model, it may still be able to stay online and allow us to read from it.
• run maintenance activities on components - e.g., battery calibration, firmware updates.
• add a placeholder component to the component graph, to indicate its existence in case we cannot reach it over the network due to hardware-installation-related challenges.

Alternatives and workarounds

No response

Additional context

No response

[llucax]

Really, is ComponentStatus supposed to be about access level? Currently is only ACTIVE and INACTIVE, from the current values maybe ComponentOperationalStatus might be more precise, or we could have it as a bool if being active or inactive is independent from the access level.

[tiyash-basu-frequenz]

As of now, it is in fact about access - whether we should read from (and write to) a component or not. In practice, this could be used for a component that is electrically connected to a microgrid, but we do not have physical access to it. This has nothing to do with the component itself being active or inactive.

I do not think ComponentOperationalStatus helps. It is closer in meaning to the actual state of the component.
This would mean that ACTIVE and INACTIVE are not appropriately named either.

Or maybe we flip the concept, and say that if a component is moved to an INACTIVE, then we stop the component, and prevent clients from reading from it or writing to it. This approach of course has its own naming challenges.

[tiyash-basu-frequenz]

I have added a 2nd proposed solution, and am inclined towards it.

[thomas-nicolai-frequenz]

As soon as a component moves to this state, we try to start it up. Note that this cannot be guaranteed to succeed, since a component could refuse to start up, e.g., due to the component's internal configuration.

I think we need to be really clear on this that disabled would mean that a Microgrid API client can't use the component anymore but that it does not mean its really shut down. I feel thats something that would need clarification somehow.

[llucax]

Interpretation of proposal 3 from the client (app) side:

• Active mode: we put the component in the component graph and use it to come up with formulas, we try to read from it and to control it.
• Off mode: we put the component in the component graph and take it into account when building formulas. We try to read from it but we don't try to control it.
• Inaccessible: we put the component in the component graph and take it into account when building formulas, we want to read from it, but we need to find a proxy to read from it. We don't try to control it.

@shsms Maybe you can double-check if the above makes sense or am I missing anything?

[tiyash-basu-frequenz]

Right. (I just added a proposal 3 to the description, after a discussion)

[llucax]

Inaccessible mode

As soon as a component moves to this state, we try to stop it. Again, this cannot be guaranteed to succeed due the same reasons mentioned above.

Why would you try to stop it in this case? If we know the component is inaccessible we can't contact it, isn't it this the whole point of having a mode for inaccessible components?

[llucax]

(I took the liberty of editing the issue description to replace all occurrences of state with mode to make it more clear).

[tiyash-basu-frequenz]

Inaccessible mode
As soon as a component moves to this state, we try to stop it. Again, this cannot be guaranteed to succeed due the same reasons mentioned above.

Why would you try to stop it in this case? If we know the component is inaccessible we can't contact it, isn't it this the whole point of having a mode for inaccessible components?

oops, copy-paste error. Fixed.

[llucax]

The naming should probably a different discussion, and for the purpose of the discussion here I think we should keep using Active, Off, and Inaccessible, but I wanted to point out before I forget that Off seems a bit... off (🤡) if it still can send data. I wonder if Disabled or Inactive could be better for this, as it is not doing actual useful work (and also the opposite of Active), but it is not necessarily completely off (as in shut down, completely unresponsive).

[shsms]

Interpretation of proposal 3 from the client (app) side:

• Active mode: we put the component in the component graph and use it to come up with formulas, we try to read from it and to control it.

• Off mode: we put the component in the component graph and take it into account when building formulas. We try to read from it but we don't try to control it.

• Inaccessible: we put the component in the component graph and take it into account when building formulas, we want to read from it, but we need to find a proxy to read from it. We don't try to control it.

Yup, all that makes sense. We still have to decide how to distribute for example PV power at a location where there are some inaccesible PV inverters and some active. But that's a separate discussion.