The electrical network: buses, converters and the parts between them¶
A robot’s power system is batteries, buses, motor drives, loads and DC-DC converters, joined by
the parts a schematic draws between two buses: resistors (a harness), fuses, switches and diodes.
The electrical domain solves it every 100 µs by default (the profile’s electrical.dt, 10 µs to
1 ms) with averaged models: the mean over a switching cycle, never the switching itself, which
stays offline in ngspice. This page is the network; the parts on it have their own pages:
Motors and Battery.
flowchart LR
BAT["battery<br/>OCV(SoC), R0, RC pairs"] -->|"harness r"| BUS1["bus node<br/>capacitor C"]
BUS1 --> M["motor drives<br/>power drawn"]
BUS1 --> LD["loads<br/>resistive or constant power"]
BUS1 -->|"fuse, switch,<br/>resistor, diode"| BUS2["second bus"]
BUS1 -->|"input power / η"| DC["DC-DC converter"]
DC -->|"regulated voltage,<br/>0 to max current"| BUS3["rail"]
BUS3 --> LD2["5 V, 12 V loads"]
BUS1 -.->|"undervoltage"| BO["brownout<br/>drives off, loads unpowered"]
The equations¶
A bus is a node with a capacitance \(C\) (1 µF with a warning when none is given), so its voltage \(V\) is a state. Kirchhoff’s current law at the node, with the capacitor’s backward-Euler companion over a step \(\Delta t\):
Each battery enters as its Thévenin source: the equivalent circuit’s voltage \(E_k\) behind its
series resistance \(r_k\), which includes its harness (wireResistance). Drives and loads draw at the
previous step’s voltage (explicitly), so a load notices a brownout one electrical step late.
Loads. A resistive load takes its resistance from its power at the bus’s starting voltage,
\(R = V_0^2/P\); a constant-power load draws \(I = P/V\); both can be switched off by
load/<l>/powered when the bus browns out.
A drive draws its electrical power from the bus, \(i_{bus} = 1.5\,(v_d i_d + v_q i_q) / (\eta_{inv} V_{bus})\) (see Motors). Braking turns it round: regeneration charges the bus, the battery takes what it can up to its charge limit, and above the overvoltage trip a brake resistor switches in, or the drives switch off when there is none.
A DC-DC converter (ElectricalConverterAPI_1) is an averaged regulator. On its output bus it
is an ideal source at outputVoltage inside the node equation, giving 0 to maxOutputCurrent (no
reverse flow); at the limit the rail sags and its loads drop at their minVoltage. On its input
bus it draws the output power over its efficiency,
one step late, as loads do. It stops while its input bus is browned out. One converter per output bus.
Parts between buses (ElectricalBranchAPI_1, RFC 0010), each a two-terminal branch from bus
\(a\) to bus \(b\):
Kind |
Behaviour |
|---|---|
|
\(I = (V_a - V_b)/R\) |
|
a resistor until \(\int I^2\,dt\) reaches its rating (A²s), then open until the run restarts |
|
a resistor while |
|
\(I = (V_a - V_b - V_{drop})/R\) forward, open backward |
Trips. Under the bus’s undervoltage every drive latches a fault until the bus has recovered
by 2 % and its torque command is back to zero; loads come back with the bus. A battery is cut off
when its open-circuit voltage reaches cutoffVoltage (empty), not on the terminal voltage under
load: sag under load is the bus trip’s job.
Solving it¶
A bus with no branch keeps the single-node solve above, a scalar equation per step, so a robot without parts between buses runs exactly as before RFC 0010. Buses joined by branches are solved together: nodal analysis of all of them in one linear system, with the capacitors’ companions, solved densely with partial pivoting (a few dozen nodes at most, no allocation in the step). What is piecewise (a diode conducting or not, a battery at its charge limit, a converter at its current limit) is settled by repeating the solve while any of them changes state. A bus behind a part starts at what reaches it with nothing drawn.
Where the circuit comes from¶
The same network can be authored three ways, and all three become the same schemas at load:
An overlay file (
--overlay robot.overlay.yaml): batteries, buses, motors, loads, converters and branches as YAML (formats.md §9).A SPICE netlist (
--overlay power.cir): aVsource with its series chain is a battery, the node it reaches with itsCa bus,R n 0a resistive load, aBsource ofP / V(n)a constant-power load,R a bbetween two buses a resistor branch, and*lagrangecomment lines say what SPICE cannot (battery,bus,motor,converter,fuse R_x i2t=,switch R_x,diode D_x drop= r=). Anything else, inductors, transistors, subcircuits, is refused by line, every problem together (formats.md §9.1). A KiCad schematic comes throughkicad-cli sch export netlist --format spice.A URDF
<lagrange>block naming the netlist, with no flag (§9.2).
The other way, lagrange export spice|modelica writes the robot’s power system as an ngspice
netlist or a Modelica model, with the drives as averaged power sinks. The viewer’s Electrical
workspace draws the nets with their live values.
How far to trust it¶
Check |
Result |
Test |
|---|---|---|
Hand circuits: harness, resistor, constant power, RC pair, two batteries, charge drained, converter, sloped curve, resistor and diode between buses, a fuse opening at \(I^2t\), an open switch, a motor on a flywheel |
Lagrange within 0.5 % of the formula, ngspice within 0.1 %, each from an overlay, a netlist and a URDF block, on random values every round |
|
Energy balance over a drive cycle |
closed to 0.5 % |
|
Netlist round trip through ngspice |
bus voltage within 0.05 % (sag within 0.16 % RMS) with a drive cycle sagging a weak pack by 2.4 V |
|
Brownout of a stalled AMR on a low battery |
the bus trips, the computer loses power, both recover |
|
Regeneration into a full battery |
the bus rises until the brake resistor takes it |
|
A converter’s regulation, its input power, its current limit |
met |
|
A switch between buses follows its command |
met |
|
Netlist import: parts between buses, refusals |
met |
|
Deterministic, and restores its state |
met |
|
Against a measured robot’s power system |
owed: no bench recording yet |
— |
Not modelled: switching ripple (the models are averaged), inductors and transformers, op-amps, regulators as circuits (a regulator is a DC-DC converter), a capacitor between two buses, reverse flow through a converter, and the cost of a large branched network has not been measured. The hand check does not cover thermal effects, trips or regeneration; the tests above do.
The full model and its signals are in electrical.md §2, §9 and §10, and the parts between buses in RFC 0010.