Organize firmware by subsystem

Author: seofernando25

.dockerignore

@@ -7,13 +7,13 @@ pi/dist/
 stm32/.deps/
 stm32/app/build/
 stm32/tests/test_build_info
-stm32/tests/test_can_control
 stm32/tests/test_can_protocol
-stm32/tests/test_can_queue
+stm32/tests/test_can_rx_queue
 stm32/tests/test_can_tx_queue
 stm32/tests/test_diagnostics
-stm32/tests/test_protocol
 stm32/tests/test_protocol_vectors
+stm32/tests/test_rf_commands
+stm32/tests/test_rf_plan
 **/__pycache__/
 **/.pytest_cache/
 *.pyc

AGENTS.md

@@ -13,3 +13,10 @@
 
 - Use only repositories, branches, or implementations named by the user.
 - Do not inspect unrelated rewrites as design references unless the user explicitly asks.
+
+## Firmware layout
+
+- Keep production firmware under `stm32/app/src/{can,rf,platform}` with matching headers under `stm32/app/include/`.
+- Keep board GPIO and alternate-function assignments in `platform/board.h`.
+- Keep bench experiments and captured media under `stm32/bringup/`, not production source directories.
+- Name modules by responsibility: CAN transport/codec, RF planning/execution, or platform support.

docs/rf-control.md

@@ -4,7 +4,7 @@ CAN carries logical values; STM32 builds device serial words.
 
 ## PE44820
 
-Each phase value is a `0..255` lookup index. Firmware maps it to a calibrated 2.4 GHz `optimizedPhaseState_e` value from `PhaseStateEnum.h`:
+Each phase value is a `0..255` lookup index. Firmware maps it to a calibrated 2.4 GHz `optimizedPhaseState_e` value from `rf/phase_states_2_4ghz.h`:
 
 ```text
 bit 8     OPT

stm32/.gitignore

@@ -1,12 +1,13 @@
 app/build/
 app/generated.*.ld
-tests/test_protocol
+tests/test_rf_commands
+tests/test_rf_plan
 tests/test_diagnostics
 tests/test_can_protocol
-tests/test_can_queue
-tests/test_can_control
-tests/test_can_filter
+tests/test_can_rx_queue
+tests/test_can_tx_queue
 tests/test_build_info
+tests/test_protocol_vectors
 __pycache__/
 *.pyc
 *.o

stm32/README.md

@@ -43,17 +43,47 @@ Both RF buses are transmit-only. ACK means the STM32 completed the transfer, not
 
 ## Source map
 
+```mermaid
+flowchart LR
+    main["main.c<br/>startup + service loop"]
+
+    subgraph can["can/"]
+        bus["bus + queues"]
+        protocol["protocol codec"]
+        runtime["runtime + replay"]
+    end
+
+    subgraph rf["rf/"]
+        commands["serial commands"]
+        plan["safe planner"]
+        execute["plan executor"]
+        drivers["PE44820 + F0480 drivers"]
+    end
+
+    subgraph platform["platform/"]
+        board["board pins"]
+        support["clock, time, watchdog, faults, diagnostics"]
+    end
+
+    main --> runtime
+    main --> plan --> execute --> drivers
+    bus --> runtime --> protocol
+    runtime --> plan
+    runtime --> execute
+    plan --> commands
+    drivers --> board
+    main --> support
+    runtime --> support
+```
+
 ```text
-app/src/main.c              startup/main loop
-app/src/can_runtime.c       execution/responses/replay
-app/src/can_protocol.c      CAN codec
-app/src/can_bus.c           bxCAN transport/ISR
-app/src/can_control.c       safe operation planner
-app/src/phaseShifter.c      PE44820 driver
-app/src/vga.c               F0480 driver
-app/src/diagnostics.c       retained diagnostics
-app/src/faults.c            fault reset handlers
-tests/                      native tests
+app/src/main.c       startup and service loop
+app/src/can/         CAN hardware, codec, queues, runtime
+app/src/rf/          RF encoding, planning, execution, drivers
+app/src/platform/    board map, clock, time, faults, diagnostics
+app/include/         matching public headers
+bringup/             archived bench code and evidence; not compiled
+tests/               native unit and contract tests
 ```
 
 See [RF encoding](../docs/rf-control.md) and [hardware validation](docs/HARDWARE_VALIDATION.md).

stm32/app/Makefile

@@ -7,24 +7,25 @@ OPENCM3_DEFS := -DSTM32F0
 
 CFILES := \
 	src/main.c \
-	src/beamforming_protocol.c \
-	src/build_info.c \
-	src/can_bus.c \
-	src/can_tx_queue.c \
-	src/can_control.c \
-	src/can_filter.c \
-	src/can_protocol.c \
-	src/can_queue.c \
-	src/can_runtime.c \
-	src/clock_control.c \
-	src/diagnostic_record.c \
-	src/diagnostics.c \
-	src/faults.c \
-	src/phaseShifter.c \
-	src/spi_guard.c \
-	src/timebase.c \
-	src/vga.c \
-	src/watchdog.c
+	src/can/bus.c \
+	src/can/filter.c \
+	src/can/protocol.c \
+	src/can/runtime.c \
+	src/can/rx_queue.c \
+	src/can/tx_queue.c \
+	src/rf/commands.c \
+	src/rf/execute.c \
+	src/rf/phase_shifter.c \
+	src/rf/plan.c \
+	src/rf/vga.c \
+	src/platform/build_info.c \
+	src/platform/clock.c \
+	src/platform/diagnostic_record.c \
+	src/platform/diagnostics.c \
+	src/platform/faults.c \
+	src/platform/spi_guard.c \
+	src/platform/timebase.c \
+	src/platform/watchdog.c
 
 INCLUDES += -Iinclude
 CSTD := -std=c2x

stm32/app/include/PhaseShifter.h

@@ -1,20 +1,12 @@
 #ifndef CAN_BUS_H
 #define CAN_BUS_H
 
-#include "can_protocol.h"
+#include "can/protocol.h"
+#include "can/tx_queue.h"
 
 #include <stdbool.h>
 #include <stdint.h>
 
-/* Software TX-queue priority. Lower numeric value = higher priority. */
-typedef enum can_tx_priority {
-    CAN_TX_PRIORITY_ERROR = 0,
-    CAN_TX_PRIORITY_ACK = 1,
-    CAN_TX_PRIORITY_REQUESTED_STATUS = 2,
-    CAN_TX_PRIORITY_TELEMETRY = 3,
-    CAN_TX_PRIORITY_COUNT = 4
-} can_tx_priority_t;
-
 bool can_bus_setup(uint8_t self_node);
 bool can_bus_receive(can_frame_t *frame);
 

stm32/app/include/Vga.h

@@ -1,6 +1,8 @@
 #ifndef CAN_PROTOCOL_H
 #define CAN_PROTOCOL_H
 
+#include "rf/limits.h"
+
 #include <stdbool.h>
 #include <stdint.h>
 
@@ -25,20 +27,6 @@
 #define CAN_ID_NODE_MASK 0x1fu
 #define CAN_ID_SEQUENCE_MASK 0xffffu
 
-/*
- * BeamControl has four physical RF channels.
- *
- * CAN payload arrays use channel indexes 0..3. The PE44820 unit addresses used
- * on the receiver board are 1..4, matching the CANDev implementation.
- */
-#define CAN_RF_CHANNEL_MIN 0u
-#define CAN_RF_CHANNEL_MAX 3u
-#define CAN_RF_CHANNEL_COUNT 4u
-#define CAN_PHASE_ADDRESS_MIN 1u
-#define CAN_PHASE_ADDRESS_MAX 4u
-
-#define CAN_VGA_ATTENUATION_MAX_DB 23u
-
 #define CAN_ENTER_SAFE_LENGTH 1u
 #define CAN_SET_PHASE_INDIVIDUAL_LENGTH 2u
 #define CAN_SET_PHASE_BULK_LENGTH 4u
@@ -111,8 +99,8 @@ typedef struct can_command {
     uint16_t sequence;
 
     /* Fixed order: array index 0..3 maps to RF channel / PE44820 address 1..4. */
-    uint8_t phase_states[CAN_RF_CHANNEL_COUNT];
-    uint8_t attenuation_db[CAN_RF_CHANNEL_COUNT];
+    uint8_t phase_states[RF_CHANNEL_COUNT];
+    uint8_t attenuation_db[RF_CHANNEL_COUNT];
 
     /* Individual RF commands and ENTER_SAFE use this zero-based channel. */
     uint8_t channel;