Tutorial: a robot’s power system from a schematic¶
You write a circuit as a SPICE netlist, name it from your URDF, see it in the viewer and check its numbers by hand. The finished result is examples/lagrange_example_power.
1. The circuit¶
power.cir, a 24 V battery with 100 mΩ inside, a bus capacitor and a lamp. Its first line is a title, as in any SPICE file:
Power system of my robot
V_pack in 0 DC 24
R_pack in dc 0.1
C_bus dc 0 4.7m IC=24
R_lamp dc 0 12
.tran 1m 0.2 uic
.end
Check it in ngspice before anything else: ngspice power.cir, then print v(dc). By hand, 24 * 12 / (12 + 0.1) = 23.80 V.
2. Name it from the URDF¶
SPICE cannot say what a battery holds, where a bus trips or which joint a motor turns. Say it in a <lagrange> block inside <robot>:
<lagrange>
<schematic file="power.cir"/>
<battery source="V_pack" capacity="72000" cutoff="18" max_charge="10"/>
<bus node="dc" undervoltage="15" overvoltage="30"/>
<motor joint="spin" node="dc" r="0.2" l="0.0003" kt="0.1" imax="20" gear="10" rotor_inertia="0.0001"/>
</lagrange>
Capacity is in coulombs (20 Ah is 72000), voltages in volts, currents in amps. Other URDF readers skip the block. What the importer reads and refuses is in formats.md §9.1; a part it cannot simulate stops the load with its line number. That includes diodes, inductors and anything between two buses, for now.
Before running, lagrange check robot.urdf says whether each motor and joint can carry the robot.
3. See it¶
lagrange robot.urdf
Press Ctrl+3 for the Electrical workspace:
Tab |
What it is |
|---|---|
Schematic |
Live blocks, wires whose width follows the current. Drag a block to move it; Auto-layout puts them back; Export SPICE writes the circuit |
Circuit |
The same as a circuit diagram, with symbols and values |
3D overlay |
The robot, each motor’s link tinted by its current, blue when reversed |
Netlist |
Edit a copy of the circuit on a form and save it as a |
Click the battery for its state of charge, sag and place on its voltage curve.
4. Read it from your code¶
Any signal goes on a ROS topic with --ros-topics:
publish:
- {signal: bus/dc/voltage, topic: /power/bus_voltage, type: std_msgs/msg/Float64}
5. More parts¶
A voltage curve, for a battery whose voltage follows its charge, given for the whole pack:
*lagrange battery V_pack capacity=72000 cutoff=30 max_charge=10 soc=0.5 ocv_soc=0,1 ocv=44,52
The source must equal the curve at that soc (here 48 V), or it is refused: ngspice and the run would answer for different batteries.
A DC-DC converter, with a source standing for its output in ngspice and a behavioural source for what it draws:
V_rail rail 0 DC 12
B_rail_in dc 0 I = -I(V_rail) * 12 / 0.9 / max(V(dc), 0.001) * ((V(dc) >= 0) ? 1 : 0)
R_lamp rail 0 6
*lagrange bus rail undervoltage=9 overvoltage=15
*lagrange converter dcdc source=V_rail in=dc max_current=5 efficiency=0.9 input_sink=B_rail_in
6. How you know it is right¶
tools/ci/check_electrical.py --verbose works out simple circuits three ways, by formula, in ngspice and in Lagrange, and fails on a difference. What it does not cover: switching ripple, which is averaged in the run and is for ngspice offline, temperature, trips and regeneration.