Project Plan ============ Purpose ------- This document is the live execution plan for the MOTSEN TOOL project. It tracks the milestones, open decisions, and known risks that drive the project forward. The three project phases (MVP, Full Feature Development, Productization) and the overall scope are defined in :doc:`definition`. This document does not redefine them; it lists what must actually happen to complete each phase. Planning Approach ----------------- The plan is milestone-driven, not date-driven: * Development cadence is irregular. Calendar dates are deliberately omitted. * A phase advances only when its phase-gate milestones have status ``done``. * Later phases are intentionally lighter than Phase 1. Their milestones are placeholders that will be refined when the prior phase exits. * Open Decisions and Risks are reviewed at every phase gate. Phase Overview -------------- .. list-table:: :header-rows: 1 :widths: 15 35 50 * - Phase - Theme - Exit Gate * - Phase 1 - Proof of Concept (MVP) - End-to-end sensor health check and Rs measurement on a real motor through the web UI * - Phase 2 - Full Feature Development - Full characterization suite, FOC, second MCU platform supported * - Phase 3 - Productization - Manufacturable product with documented service and production processes Phase 1 — MVP Milestones ------------------------ Phase 1 milestones are grouped by theme. IDs are reserved with gaps so refinement does not require renumbering. Foundation ~~~~~~~~~~ .. milestone:: Dev environment baseline :id: MIL_001 :status: open :tags: foundation Toolchain, build, debug, and flash workflow are documented and reproducible from the repository. Ozone (Segger J-Link) is the canonical flashing path; S32 Flash Lite is known to silently fail on this setup and must not be used. .. milestone:: Repository structure and coding conventions :id: MIL_002 :status: open :tags: foundation Top-level repository layout, file/folder naming rules, and commit/branch conventions are agreed and recorded in the development environment documentation. .. milestone:: Documentation toolchain operational :id: MIL_003 :status: open :tags: foundation ``make html`` builds the full documentation cleanly with sphinx, sphinx-needs, and graphviz. All need types render correctly. Build instructions are documented. HAL and MCU Bring-up ~~~~~~~~~~~~~~~~~~~~ .. milestone:: HAL skeleton interfaces :id: MIL_004 :status: open :tags: hal; mcu Platform-agnostic interfaces for GPIO, UART, timer, ADC, and PWM are defined. S32K322 implementations are stubbed and link cleanly. .. milestone:: Clock tree configured and verified :id: MIL_005 :status: open :tags: hal; mcu CPU, peripheral, FlexPWM, and ADC clocks are configured and measured against expected frequencies. Clock source selection is documented. .. milestone:: UART host link bring-up :id: MIL_006 :status: open :tags: hal; mcu; comms Bi-directional UART communication is functional at the target baud rate, verified with loopback and host-side echo. .. milestone:: System tick and non-blocking timing :id: MIL_007 :status: open :tags: hal; mcu A system tick source is running. Non-blocking delay and timeout primitives are available for application code. Hardware Platform ~~~~~~~~~~~~~~~~~ .. milestone:: Eval board selected and characterized :id: MIL_008 :status: open :tags: hardware :links: DEC_001 A specific eval board is chosen and procured (closes DEC_001). Voltage range, current capability, gate-driver topology, and sensing chain are documented. .. milestone:: Safe power-up procedure :id: MIL_009 :status: open :tags: hardware; safety A bench power-up checklist exists and is followed. A current-limited supply is verified to trip before damage in fault conditions. .. milestone:: Low-side current sensing chain :id: MIL_010 :status: open :tags: hardware; sensing ADC sampling is synchronized to PWM. Scale, offset, and noise floor are calibrated against a known reference current. .. milestone:: DC-bus voltage sensing :id: MIL_011 :status: open :tags: hardware; sensing DC-bus voltage is read with documented accuracy. Under-voltage and over-voltage thresholds are enforced in firmware. .. milestone:: Three-phase PWM generation :id: MIL_012 :status: open :tags: hardware; motor Center-aligned PWM with configurable dead-time and complementary output pairs is generated and verified on an oscilloscope. .. milestone:: Hardware fault path :id: MIL_013 :status: open :tags: hardware; safety An overcurrent latch trips the PWM outputs in hardware, independently of the firmware control loop. The recovery procedure is documented. Position Sensing and First Spin ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. milestone:: Hall sensor input and decoding :id: MIL_014 :status: open :tags: position; motor Hall sensor states are captured. A 6-state decoder produces commutation sector and inferred direction. .. milestone:: Open-loop commutation spin :id: MIL_015 :status: open :tags: motor The motor spins under open-loop sinusoidal commutation on the bench with an enforced current limit. Communications and Host ~~~~~~~~~~~~~~~~~~~~~~~ .. milestone:: Framed firmware↔host protocol :id: MIL_016 :status: open :tags: comms; host :links: DEC_003 A framed protocol is defined and implemented, supporting parameter read/write and a streaming log channel (closes DEC_003). .. milestone:: Local web server scaffold :id: MIL_017 :status: open :tags: host; ui :links: DEC_002 A local web server runs on the host PC, serves static UI assets, and exposes a real-time channel (e.g. WebSocket) bridged to the firmware (closes DEC_002). .. milestone:: Web UI live plot and control panel :id: MIL_018 :status: open :tags: host; ui The browser dashboard shows live phase currents and Hall state. Parameters can be edited from the UI and applied to the firmware. First Measurements and MVP Integration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. milestone:: Sensor health check feature :id: MIL_019 :status: open :tags: measurement; mvp Phase-sequence and Hall-alignment validation runs end-to-end from the web UI on a real motor and reports pass/fail with a clear diagnostic message on failure. .. milestone:: Phase resistance (Rs) measurement :id: MIL_020 :status: open :tags: measurement; mvp The Rs measurement procedure is implemented. The result is validated against a known reference motor and falls within a documented tolerance. .. milestone:: MVP integration demo :id: MIL_021 :status: open :tags: mvp The full MVP demo runs end-to-end: connect motor, run sensor health check, run Rs measurement, view the report in the web UI. A non-author can reproduce the demo by following the documentation. Phase 2 — Full Feature Milestones --------------------------------- These milestones will be refined when Phase 1 exits. .. milestone:: Inductance estimation (Ld, Lq) :id: MIL_040 :status: open :tags: measurement .. milestone:: Back-EMF and torque constant measurement :id: MIL_041 :status: open :tags: measurement .. milestone:: Encoder support alongside Hall :id: MIL_042 :status: open :tags: position .. milestone:: CAN communication interface :id: MIL_043 :status: open :tags: comms :links: DEC_004 .. milestone:: Scriptable test automation framework :id: MIL_044 :status: open :tags: host .. milestone:: FOC closed-loop control :id: MIL_045 :status: open :tags: motor; control .. milestone:: Web UI feature-complete :id: MIL_046 :status: open :tags: host; ui .. milestone:: Parameter storage and project files :id: MIL_047 :status: open :tags: host .. milestone:: Second MCU platform supported :id: MIL_048 :status: open :tags: hal; mcu .. milestone:: Phase 2 acceptance demo :id: MIL_049 :status: open :tags: gate Phase 3 — Productization Milestones ----------------------------------- .. milestone:: Custom PCB v1 design :id: MIL_070 :status: open :tags: hardware .. milestone:: Custom PCB bring-up :id: MIL_071 :status: open :tags: hardware .. milestone:: Manufacturing test fixtures and procedures :id: MIL_072 :status: open :tags: production .. milestone:: User manual :id: MIL_073 :status: open :tags: documentation .. milestone:: Service and calibration documentation :id: MIL_074 :status: open :tags: documentation .. milestone:: Reliability and safety test campaign :id: MIL_075 :status: open :tags: production; safety .. milestone:: Pilot production run :id: MIL_076 :status: open :tags: production .. milestone:: Resolver support :id: MIL_077 :status: open :tags: position .. milestone:: Phase 3 acceptance — manufacturable product :id: MIL_078 :status: open :tags: gate Phase Gate Criteria ------------------- Phase 1 exits when: * MIL_001 through MIL_021 are all ``done``. * MIL_021 (MVP integration demo) is reproducible by a non-author. Phase 2 exits when: * MIL_040 through MIL_048 are all ``done``. * MIL_049 (Phase 2 acceptance demo) is signed off. Phase 3 exits when: * MIL_070 through MIL_077 are all ``done``. * MIL_078 (Phase 3 acceptance) is signed off, including a manufacturable build and documented production/service flows. Open Decisions -------------- .. decision:: Specific eval board model :id: DEC_001 :status: open Which off-the-shelf inverter eval board is the MVP target hardware. Constraint: must support a <100 W BLDC at 12–24 V, expose low-side current sense, and be compatible with the chosen MCU. Closes through MIL_008. .. decision:: Web server language and framework :id: DEC_002 :status: open Backend language and framework for the local web server. Candidates include Python (FastAPI), Node.js, Go, and others. Constraint: must support fast WebSocket streaming and be easy to package for a non-author end user. Closes through MIL_017. .. decision:: Host↔firmware physical link and framing :id: DEC_003 :status: open Physical link (UART vs USB-CDC) and the frame format for the host-firmware protocol. Closes through MIL_016. .. decision:: CAN priority :id: DEC_004 :status: open Whether CAN is a Phase 1 nice-to-have or strictly a Phase 2 feature. Default: Phase 2 (MIL_043). .. decision:: HAL implementation strategy :id: DEC_005 :status: open Whether the HAL wraps NXP RTD/SDK calls or is a thin custom layer over registers. Affects MCU portability cost and the work in MIL_004 and MIL_048. .. decision:: Sensorless control scope :id: DEC_006 :status: open Whether sensorless control (observer-based position estimation) is in scope, and for which phase. .. decision:: Open-source license and publication policy :id: DEC_007 :status: open License selection and whether/when the project is published publicly. Risks ----- .. risk:: Irregular cadence causes context loss :id: RISK_001 :status: open Long calendar gaps between work sessions cause loss of mental context and rework. Mitigation: every session ends with a short note in the docs capturing current state and the next concrete step. .. risk:: HAL over-engineered prematurely :id: RISK_002 :status: open The HAL is designed for portability before a second MCU exists, leading to wasted effort and brittle abstractions. Mitigation: design the HAL to the minimum needed for Phase 1; revisit at MIL_048. .. risk:: Eval board limitation forces early custom PCB :id: RISK_003 :status: open The selected eval board cannot support a measurement or feature needed in Phase 1 or Phase 2, forcing custom hardware earlier than planned. Mitigation: review board limits in MIL_008; treat custom PCB as a Phase 3 item only. .. risk:: Web-stack scope creep :id: RISK_004 :status: open Authentication, multi-user, hosting, and other web concerns expand beyond the local-tool use case. Mitigation: keep the server local-only and single-user through Phase 2. .. risk:: Characterization algorithm complexity underestimated :id: RISK_005 :status: open Parameter estimation procedures (Rs, Ld, Lq, Kt) require more signal processing and calibration than expected. Mitigation: stage the work — Rs first, then Ld/Lq, then Kt — and validate each against a reference motor. .. risk:: Documentation drift from implementation :id: RISK_006 :status: open Code and documentation drift apart, so the docs no longer describe what the project actually does. Mitigation: documentation changes ship in the same commits as the implementation changes that motivate them. .. risk:: Motor-under-test safety incident :id: RISK_007 :status: open Overcurrent, overspeed, or mechanical incidents during bench testing cause damage or injury. Mitigation: enforced current limits in firmware, hardware overcurrent latch (MIL_013), and bench safety procedures (MIL_009). Traceability ------------ Milestones in this document forward-link to system, hardware, and software requirements using the ``linked_to`` and ``implemented_by`` link types defined in the project ``conf.py``. At the time of writing these links are mostly empty; they will be populated as the requirements documents in ``02_System``, ``03_Hardware``, and ``04_Software`` come online. The intended traceability flow is: .. code-block:: text Milestone (MIL_*) │ ├── System Requirement (SYS_*) │ │ │ ├── Hardware Requirement (HW_REQ_*) │ │ └── Hardware Test Case (HW_TEST_*) │ │ │ └── Software Requirement (SW_REQ_*) │ └── Software Test Case (SW_TEST_*) │ └── Open Decisions (DEC_*) / Risks (RISK_*)