freeze Revision 1 hardware baseline for CAD

HARDWARE.md

@@ -1,118 +1,24 @@
-# Hardware
-
-Verified facts only. Physical dimensions live in
-[`Measurements/`](Measurements/README.md) and are not repeated here.
-
-## Components
-
-| Part | Model | Qty |
-|---|---|---:|
-| Stepper motor | YEJMKJ / LYLANMO `42HDB0014NC-24B` | 2 |
-| Stepper driver | BIGTREETECH TMC2209 V1.3 | 2 |
-| Controller | ELEGOO ESP32 devkit, ESP-WROOM-32, USB-C | 1 |
-| RF detector | AD8317 EVAL BD (NWDZ V1.0) | 1 |
-| Buck converter | LM2596-based module | 1 |
-| Motor supply | 12 V battery, inline fuse, master disconnect | 1 |
-
-## Motor nameplate
-
-From the label, legible in `IMG_5249.HEIC`:
-
-| | |
-|---|---|
-| Holding torque | 0.13 N·m |
-| Phase resistance | 3.5 Ω |
-| Phase inductance | 3.4 mH |
-| Rated phase current | 1.0 A |
-| Step angle | 1.8° (200 full steps/rev) |
-| Frame | 42 × 42 × 21 mm |
-
-## Motor phase wiring
-
-| Wire | Phase |
-|---|---|
-| Black | A+ |
-| Green | A− |
-| Red | B+ |
-| Blue | B− |
-
-**Coil A = black + green. Coil B = red + blue.** Splitting a pair across the two driver
-outputs makes the motor buzz, jitter or lock instead of turning, and it is not obvious
-by ear.
-
-Check with a multimeter before energising: about 3.5 Ω within a pair, open circuit
-between pairs.
-
-Never connect or disconnect a motor while the drivers are powered.
-
-## GPIO baseline
-
-Working baseline for the current firmware. Verify against the actual board before
-final wiring.
-
-| Signal | Azimuth | Elevation | Notes |
-|---|---|---|---|
-| STEP | GPIO25 | GPIO18 | 3.3 V logic |
-| DIR | GPIO26 | GPIO19 | 3.3 V logic |
-| ENABLE (EN/ENN) | GPIO27 | GPIO23 | Active low — confirm carrier polarity |
-| UART TX → PDN_UART | GPIO22 / UART1 | GPIO17 / UART2 | One-wire; may need a resistor |
-| UART RX ← PDN_UART | GPIO21 / UART1 | GPIO16 / UART2 | |
-| Home switch | GPIO32 | GPIO33 | Configurable; see homing note below |
-| Emergency stop | GPIO13 | shared | Active low |
-
-Logic ground and motor-power ground must share a common reference. VM is 12 V to the
-drivers only — never to the ESP32.
-
-## Power
-
-```text
-12 V battery
-├── inline fuse (3–5 A)
-├── master disconnect
-├── TMC2209 VM ×2
-└── LM2596 buck → 5.0 V → ESP32 only
-```
-
-Set the buck output to exactly 5.0 V with a multimeter before connecting an ESP32. Do
-not trust an onboard display as the only check.
-
-Bulk capacitance (100–220 µF, 25 V minimum) close to each driver's VM/GND, plus 0.1 µF
-local decoupling. Steppers regenerate current when decelerating, so VM transients
-appear even when the command is static.
-
-Keep motor-current returns short and away from logic, switch and RF returns.
-
-USB and the buck rail can both energise the board. Check the board's power circuit
-before connecting both at once.
-
-## Motor current
-
-Commissioning starts at **650 mA RMS**. Motor ceiling is **1000 mA RMS**.
-
-Progression: 500–650 → 650–800 → ~900 only if needed. Never exceed the ceiling. A 12 V
-supply does not put 12 V across a winding — the TMC2209 chops to regulate current — but
-wrong RMS current still overheats or under-drives the motor.
-
-## Homing
-
-The firmware currently homes by driving to a switch (`home_switch_pin`). There is no
-sensorless/StallGuard implementation. Three options if switches are not wanted:
-
-1. **Skip homing.** Set zero by hand. Works now, no parts, no code. Zero moves on every
-   power cycle, so scans are not comparable to each other.
-2. **StallGuard sensorless homing.** The TMC2209 supports it and no switch is needed,
-   but it is not written yet and needs mechanical hard stops. A light antenna is the
-   hard case for stall detection.
-3. **One microswitch per axis.** Firmware already supports it. Most repeatable.
-
-Position is open-loop step counting. It is only trusted after a successful home. Reset,
-fault, e-stop or a missed step invalidates it.
-
-## Safety
-
-Physical commissioning starts with USB power only, motor power disconnected, and
-accessible power isolation that does not depend on firmware.
-
-Simulator tests prove none of: wiring correctness, GPIO correctness, motor direction,
-driver current, step timing under load, switch polarity, mechanical clearance,
-e-stop latency, RF accuracy.
+# Radiance3D owned hardware baseline
+
+This repository uses only the owned-hardware profile in
+[`firmware/config/radiance3d-owned-hardware.json`](firmware/config/radiance3d-owned-hardware.json).
+The hardware photographs in [`Part Numbers:Views/`](<Part Numbers:Views/>) are the
+visual authority; this file is an index, not a substitute for inspection.
+
+**Verified Hardware** is owned, photographed, measured, or electrically confirmed.
+**Design Intent** is conceptual Fusion guidance only; final placement is determined
+during CAD. The [reference architecture](docs/hardware/reference-architecture.md)
+keeps those categories separate.
+
+Read the hardware documentation in this order:
+
+1. [Owned hardware and BOM](docs/hardware/owned-hardware.md)
+2. [Power tree](docs/hardware/power-tree.md)
+3. [GPIO map](docs/hardware/gpio-map.md)
+4. [Wire and harness standard](docs/hardware/wire-standard.md)
+5. [Assembly, routing, and commissioning](docs/hardware/assembly-order.md)
+6. [Conceptual Fusion reference architecture](docs/hardware/reference-architecture.md)
+
+The firmware uses ESP-IDF. It has no calibrated RF-power conversion and has not yet
+been validated on the physical mechanism. Firmware soft limits are deliberately
+conservative placeholders until the final cable route is measured.

Measurements/README.md

@@ -2,6 +2,10 @@
 
 This folder is the **canonical source for every physical dimension in Radiance3D**.
 
+The enclosure has not yet been designed. Measurements support conceptual Fusion work;
+the [reference architecture](../docs/hardware/reference-architecture.md) defines the
+official non-dimensioned placement baseline.
+
 Every number here was measured with a digital caliper on the actual parts in hand and
 is traceable to a photograph in this folder. Hardware, mechanical, assembly, BOM and
 CAD documents elsewhere in the repository must link here rather than repeat these

Measurements/fusion360-assistant-prompt.md

@@ -1,5 +1,9 @@
 # Fusion 360 Assistant prompt
 
+The enclosure has not yet been designed. Treat all listed component locations as
+conceptual only and follow [`../docs/hardware/reference-architecture.md`](../docs/hardware/reference-architecture.md)
+for the official non-dimensioned placement baseline.
+
 Paste everything inside the code block below into Fusion 360 Assistant. It is written
 to be self-contained — it carries the measured dimensions with it, so the assistant
 does not need access to this repository.
@@ -18,9 +22,11 @@ Source of the numbers: [`nema17.md`](nema17.md), [`tmc2209-v1.3.md`](tmc2209-v1.
 You are helping me design the first Radiance3D pan-and-tilt prototype in Fusion 360.
 
 Radiance3D is an antenna radiation-pattern measurement platform. The mechanism rotates
-an antenna under test (AUT) in azimuth (pan) and elevation (tilt) while a stationary
-receiver measures it. Positioning repeatability matters more than speed, and the
-structure must not distort the radiation pattern more than necessary.
+the AD8317-mounted antenna under test (AUT) in azimuth (pan) and elevation (tilt) while
+an external stationary 5.8 GHz VTX transmits. The AUT threads directly onto the
+vertically mounted AD8317 SMA; no RG316 jumper connects the AUT and detector.
+Positioning repeatability matters more than speed, and the structure must not distort
+the radiation pattern more than necessary.
 
 =====================================================================
 NON-NEGOTIABLE RULES
@@ -38,21 +44,26 @@ NON-NEGOTIABLE RULES
    If a print comes out tight, the fix is dPrintClearance or dBearingFitAllowance, and
    nothing else. Overwriting a measurement with a print allowance destroys the record
    of what the hardware actually is.
-3. Each major part is a separate Fusion component, named as listed below.
-4. The MEASURED dimensions below are the source of truth. They were taken with
+3. The enclosure is not designed yet: all locations are conceptual, not dimensioned.
+   Place ESP32 and both drivers/bucks in the stationary base; place only the tilt motor,
+   vertically mounted AD8317, and antenna mount on the rotating platform. The pan motor
+   is fixed in the base and the target motion is one controlled 360° turn, not unlimited
+   continuous rotation. Model a managed moving harness, with lengths TBD AFTER CAD.
+4. Each major part is a separate Fusion component, named as listed below.
+5. The MEASURED dimensions below are the source of truth. They were taken with
    calipers on the actual parts. Do not replace them with datasheet or "standard"
    values, even where a standard value looks rounder or more familiar.
-5. Never guess a critical fit dimension. Anything marked PROVISIONAL is a placeholder
+6. Never guess a critical fit dimension. Anything marked PROVISIONAL is a placeholder
    for a measurement I have not taken yet. If a feature's fit depends on a PROVISIONAL
    value, say so out loud before modelling it, and design that feature so the
    parameter can change without rebuilding the part.
-6. Design for PETG on a fused-filament printer:
+7. Design for PETG on a fused-filament printer:
    - avoid overhangs steeper than 45 degrees where a design change can prevent them
    - minimise support material; state the intended print orientation for each part
    - use structural fillets at load-bearing intersections and ribs instead of thick
      solid walls
    - use heat-set threaded inserts wherever a fastener will be removed more than once
-7. Protect the motor shafts. A motor shaft must not carry a side load or a cantilevered
+8. Protect the motor shafts. A motor shaft must not carry a side load or a cantilevered
    mass. Every rotating axis is carried on its own bearings; the motor supplies torque
    through a coupler only.
 7a. Both motors have a connector on the rear end cap that stands 9.38 mm proud, with a
@@ -61,13 +72,14 @@ NON-NEGOTIABLE RULES
    connector must stay reachable for wiring. When you recommend a motor orientation,
    state where that 21.4 mm goes and what it costs in stack height. Do not recommend an
    orientation without pricing it.
-8. Place the pan and tilt axes as close together as practical, and put the antenna's
+9. Place the pan and tilt axes as close together as practical, and put the antenna's
    active centre as close as practical to the point where the two axes intersect.
    Offset between the antenna phase centre and the axis intersection is a measurement
    error, not just an aesthetic issue. Report any offset you cannot eliminate.
-9. Route cables so they never bind, stretch or wrap as the axes move. Coax bend radius
-   is a hard constraint, not a guideline.
-10. Work on ONE major component at a time. Do not start the next component until I
+10. Route the moving silicone harness so it never binds, stretches, or wraps through
+    one controlled 360° pan turn; its bend radius is a hard constraint, not a guideline.
+    The external VTX coax is off-scanner and there is no AUT-to-detector coax jumper.
+11. Work on ONE major component at a time. Do not start the next component until I
     have reviewed and approved the current one.
 
 =====================================================================

Measurements/fusion360-bom-template.md

@@ -1,5 +1,9 @@
 # Fusion 360 BOM template
 
+The enclosure has not yet been designed. All placements are conceptual only; use
+[`../docs/hardware/reference-architecture.md`](../docs/hardware/reference-architecture.md)
+as the official non-dimensioned baseline.
+
 Use this as the starting BOM for the first prototype. Because the relevant hardware is already in the project, this can stay as a simple mechanical checklist first; fill in part numbers and suppliers only if you want a formal procurement list.
 
 ## Mechanical
@@ -21,15 +25,17 @@ Use this as the starting BOM for the first prototype. Because the relevant hardw
 |---|---:|---|---|---|
 | ESP32 board | 1 | ELEGOO ESP32 devkit | TBD | Existing hardware |
 | TMC2209 driver | 2 | Stepper driver module | TBD | Existing hardware |
-| Buck converter | 1 | LM2596 module | TBD | Measure before tray finalization |
+| Buck converter A | 1 | ZX-052 V2.0, ESP32 5 V branch | TBD | Existing hardware; stationary base |
+| Buck converter B | 1 | ZX-052 V2.0, AD8317 5 V branch | TBD | Existing hardware; stationary base |
 
 ## RF and antenna
 
 | Item | Qty | Description | Part number | Notes |
 |---|---:|---|---|---|
-| Antenna under test | 1 | Antenna to be mounted | TBD | Measure before cradle finalization |
-| Coax | 1 | RF cable to antenna | TBD | Check bend radius |
-| RF detector | 1 | AD8317 evaluation board | TBD | Existing hardware |
+| Antenna under test | 1 | Threads directly onto AD8317 SMA | TBD | Measure before direct-SMA mount finalization |
+| RF detector | 1 | AD8317 evaluation board, vertically mounted | TBD | Existing hardware; rotating platform |
+| External VTX | 1 | Stationary external 5.8 GHz source | TBD | Off-scanner; not an enclosure component |
+| RG316 jumper, antenna to detector | 0 | Not used | — | Direct SMA connection only |
 
 ## Miscellaneous
 

Measurements/fusion360-build-order.md

@@ -1,5 +1,9 @@
 # Fusion 360 build order — first prototype
 
+The enclosure has not yet been designed. All locations in this document are conceptual
+placement intent only; use the [reference architecture](../docs/hardware/reference-architecture.md)
+as the official non-dimensioned baseline before choosing CAD dimensions.
+
 This is the practical next-step plan for the first Radiance3D prototype. It is intentionally scoped so you can build the structure one component at a time without guessing.
 
 ## 0. Before modeling anything
@@ -16,6 +20,10 @@ Before you model the first part, confirm these items from the existing measureme
 
 Create the stationary base first. This defines the envelope for everything else.
 
+The 12 V source is permanently off-board beneath the workbench. Do not model a battery
+compartment, retention feature, or battery-weight allowance. Model only an accessible,
+strain-relieved `+12V IN` / `GND IN` entry and its route to internal distribution.
+
 ### Goals
 - Provide a stable platform for the pan axis.
 - Reserve space for the pan motor, bearings, and the electronics tray.
@@ -57,7 +65,9 @@ Once the base is reviewed, add the pan motor mount.
 
 ## 3. Build Pan_Platform third
 
-Now model the rotating platform that carries the tilt assembly.
+Now model the rotating platform that carries only the tilt motor, vertically mounted
+AD8317 detector, and antenna mount. The AUT threads directly onto the detector SMA;
+do not add an antenna-to-detector coax jumper.
 
 ### Goals
 - Create the pan platform as a bearing-supported rotating part.
@@ -164,13 +174,18 @@ Cable routing should be designed as part of the structure, not added later.
 
 ### Goals
 - Prevent cable binding or stretching through motion.
-- Respect the minimum bend radius of the coax or cable being used.
+- Model RF paths as RG316 50 Ω coax with a centre-and-shield envelope; model silicone
+  electrical harnesses separately, never as the same cable type.
+- Respect the measured minimum bend radius of the RG316 coax and the bend clearance of
+  each silicone harness.
 - Keep the cable path away from fasteners and the moving bearing faces.
 
 ### Model requirements
 - Include clips or guides in the frame and base.
 - Leave generous bend radius room.
-- Prevent the cable from wrapping around the axis as it moves.
+- Prevent either cabling system from wrapping around the axis as it moves.
+- Label CAD routes with `RF-###` for coax and `PWR-###`, `SIG-###`, or `MTR-###` for
+  silicone harnesses.
 
 ## 10. Build Limit_Switch_Mounts tenth
 

Measurements/fusion360-design-spec.md

@@ -1,12 +1,17 @@
 # Fusion 360 design spec — precision pass
 
+The enclosure has not yet been designed. All component locations are conceptual only;
+the [reference architecture](../docs/hardware/reference-architecture.md) is the official
+non-dimensioned placement baseline for Fusion work.
+
 This document is a tighter handoff for the first Radiance3D pan-and-tilt prototype. It turns the broad CAD brief into a concrete implementation plan that is easier to execute in Fusion 360 and easier to review.
 
 ## 1. Target architecture
 
 The first prototype should use a two-axis, two-bearing mechanism with the motor shafts protected from side load:
 
-- Pan axis: a rotating platform carried on bearings in the base, driven by the pan motor through a coupler.
+- Pan axis: a rotating platform carried on bearings in the base, driven by the fixed
+  stationary-base pan motor through a coupler; target capability is one controlled 360° turn.
 - Tilt axis: a tilt support frame carried on bearings and driven by the tilt motor through a coupler.
 - The motor shaft should never be the primary radial support for the axis. The bearings carry the load; the motor supplies torque only.
 - The antenna active centre should be placed as close as practical to the pan/tilt axis intersection. The target is $0\,\text{mm}$ offset. Any remaining offset must be recorded as a design parameter rather than hidden.
@@ -67,8 +72,12 @@ The antenna active centre should be brought as close as practical to the pan/til
 
 ### 4.4 Cable path
 
-The cable route should be planned before the frame is finalized. Cable routing must account for:
-- coax bend radius
+The cable route should be planned before the frame is finalized. RF and electrical
+cabling must be modelled as separate routes: RG316 50 Ω coax is represented with centre
+conductor and shield for RF-### paths, while PWR-###, SIG-###, and MTR-### are silicone
+wire harnesses. Cable routing must account for:
+- bend radius of the moving silicone harness; the external VTX RG316 path is not a
+  scanner-mounted antenna-to-detector jumper
 - connector reach
 - axis travel
 - strain relief

Measurements/fusion360-parameters.md

@@ -1,5 +1,8 @@
 # Fusion 360 parameters
 
+The enclosure has not yet been designed. These parameters support conceptual Fusion
+work only; they do not establish final component locations or enclosure dimensions.
+
 Proposed Fusion 360 user parameters for the Radiance3D pan-and-tilt prototype.
 
 Every parameter is tagged with its **type**, and the types are never mixed silently:

docs/architecture/overview.md

@@ -0,0 +1,6 @@
+# Architecture overview
+
+Radiance3D has an ESP-IDF controller, a portable controller simulator, and a Python
+host client. The owned-hardware configuration is generated into the firmware build from
+`firmware/config/radiance3d-owned-hardware.json`; hardware boundaries and commissioning
+requirements are documented in [the hardware index](../../HARDWARE.md).

docs/firmware/protocol.md

@@ -0,0 +1,5 @@
+# Firmware protocol
+
+The controller exposes its versioned motion protocol over USB serial. `MOTOR HOME` is
+rejected on the owned profile because no physical home switches are installed. Motion
+commands remain bounded by the profile's cable-protection soft limits.