Unify battery charging ports

[ducky64]

Currently, batteries have a pwr (output) and chg (input) Voltage port, even though both are on the same copper net. Can be unintuitive and lead to weirdness

Needs more thought on how to handle this. Perhaps a bidirectional port? Perhaps some concept of chargers (regulated voltage / current devices) instead of the constant-voltage source?

Requirements

• Allow-list certain types of multiple-source connections, here battery-charger
• Support propagation of values across blocks (e.g. a GatedPowerSwitch between a battery and charger), these blocks may have generator code to specifically handle propagating these connections
• Separate charging current limits (property of charger) from discharging current limits (property of source)
• Battery connection should be very straightforward in the discharge-only case - should be directly connect-able to a voltage regulator (no special-case links)
• Ideally, a generic facility (instead of BatteryPort - though that may be the lesser evil)
• Kinda fundamentally, this is asking for modeling of two distinct power states, charging and discharging, each with their own voltage, limits, current, and current limits.

Solution leaned towards

• Add reverse-voltage and reverse-current capability on VoltageLink. Parameters are pretty cheap in the Scala compiler.
• By default these parameters are empty. Passthrough subcircuits must be reverse-aware and must propagate those manually (define the capability)
• In some cases this must be an explicit opt-in parameter.
• Specifics TBD. Should there be a case where charging is required, and how would that be modeled? Possibly a parameter (eg, on a battery) as charging_current_limit which does not intersect zero?
• Until then, the recommendation is to not have a separate charge port, and charge ports should act as VoltageSinks with no draw.

Potential implementations

• VoltageBidir
  • Main drawback: distinct port type that needs to be accounted for where voltage port is being propagated, eg PMOS voltage gate
    • May be ok because the circuit needs to explicitly support bidir - but things get even more confusing in the bidir case
    • Example: Battery (Bidir w/ Chargeable tag) <-> (Bidir w/ Charger tag) GatedPowerSwitch (Bidir w/ Chargeable tag) <-> (Source w/ Charger tag) charger IC
      • Bidir has the modeling to act as a source or sink. Allowlisted combination of multiple sources, including Bidir when acting as a source (source limit > 0). Bidir with source_limit = 0 treated as a Sink. GatedPowerSwitch is Charging tag aware and can propagate charging capability from the output to the input.
    • Tags flow in power flow direction (by convention). GatedPowerSwitch always has a Chargeable tag on the output, but only produces a Charger tag on the input if it has a Charger on the input. Validation point is at the Battery - GatedPowerSwitch link.
    • Why Bidir over Source with tags? Avoids specialized ports / blocks, since ports can dual role capable. Provides data store (e.g. limits and output modeling) for both roles. Really just makes up for the lack of union ports. Source still needs tags.
• Support multiple sources on a single link in special cases
  • Imprecise modeling in that the ports are technically Bidir, but convenient
  • Could special-case the link to allow the one-charger one-charged device connection, with special rules to check current capability.
  • Example: Battery (Source w/ Chargeable tag) <-> (Source w/ Charger tag) GatedPowerSwitch (Source w/ Chargeable tag) <-> (Source w/ Charger tag) charger IC
    • GatedPowerSwitch would propagate tags. This version needs a Source on both the input and output, which is non-ideal, and either accomplished through a separate ChargerGatedPowerSwitch Block, or as an additional (probably confusing) src_in port.
    • Future work might support port unions, where the input port can be either Source or Sink based on connections.
• PROBLEM WITH ANY SINGLE-LINK CASE: can't separate the charging current from the unified current on the link.
  • Fundamentally, there are two states of power flows, discharging and charging, which have different capabilities and limits
  • This requires two sets of variables for the two cases, which should generalize to multiple-sources beyond charging.
  • VoltageBidir with concept of reversible flow? VoltageLink would manage reversed flow where needed? (this would probably absolutely destroy performance for an uncommon case)
• Continue with a separate charging port on the same net. Makes charging hella ugly by requiring two connections. Charging-aware intermediate blocks would need to have two ports on each side.
• Effectively, this is asking how to integrate two ports / links into one.
• Long-term: some concept of port mixins / aspects. A battery port is a source that also is Chargeable, while a charger port is source that is a Charger. Passthrough ports can define mixin passthrough logic explicitly.

General rules

• Any connection of multiple sources must be allow-listed, eg battery-charger combinations.
  • Most source-source connections are wrong
  • In this context, Bidir doesn't make sense, except as a store for variables
  • Battery (in a non-charging-only context, where it is clearly a Sink) is generally primarily a Source, with a secondary function as a Sink (where e.g. external power is supplied)

Use Cases

Use cases:

• Battery charging
• Bidirectional USB PD
• Motor regeneration

Some example topologies it should support:

• (battery) - (charger + sinks)
  • Note: this has a source (charger) + bidir (battery), which in general may not be safe.
• (battery) - (sinks)
• (battery) - (reverse protection circuit / gated power switch - can be charging aware) - (charger + sinks)

Some example topologies that might error:

• (multiple batteries in parallel) - (anything else)
• (battery) - (non-charging-capable reverse protection circuit, eg simple PMOS device) - (charger + sinks)
  • more of a stretch goal to detect this and error
• (charger) - (sinks)
  • Technically can be fine, where the charger is functionally a current-limited supply, but maybe unusual

Perhaps more parameters on VoltageInOut / VoltageBidir can address the above issues, without needing a dedicated BatteryPort and ChargerPort class. Brainstorming:

• VoltageBidir can have a controlled_source property - if true, the behavior is like DigitalBidir where it is up to the user to make sure that sources don't conflict. Battery would not be a controlled_source (they're always on) and would conflict.
• Need some way to distinguish that charging current only goes into the battery (or only validates against the battery). A trickle-charger + high power load is legit. Likely not possible without either battery-specific ports or battery-specific modeling (which might be ugly to add to a generic VoltageBidir).
• Note, for general VoltageBidir, parameters have these meanings:
  • voltage-out: (charger) output (up to float) voltage, (battery) operating voltage. All devices validate against this, this represents the actual voltage on the bus.
  • voltage-limit: (battery) charging limit (if any), (charger) maximum rating if provided. Consistent semantics with other VoltagePorts
  • current-drawn: ???
  • current-limit: (battery) maximum output / discharging current (what about input / charging current?)
  • as the charger is not meant to power other devices, charger current does not need to validate against current limit (except maybe on the low end, to ensure the battery charges regardless of parasitic draw?). But charger current must be within the battery charging limits - could just be the negative current limit of the battery?
• Insight (?): both battery and chargers can be modeled as CC-CV sources. Main difference is that battery tolerates slower charging current than limits (so different current-draw semantics)
  • Perhaps decouple current-draw into current-draw (hard current draw) and charging-limits (soft current draw), for battery types or VoltageBidir?
• Also needs a BatteryChargerBidir port, that acts as a VoltageSink AND a BatteryCharger, to allow forwarding eg across a protection circuit