⚡ ansv-haptics-sim

🚀 A minimal, zero-dependency 2nd-order damped harmonic oscillator solver for haptic actuator physics & motor 5 key parameters.
专为硬件工程师和算法开发者打造的轻量级触觉马达（LRA / VCM）二阶物理求解器与动态位移仿真引擎。

English | 简体中文 | 🌐 🚀 Online Live Studio Demo

---

📈 Interactive Simulation Preview

• 🌐 Interactive Web Studio: Open docs/index.html or visit Online Live Studio Demo to tweak parameters in real-time with synchronized 2D haptic motor physics animation!

Below is the dynamic simulation generated by ansv-haptics-sim showing a full haptic actuator lifecycle (Transient Rise $\rightarrow$ Extended Steady-State $\rightarrow$ Cutoff Ring-down Decay):

---

📌 Overview & Developer Note

ansv-haptics-sim is a lightweight, open-source 2nd-order harmonic oscillator solver for educational demonstration and haptic actuator physics modeling.

🛠️ Developer Note:
My primary engineering stack for industrial simulation and data acquisition has historically been LabVIEW. As an individual developer with limited bandwidth, I am currently learning and exploring JavaScript for Web-based physics visualization in my spare time. I will refine and update this open-source repository as time permits. Community contributions and feedback are warmly welcome!

🌐 Feel free to check out my open lab page at ansv.net/simulations/ for more simulation demos.

---

🔬 Physics Model & Motor 5 Key Parameters

The system dynamics are governed by the 2nd-order linear differential equation:

$$m \cdot \frac{d^2x}{dt^2} + c \cdot \frac{dx}{dt} + k \cdot x = F(t) = BL \cdot I(t)$$

Parameter	Symbol	Description	Default Value	Unit
mass	$m$	Moving Mass	0.0015 (1.5g)	$\text{kg}$
stiffness	$k$	Spring Stiffness	800	$\text{N/m}$
damping	$c$	Damping Coefficient	0.10	$\text{N}\cdot\text{s/m}$
bl	$BL$	Force Factor / BL Product	1.2	$\text{N/A}$ or $\text{T}\cdot\text{m}$
current	$I$	Drive Current Peak	0.4	$\text{A}$ (Ampere)

Derived Key Metrics:

• Resonant Frequency ($f_0$): $$f_0 = \frac{1}{2\pi}\sqrt{\frac{k}{m}} \quad (\text{Hz})$$

• Acceleration Response ($a$): $$a(t) = \frac{d^2x/dt^2}{9.81} \quad (\text{G})$$

---

🎛️ Motor Control & Haptic Drive Strategies [Planned]

🛠️ Roadmap Note:
The following advanced Motor Control algorithms and simulation features are currently [Under Active Development / Planned], and will be rolled out in upcoming releases:

1. 🔄 [Planned] Overdrive Control (Fast Transient Rise): Applies a higher-than-rated drive voltage/current during the initial phase (first 10–20ms) to accelerate kinetic energy accumulation, significantly shortening the transient rise time.

2. 🔄 [Planned] Active Braking (Active Deceleration): Applies a 180° phase-inverted braking pulse at the end of the haptic effect to actively counteract kinetic energy, reducing ring-down decay time by >60% for a crisp "button-click" feel.

3. 🔄 [Planned] Closed-Loop Resonance Tracking (Auto-Resonance): Monitors Back-EMF or current phase angle to dynamically adjust drive frequency, keeping the actuator locked exactly at its measured resonant frequency ($f_0$).

---

🔄 Core Numerical Solver Architecture

To illustrate the underlying data flow and Euler numerical integration loop of the physics engine, below is the core execution flowchart of ansv-haptics-sim:

flowchart TD
    A[1. Initialize Actuator Params m, k, c, BL] --> B[2. Import Drive Waveform I t]
    B --> C[3. Init Physical State x=0, v=0]
    C --> D[4. Enter Time-step Loop dt]
    D --> E["5. Compute Lorentz Force: F = BL * I(t)"]
    E --> F["6. Compute Acceleration: a = (F - c*v - k*x) / m"]
    F --> G["7. Integrate Velocity: v = v + a*dt"]
    G --> H["8. Integrate Displacement: x = x + v*dt"]
    H --> I{9. Reached Stop Time?}
    I -- No --> D
    I -- Yes --> J["10. Export Time-Domain Data (x, v, a)"]

Loading

Figure 2: ansv-haptics-sim Numerical Integration Solver Flowchart.

---

🚀 Quick Start & Usage

# Run unit tests
npm test

# Generate SVG simulation graph (Supports English & Chinese CLI output)
npm run build:svg

# Run with custom parameters & English terminal CLI output
node generate_svg.js --lang=en --mass=0.002 --stiffness=950 --bl=1.5 --current=0.5

# Run with Chinese terminal CLI output
node generate_svg.js --lang=zh --mass=0.002 --stiffness=950

JavaScript API Usage

const { solveBasicDampedOscillator } = require('./index');

// Define custom motor parameters:
const myMotorParams = {
  mass: 0.0015,       // Mass m = 1.5g (0.0015 kg)
  stiffness: 800,     // Stiffness k = 800 N/m
  damping: 0.10,      // Damping c = 0.10 Ns/m
  bl: 1.2,            // BL = 1.2 N/A
  current: 0.4,       // Current I = 0.4 A
  driveType: 'ac',    // 'ac' for sine wave drive, 'dc' for step drive
  driveDuration: 0.20 // 200ms power-on duration
};

// Solve 260ms simulation (0.1ms step size)
const res = solveBasicDampedOscillator(myMotorParams, 0.260, 0.0001);

console.log(`📌 Resonant Frequency (f0): ${res.f0Hz} Hz`);
console.log(`📈 Steady-State Amplitude: ±${Math.max(...res.displacement.slice(600, 1800))} mm`);

---

🤝 Links & Personal Tech Channels

• 🌐 Personal Tech Website: https://ansv.net
• 📱 WeChat Official Account: 【ANSV微型执行器】
• 💡 Zhihu Column: Zhihu@ansv-net

---

📜 Release History

• v1.2.1 (2026-08-20)

  • 🎨 Web Live Studio UI & High-DPI Polish: Sleek dark mode visual overhaul, custom glow sliders, responsive mobile layout, and sharp High-DPI canvas rendering.
  • ⏯️ Playback Controls: Added Play/Pause and Re-trigger controls for waveforms and spring-mass dynamics.
  • 📱 Mobile Responsiveness: Optimized touch targets and adaptive stats grid for smartphone displays.

• v1.2.0 (2026-07-31)

  • 🌐 Launched Zero-Dependency Web Live Studio (docs/index.html).
  • 🎛️ Real-Time Parameter Tuning & i18n: Interactive Web UI with Chinese/English language toggle, sliders to dynamically tweak $m, k, c, BL, I$ and instantly recompute waveforms.
  • 🧲 2D Haptic Motor Motion Simulation: Added synchronized 2D spring and moving mass physics animation in Canvas.
  • 🎯 Presets: One-click switching between Standard LRA, Heavy VCM, High Damping Fast Cutoff, and Soft Spring Ring-down.

• v1.1.0 (2026-07-31)

  • 🔄 Added Mermaid flowchart for core numerical integration solver architecture.
  • ⚡ Implemented AC sine resonance drive & full haptic lifecycle (Rise $\rightarrow$ 200ms Steady-State $\rightarrow$ Ring-down).
  • 🎨 Added --lang=zh/en CLI flag and clip-path sequential SVG vector wave renderer.
  • 🛠️ Updated MIT License and personal developer background notes.

• v1.0.0 (2026-07-30)

  • 🎉 Initial open-source release: Minimal 2nd-order forced damped harmonic oscillator solver ($m, k, c, BL, I$ motor 5 key parameters).

---

📜 License

MIT License © 2026 ansv.net