items = new ArrayList<>();
+ list.forEach(items::add);
+ if (items.isEmpty()) {
+ sb.append("[]");
+ return;
+ }
+ sb.append("[\n");
+ for (int i = 0; i < items.size(); i++) {
+ pad(sb, indent + 1);
+ write(sb, items.get(i), indent + 1);
+ sb.append(i + 1 < items.size() ? ",\n" : "\n");
+ }
+ pad(sb, indent);
+ sb.append(']');
+ } else {
+ quote(sb, value.toString());
+ }
+ }
+
+ private static void pad(StringBuilder sb, int indent) {
+ sb.append(" ".repeat(indent));
+ }
+
+ private static void quote(StringBuilder sb, String s) {
+ sb.append('"');
+ for (char c : s.toCharArray()) {
+ switch (c) {
+ case '"' -> sb.append("\\\"");
+ case '\\' -> sb.append("\\\\");
+ case '\n' -> sb.append("\\n");
+ case '\r' -> sb.append("\\r");
+ case '\t' -> sb.append("\\t");
+ default -> {
+ if (c < 0x20) {
+ sb.append(String.format("\\u%04x", (int) c));
+ } else {
+ sb.append(c);
+ }
+ }
+ }
+ }
+ sb.append('"');
+ }
+ }
+}
diff --git a/src/main/java/xbot/common/injection/electrical_contract/ReadyWhen.java b/src/main/java/xbot/common/injection/electrical_contract/ReadyWhen.java
new file mode 100644
index 00000000..115b3d77
--- /dev/null
+++ b/src/main/java/xbot/common/injection/electrical_contract/ReadyWhen.java
@@ -0,0 +1,26 @@
+package xbot.common.injection.electrical_contract;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks an electrical contract getter as part of a robot mechanism. The device only exists on a robot whose contract
+ * reports that mechanism as ready ({@link XElectricalReportContract#isReady(String)}).
+ *
+ *
+ * The value is the name of a constant in the robot's own hardware enum (for example {@code @ReadyWhen("LeftShooter")}
+ * for {@code Hardware.LeftShooter}). The library can't name a robot enum type, so the electrical report checks every
+ * name against {@link XElectricalReportContract#getHardwareNames()} and fails on a typo.
+ *
+ *
+ * Put it on the getter where it's first declared (usually the robot's abstract ElectricalContract); overrides in
+ * subclasses inherit it.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface ReadyWhen {
+ /** Name of the hardware/mechanism this device belongs to. */
+ String value();
+}
diff --git a/src/main/java/xbot/common/injection/electrical_contract/XElectricalReportContract.java b/src/main/java/xbot/common/injection/electrical_contract/XElectricalReportContract.java
new file mode 100644
index 00000000..6c472041
--- /dev/null
+++ b/src/main/java/xbot/common/injection/electrical_contract/XElectricalReportContract.java
@@ -0,0 +1,80 @@
+package xbot.common.injection.electrical_contract;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * Optional extras an electrical contract can provide for the electrical report
+ * ({@code xbot.common.electrical.report.ElectricalReport}): which mechanisms the robot has, and wiring facts the robot
+ * code itself doesn't use (CAN daisy-chain order, non-motor PDH loads, converter branches).
+ *
+ *
+ * The report-only lists are only used when the robot's own contract class declares them, so a contract that extends
+ * another robot's contract doesn't inherit that robot's wiring.
+ */
+public interface XElectricalReportContract {
+
+ /**
+ * One device's place in a CAN daisy chain.
+ *
+ * @param busId
+ * The bus.
+ * @param canId
+ * The device's CAN ID on that bus.
+ * @param deviceName
+ * A readable name (documentation only; the report matches on bus and ID).
+ * @param busPosition
+ * 1-based position along the chain.
+ */
+ record CanBusOrderEntry(CANBusId busId, int canId, String deviceName, int busPosition) {
+ }
+
+ /**
+ * Whether this robot has the named mechanism (see {@link ReadyWhen}).
+ *
+ * @param hardwareName
+ * Name of a constant in the robot's hardware enum.
+ * @return True if devices tagged with that name exist on this robot.
+ */
+ default boolean isReady(String hardwareName) {
+ return true;
+ }
+
+ /**
+ * Every name {@link #isReady(String)} understands, used to catch typos in {@link ReadyWhen}.
+ *
+ * @return The names, or null to skip the check.
+ */
+ default Set getHardwareNames() {
+ return null;
+ }
+
+ /**
+ * Physical daisy-chain order of the CAN devices.
+ *
+ * @return Chain entries; empty if not documented.
+ */
+ default List getCanBusConnectionOrder() {
+ return List.of();
+ }
+
+ /**
+ * Non-motor loads on PDH ports (VRMs, buck converters, the controller, the radio...). Several non-motor loads may share
+ * a port.
+ *
+ * @return Port to load names; empty if not documented.
+ */
+ default Map> getAdditionalPDHConnections() {
+ return Map.of();
+ }
+
+ /**
+ * Converter to the devices it powers (e.g. a buck converter feeding a coprocessor).
+ *
+ * @return Converter name to downstream device names; empty if not documented.
+ */
+ default Map> getAdditionalPowerBranches() {
+ return Map.of();
+ }
+}
diff --git a/src/test/java/xbot/common/electrical/report/ElectricalReportTest.java b/src/test/java/xbot/common/electrical/report/ElectricalReportTest.java
new file mode 100644
index 00000000..de135a2e
--- /dev/null
+++ b/src/test/java/xbot/common/electrical/report/ElectricalReportTest.java
@@ -0,0 +1,203 @@
+package xbot.common.electrical.report;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import org.junit.jupiter.api.Test;
+
+import org.wpilib.hardware.bus.CANPort;
+
+import xbot.common.injection.electrical_contract.CANBusId;
+import xbot.common.injection.electrical_contract.CANMotorControllerInfo;
+import xbot.common.injection.electrical_contract.DeviceInfo;
+import xbot.common.injection.electrical_contract.MotorControllerType;
+import xbot.common.injection.electrical_contract.PDHPort;
+import xbot.common.injection.electrical_contract.PowerSource;
+import xbot.common.injection.electrical_contract.ReadyWhen;
+import xbot.common.injection.electrical_contract.XElectricalReportContract;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class ElectricalReportTest {
+
+ enum Hardware {
+ Shooter, Intake
+ }
+
+ /** Shaped like a robot's abstract ElectricalContract: readiness plus tagged getters. */
+ abstract static class BaseContract implements XElectricalReportContract {
+ private final Set ready;
+
+ BaseContract(Set ready) {
+ this.ready = ready;
+ }
+
+ @Override
+ public boolean isReady(String hardwareName) {
+ return ready.stream().anyMatch(h -> h.name().equals(hardwareName));
+ }
+
+ @Override
+ public Set getHardwareNames() {
+ return Arrays.stream(Hardware.values()).map(Enum::name).collect(Collectors.toSet());
+ }
+
+ @ReadyWhen("Shooter")
+ public abstract CANMotorControllerInfo getShooterMotor();
+
+ @ReadyWhen("Intake")
+ public abstract CANMotorControllerInfo getIntakeMotor();
+
+ public DeviceInfo getHomeSensor() {
+ return DeviceInfo.builder("HomeSensor").withChannel(0).withPowerFrom(PowerSource.RIO).build();
+ }
+
+ public DeviceInfo getHoodServo() {
+ return DeviceInfo.builder("HoodServo").withChannel(3).build();
+ }
+ }
+
+ /** A robot with a shooter only, and its own wiring lists. */
+ static class ShooterRobot extends BaseContract {
+ ShooterRobot() {
+ super(EnumSet.of(Hardware.Shooter));
+ }
+
+ @Override
+ public CANMotorControllerInfo getShooterMotor() {
+ return CANMotorControllerInfo.builder("Shooter").withType(MotorControllerType.TalonFx).withCanBus(CANBusId.Canivore, 22).withPdhPort(PDHPort.PDH02)
+ .build();
+ }
+
+ @Override
+ public CANMotorControllerInfo getIntakeMotor() {
+ return CANMotorControllerInfo.builder("Intake").withType(MotorControllerType.TalonFx).withCanBus(CANPort.CAN_S0, 30).withPdhPort(PDHPort.PDH03)
+ .build();
+ }
+
+ @Override
+ public List getCanBusConnectionOrder() {
+ return List.of(new CanBusOrderEntry(CANBusId.Canivore, 22, "Shooter", 1));
+ }
+
+ @Override
+ public Map> getAdditionalPDHConnections() {
+ return Map.of(PDHPort.PDH20, List.of("Controller"));
+ }
+ }
+
+ /** A second robot built on the first one's contract; it must not inherit its wiring. */
+ static class SpareRobot extends ShooterRobot {
+ }
+
+ /** A typo in a hardware name. */
+ abstract static class TypoContract extends BaseContract {
+ TypoContract() {
+ super(EnumSet.allOf(Hardware.class));
+ }
+
+ @ReadyWhen("Shoter")
+ public CANMotorControllerInfo getFeederMotor() {
+ return CANMotorControllerInfo.builder("Feeder").withType(MotorControllerType.TalonFx).withCanBus(CANBusId.Canivore, 23).withPdhPort(PDHPort.PDH04)
+ .build();
+ }
+ }
+
+ @Test
+ public void leavesOutDevicesWhoseMechanismIsNotReady() throws Exception {
+ ElectricalReport.Discovery d = ElectricalReport.discover(new ShooterRobot());
+ assertEquals(List.of("Shooter"), d.canByBus.get("Canivore").stream().map(ElectricalReport.CanDevice::name).toList());
+ assertFalse(d.canByBus.containsKey("can_s0"));
+ assertEquals(List.of("Intake"), d.disabled);
+ }
+
+ @Test
+ public void recordsWhereEachDeviceIsDefined() throws Exception {
+ ElectricalReport.Discovery d = ElectricalReport.discover(new SpareRobot());
+ assertEquals("ShooterRobot", d.definedIn.get("Shooter"));
+ assertEquals("BaseContract", d.definedIn.get("HomeSensor"));
+ }
+
+ @Test
+ public void sortsIoByConvention() throws Exception {
+ ElectricalReport.Discovery d = ElectricalReport.discover(new ShooterRobot());
+ assertEquals(List.of("HomeSensor"), d.dio.stream().map(DeviceInfo::name).toList());
+ assertEquals(List.of("HoodServo"), d.pwm.stream().map(DeviceInfo::name).toList());
+ }
+
+ @Test
+ public void usesWiringListsOnlyFromTheRobotsOwnClass() throws Exception {
+ ElectricalReport.Discovery own = ElectricalReport.discover(new ShooterRobot());
+ assertEquals(1, own.canOrder.size());
+ assertEquals(1, own.canByBus.get("Canivore").get(0).busPosition());
+ assertTrue(own.additionalPdh.containsKey(PDHPort.PDH20));
+
+ ElectricalReport.Discovery spare = ElectricalReport.discover(new SpareRobot());
+ assertTrue(spare.canOrder.isEmpty());
+ assertTrue(spare.additionalPdh.isEmpty());
+ }
+
+ @Test
+ public void rejectsUnknownHardwareNames() throws Exception {
+ TypoContract contract = new TypoContract() {
+ @Override
+ public CANMotorControllerInfo getShooterMotor() {
+ return null;
+ }
+
+ @Override
+ public CANMotorControllerInfo getIntakeMotor() {
+ return null;
+ }
+ };
+ Method feeder = TypoContract.class.getMethod("getFeederMotor");
+ assertThrows(IllegalStateException.class, () -> ElectricalReport.isEnabled(contract, feeder));
+ }
+
+ @Test
+ public void writesSnapshotAndTextReport() throws Exception {
+ ShooterRobot contract = new ShooterRobot();
+ ElectricalReport.RobotContract robot = new ElectricalReport.RobotContract("Test Robot", ShooterRobot::new);
+ ElectricalReport.Discovery d = ElectricalReport.discover(contract);
+
+ String json = ElectricalReport.Json.write(ElectricalReport.snapshot("Competition", robot, contract, d));
+ assertTrue(json.contains("\"contractName\": \"Competition\""));
+ assertTrue(json.contains("\"bus\": \"Canivore\""));
+ assertTrue(json.contains("\"disabled\": [\n \"Intake\"\n ]"));
+
+ ByteArrayOutputStream bytes = new ByteArrayOutputStream();
+ ElectricalReport.writeText(new PrintStream(bytes, true, StandardCharsets.UTF_8), "Competition", robot, contract, d);
+ String text = bytes.toString(StandardCharsets.UTF_8);
+ assertTrue(text.contains("ID 22: Shooter"));
+ assertTrue(text.contains("PDH20: Controller"));
+ assertTrue(text.contains("Not on this robot"));
+ }
+
+ @Test
+ public void writesEveryContractAndAnIndex(@org.junit.jupiter.api.io.TempDir java.nio.file.Path dir) throws Exception {
+ Map contracts = new java.util.LinkedHashMap<>();
+ contracts.put("Competition", new ElectricalReport.RobotContract("Shooter Robot", ShooterRobot::new));
+ contracts.put("Spare", new ElectricalReport.RobotContract("Spare Robot", SpareRobot::new));
+ ElectricalReport.writeAll(dir, contracts);
+ assertTrue(java.nio.file.Files.exists(dir.resolve("Competition.json")));
+ assertTrue(java.nio.file.Files.exists(dir.resolve("Spare.json")));
+ String index = java.nio.file.Files.readString(dir.resolve("index.json"));
+ assertTrue(index.contains("\"file\": \"Spare.json\""));
+ }
+
+ @Test
+ public void escapesJsonStrings() {
+ assertEquals("\"a\\\"b\\\\c\\n\"", ElectricalReport.Json.write("a\"b\\c\n"));
+ }
+}