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 Project 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¶
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¶
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. |
Top-level repository layout, file/folder naming rules, and commit/branch conventions are agreed and recorded in the development environment documentation. |
|
HAL and MCU Bring-up¶
Platform-agnostic interfaces for GPIO, UART, timer, ADC, and PWM are defined. S32K322 implementations are stubbed and link cleanly. |
CPU, peripheral, FlexPWM, and ADC clocks are configured and measured against expected frequencies. Clock source selection is documented. |
Bi-directional UART communication is functional at the target baud rate, verified with loopback and host-side echo. |
A system tick source is running. Non-blocking delay and timeout primitives are available for application code. |
Hardware Platform¶
A specific eval board is chosen and procured (closes DEC_001). Voltage range, current capability, gate-driver topology, and sensing chain are documented. |
A bench power-up checklist exists and is followed. A current-limited supply is verified to trip before damage in fault conditions. |
ADC sampling is synchronized to PWM. Scale, offset, and noise floor are calibrated against a known reference current. |
DC-bus voltage is read with documented accuracy. Under-voltage and over-voltage thresholds are enforced in firmware. |
Center-aligned PWM with configurable dead-time and complementary output pairs is generated and verified on an oscilloscope. |
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¶
Hall sensor states are captured. A 6-state decoder produces commutation sector and inferred direction. |
The motor spins under open-loop sinusoidal commutation on the bench with an enforced current limit. |
Communications and Host¶
A framed protocol is defined and implemented, supporting parameter read/write and a streaming log channel (closes DEC_003). |
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). |
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¶
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. |
The Rs measurement procedure is implemented. The result is validated against a known reference motor and falls within a documented tolerance. |
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.
Phase 3 — Productization Milestones¶
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¶
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. |
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. |
Physical link (UART vs USB-CDC) and the frame format for the host-firmware protocol. Closes through MIL_016. |
Whether CAN is a Phase 1 nice-to-have or strictly a Phase 2 feature. Default: Phase 2 (MIL_043). |
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. |
Whether sensorless control (observer-based position estimation) is in scope, and for which phase. |
License selection and whether/when the project is published publicly. |
Risks¶
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. |
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. |
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. |
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. |
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. |
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. |
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:
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_*)