Software Actuation Module Design Spec

Enigma-NG Software Design: Actuation Module Firmware

Status: Draft Version: v.0.1.0 Associated Hardware Revision: Rev A Last Updated: 2026-04-26

1. Overview

The Actuation Module (AM) firmware is a small single-purpose bare-metal STM32 application for the AM hardware defined in [[design/Electronics/Actuation_Module/Design_Spec.md|Electronics-Actuation-Module-Design-Spec]]. It is not a general host coprocessor and it does not need a command protocol, field bus, or persistent telemetry channel.

Its responsibilities are to:

• initialise the local AM hardware safely
• home the servo at power-up
• watch one host request input plus one local home-switch input
• generate one deterministic single-step servo cycle for each valid request
• expose simple local diagnostics on PWR, HOMED, and ACT

The selected controller is STMicroelectronics STM32G071K8T3TR. The firmware should use a simple cooperative main loop driven by a millisecond tick plus at least one hardware timer for servo PWM generation. An RTOS is unnecessary for Rev A.

2. Boot and Programming Paths

The STM32 on the AM has three relevant boot / service paths:

1. Normal application boot
   • Default path used in service
   • BOOT0 remains LOW at reset release
   • The user firmware starts and performs the AM startup / homing sequence
2. SWD debug / programming path
   • Accessed through J4 on the AM hardware
   • Used for normal firmware flashing, debug, recovery, and bring-up
   • This path does not depend on the UART header or button sequence
3. STM32 ROM UART bootloader path
   • Accessed through J5 plus SW1 / SW2 on the AM hardware
   • This bypasses the AM application firmware and enters the STM32's built-in ROM bootloader
   • Use this only when an ad-hoc UART flashing path is desired or when SWD is unavailable

3. UART Bootloader Operator Sequence

The user-facing UART bootloader sequence shall be documented and supported exactly as follows:

1. Connect the UART adapter to J5:
   • J5 pin 1 = GND
   • J5 pin 2 = 3V3_ENIG reference
   • J5 pin 3 = UART_TX from the AM
   • J5 pin 4 = UART_RX into the AM
2. Press and hold SW2 to assert BOOT0
3. Press and release SW1 to pulse NRST
4. Release SW2 after reset
5. The STM32 then remains in the ROM bootloader until the next reset or power cycle with BOOT0 LOW

Important behavior note: in user/operator terms, BOOT0 is a momentary action with a timing constraint, not a latched mode switch. In electrical terms, the firmware design shall assume only that BOOT0 must be valid at the STM32 boot-mode sample point during reset release.

4. Firmware Operating Model

The AM firmware shall implement this logical state machine:

State	Entry condition	Outputs / actions	Exit condition
BOOT_INIT	MCU exits reset into user firmware	Configure clocks, GPIO, timer PWM, tick timer, and default-safe outputs; LED PWR=ON, HOMED=OFF, ACT=OFF	Initialization complete
HOME_SEEK	BOOT_INIT complete	Drive servo toward the defined home direction / position until the home switch is detected or timeout expires	Home switch valid -> IDLE_HOMED; timeout/fault -> FAULT
IDLE_HOMED	Successful homing	Servo held at home; PWR=ON, HOMED=ON, ACT=OFF; watch ACTUATE_REQUEST_N	Valid request edge -> ACTUATE_CYCLE
ACTUATE_CYCLE	Request accepted	Latch one cycle, set ACT=ON, drive the servo through the programmed one-shot motion profile	Cycle complete -> WAIT_FOR_RELEASE
WAIT_FOR_RELEASE	Cycle complete	Return servo to home / idle position, ACT=OFF; ignore repeated triggers while request is still asserted	Request released -> IDLE_HOMED
FAULT	Home timeout, impossible input condition, or firmware-detected unrecoverable error	Motion output driven to safe idle; PWR=ON, HOMED=OFF, ACT indicates fault pattern if desired	Reset or power cycle

This state machine is intentionally conservative:

• no repeated actuation is permitted from a held-low request
• no host-side feedback wire is required
• no request is serviced before homing has completed
• any unsafe or ambiguous startup condition resolves to no motion

5. Signal Ownership and Firmware I/O Contract

Logical signal	Direction at MCU	Firmware use
ACTUATE_REQUEST_N	Input	Debounced / qualified active-low request from host; bias = STM32 internal pull-up (PUPDR = 0b01) configured by firmware - no external resistor fitted
ACTUATION_HOME_N	Input	Debounced active-low home confirmation
SERVO_PWM	Output	50 Hz-class servo pulse train generated by timer hardware
LED_PWR	Output	ON whenever firmware has completed basic boot initialization
LED_HOMED	Output	ON only when the module is in a successfully homed ready state
LED_ACT	Output	ON during an accepted actuation cycle; optional blink pattern in FAULT
BOOT0	Service input	Not used during normal application runtime; only relevant at reset / ROM bootloader entry
NRST	Service input	External reset path via SW1 / J4

The exact STM32 pad mapping may still be finalized during schematic capture, but the firmware design shall preserve these logical roles exactly.

ACTUATE_REQUEST_N pull-up configuration: The ACTUATE_REQUEST_N pull-up is provided solely by the STM32 internal GPIO pull-up (PUPDR = 0b01). No external pull-up resistor is fitted on the hardware - the internal pull-up is the authoritative pull-up source. The firmware shall enable the internal pull-up (PUPDR register = 0b01) before the GPIO is sampled or the debounce routine starts.

6. Startup and Homing Behavior

At application boot, the firmware shall:

1. start with servo output in a safe idle configuration
2. wait a short stabilization interval for power and GPIO state to settle
3. sample the home input with debounce / qualification
4. if already home, declare success without unnecessary movement
5. otherwise drive the servo in the homing direction until home is detected
6. stop motion immediately once home is confirmed
7. enter FAULT if home is not reached within the defined timeout window

Implementation notes:

• The home-switch input should be digitally filtered rather than acted on from a single raw sample.
• The firmware should avoid continuous hunting around the home point.
• Rev A should prefer deterministic fixed timing and fixed pulse widths over adaptive or learning behavior.

7. Actuation-Cycle Behavior

Each accepted request shall produce exactly one cycle:

1. detect a valid active-low request after debounce / qualification
2. latch the request internally
3. ignore further request changes until the cycle completes
4. move the servo from home to the actuation position
5. hold for the required dwell interval
6. return the servo to the home / idle position
7. require request release before a new cycle can be armed

The firmware shall treat ACTUATE_REQUEST_N as an edge-qualified one-shot trigger, not as a continuous command input.

8. Timing and Configuration Parameters

Rev A firmware should keep these values as named constants or a compact configuration structure:

Parameter	Purpose
startup_settle_ms	Delay after reset before input qualification begins
input_debounce_ms	Digital qualification window for ACTUATE_REQUEST_N and ACTUATION_HOME_N
servo_pwm_period_us	Servo PWM period, typically around 20 ms
servo_home_pulse_us	Timer compare value for home position
servo_actuate_pulse_us	Timer compare value for actuated position
servo_travel_time_ms	Time allowed for each movement leg
servo_dwell_ms	Hold time at the actuated position
homing_timeout_ms	Maximum time allowed for initial home acquisition

These parameters do not need a runtime user interface in Rev A; compile-time constants are acceptable.

9. Diagnostics and Fault Indication

The firmware shall drive LEDs as follows:

Condition	PWR	HOMED	ACT
MCU initialized, not yet homed	ON	OFF	OFF
Homed and ready	ON	ON	OFF
Active cycle in progress	ON	ON	ON
Fault / homing timeout	ON	OFF	Blink or steady ON per final implementation

If a distinct fault blink pattern is used on ACT, it should be implemented in firmware with a simple non-blocking tick-based pattern rather than delay loops.

10. Implementation Guidance for Firmware Bring-Up

For the first STM32 firmware revision, implement in this order:

1. clock tree, GPIO defaults, and LED sanity test
2. hardware timer PWM generation on SERVO_PWM
3. input sampling / debounce for ACTUATION_HOME_N and ACTUATE_REQUEST_N
4. startup homing state machine
5. one-shot actuation state machine
6. fault handling and final LED behavior
7. optional UART debug prints during bench bring-up only

The release firmware should not depend on a UART console being connected.