Guide for developers and AI agents working on the 3D Pen project.

• Obsidian — for navigating the knowledge vault
• Git — version control
• GitHub CLI (gh) — for PR workflows

• KiCad 8+ — schematic capture and PCB layout
• Fusion 360 — mechanical CAD and simulation
• nRF Connect SDK — firmware development (Zephyr RTOS)
• PyTorch — ML model training
• Rust + Tauri — host application

# Clone
git clone https://github.com/Bunty9/3d-pen.git
cd 3d-pen

# Open the vault in Obsidian
# File → Open Vault → select the docs/ folder

# Navigate from Home.md or 01-Project/3d-pen-MOC.md

The docs/ directory is an Obsidian vault. All project knowledge lives here.

Every vault note must have YAML frontmatter:

---
title: "Note Title"
domain: "hardware"          # hardware | embedded | ml | software | meta
status: "draft"             # draft | review | final
created: "2026-02-21"
updated: "2026-02-21"
author: "hardware-agent"    # agent name or human name
tags:
  - research
  - hardware
  - sensors
related:
  - "[[other-note]]"
---

• Use [[wikilinks]] for internal references
• Use [[path/to/note|Display Name]] for cross-folder links
• Never use raw file paths in note content
• External URLs go in the ## References section at the bottom

• Lowercase, hyphen-separated: sensor-selection.md, flex-pcb-design.md
• No spaces, no special characters
• Descriptive names that indicate the note's primary topic

1. Vision — understand the product concept
2. Requirements — functional and non-functional requirements
3. Architecture — system design and data flow
4. Hardware Design Spec — physical geometry and materials
5. SOP-0001: Vault Contribution — rules for writing notes
6. SOP-0002: Multi-Agent Orchestration — agent roles and write scopes

Before working on a domain task, load the relevant context bundle from CLAUDE.md:

• Hardware Context — pen geometry, component selections, flex PCB constraints
• Embedded Context — MCU specs, wireless protocol math, firmware architecture
• ML Context — model architecture, dataset info, inference latency targets
• Software Context — HID protocol, virtual device creation, canvas rendering

1. Copy 08-Templates/_research-note.md as your starting template
2. Fill in all frontmatter fields (domain, status, author, tags)
3. Write all sections: Summary, Context, Key Findings, Relevance, Open Questions, Recommendations, References
4. Include at least 3 references with URLs
5. Update 01-Project/3d-pen-MOC.md with a link to your new note
6. Commit with format: docs({domain}): {description}

docs(hardware): add flex PCB bend radius analysis
docs(embedded): update MCU selection with nRF5340 comparison
docs(ml): add REWI architecture deep-dive
docs(project): update requirements with latency budget
docs(meta): update MOC with new research links

• Schematic capture in KiCad 8
• Flex PCB layout following IPC-2223 bend radius rules
• Component placement must follow the zone map in hardware-design-spec.md
• DFM check with JLCPCB flex PCB capabilities
• Mechanical CAD in Fusion 360 (pen shell, inner shell, nib section)

• Firmware in C using Zephyr RTOS via nRF Connect SDK
• Build with west build, flash with west flash
• Primary reference: Nordic nRF Desktop application
• DMA-driven ADC for sensor acquisition
• ESB wireless protocol at 2Mbps

• PyTorch for model training
• DVC for data versioning
• OnHW dataset as initial training data (100Hz, needs upsampling for 8kHz)
• ONNX Runtime for desktop inference
• Target: <10ms inference latency

• Host app in Rust + Tauri
• HIDAPI for USB dongle communication
• Virtual HID device per OS (uhid on Linux, VHF on Windows, IOHIDUserDevice on macOS)
• Pointer Events API for canvas rendering

# Check vault health (broken wikilinks)
grep -r '\[\[' docs/ | grep -v node_modules | grep -oP '\[\[([^\]]+)\]\]' | sort -u

# Count documents by domain
find docs/02-Research -name '*.md' | wc -l

# Check frontmatter completeness
grep -rL '^---' docs/02-Research/

# View git history for a domain
git log --oneline -- docs/02-Research/hardware/

# Search across all research notes
grep -ri "ICM-42688" docs/02-Research/

The project supports AI-assisted development via MCP servers:

• embedded-debugger-mcp — Flash firmware, read registers, RTT logging on physical hardware
• mcp-gdb — Source-level debugging via GDB
• MCP Inspector — Visual testing of MCP servers

See docs/02-Research/embedded/open-source-firmware.md for configuration details.