PAT (Pointing, Acquisition, Tracking) Firmware

Embedded firmware for a laser communication tracking system on PolarFire SoC Discovery Kit.

Hardware & setup

Board: PolarFire SoC Discovery Kit (MPFS095T)

• IP: root@192.168.8.100 (default; board on 192.168.8.x subnet)
• SSH from WSL: wsl -d Ubuntu -- ssh root@192.168.8.100 "cmd" ✓
• SSH from Windows: Windows OpenSSH 9.5 has MAC mismatch with board 9.6; use WSL or add StrictKeyExchange no to ~/.ssh/config

Yocto SDK (build, don't download):

Microchip doesn't ship a standalone SDK. Build with Yocto v2025.03 (2–4 hours, ~30 GB):

mkdir -p ~/yocto-mpfs-2025.03
cd ~/yocto-mpfs-2025.03
repo init -u https://github.com/polarfire-soc/polarfire-soc-yocto-manifests.git -b 2025.03 -m default.xml
repo sync -j4
source meta-polarfire-soc-yocto-bsp/polarfire-soc_yocto_setup.sh -b build -m mpfs-disco-kit
source openembedded-core/oe-init-build-env build
bitbake core-image-minimal-dev -c populate_sdk
# Then from this repo:
bash scripts/wsl/finish_yocto_sdk_install.sh
# Install completes to /opt/oecore-x86_64; prints environment-setup-* path

See .cursor/skills/polarfire-soc-setup/SKILL.md for detailed 5-step guide.

Project layout

PAT_polarfire/
├── README.md                # This file
├── .cursor/
│   └── rules/
│       └── embedded-firmware-pat.md  # AI guidance for this project
├── firmware/                # PAT controller, QPD, MEMS, camera modules
├── drivers/                 # SPI, I2C, GPIO (board-specific)
├── examples/                # Standalone test programs
├── configs/                 # Board pinouts, tracking parameters
├── docs/                    # Design and implementation docs
├── scripts/
│   ├── build.sh            # Main build + deploy script
│   ├── deploy/deploy.sh    # Manual scp deploy
│   ├── debug/gdb_remote.sh # Remote GDB
│   └── wsl/finish_yocto_sdk_install.sh  # SDK installer helper
├── build/                   # Compiled binaries (gitignored)
├── tests/                   # Unit & integration tests
├── tools/                   # Diagnostics, calibration scripts
└── tasks/
    ├── todo.md             # Session checklist
    └── lessons.md          # Accumulated rules

Development cycle

# 1. Source SDK env
source /opt/oecore-x86_64/environment-setup-riscv64-oe-linux

# 2. Edit (firmware/, drivers/, examples/, configs/)
$EDITOR firmware/my_module.c

# 3. Build & deploy (auto via WSL SSH)
./scripts/build.sh

# 4. Run on board
wsl -d Ubuntu -- ssh root@192.168.8.100 "./build/my_binary"

# 5. Verify output / behaviour
# (Check logs, ADC values, LED, sensor reads, etc.)

See .cursor/AGENTS.md for detailed workflow modes (planning, execution, debugging).

SSH to board

From WSL (works):

wsl -d Ubuntu -- ssh root@192.168.8.100 "uname -a"

From Windows PowerShell:

• Windows OpenSSH 9.5 has a MAC negotiation issue with board OpenSSH 9.6.
• Workaround: Use WSL SSH (recommended) or add StrictKeyExchange no to ~/.ssh/config.

Build output

• Binaries → build/ (gitignored)
• Logs → build/bitbake.log (if building SDK)

References

• AI guidance — .cursor/AGENTS.md (modes, workflow, build cycle, SSH)
• Project rules — .cursor/rules/embedded-firmware-pat.md (code style, verification, patterns)
• Setup — .cursor/skills/polarfire-soc-setup/SKILL.md (Yocto SDK build, 5 steps)
• Board pinout — configs/board/GPIO_PINOUT.md (interface mapping references)

Documentation

See docs/ folder:

• docs/CODEBASE_ANALYSIS.md — Reference codebase structure and data flow
• docs/INTERFACE_USAGE_PATTERNS.md — SPI/UART/I2C/GPIO usage patterns
• docs/NUCLEO_SPI6_BRIDGE.md — PolarFire host wiring + probe/runbook for NUCLEO SPI6 streaming

See also:

• tasks/todo.md — Current session checklist
• tasks/lessons.md — Rules to remember

Contributing

1. Create a task in tasks/todo.md for non-trivial work.
2. Follow .cursor/rules/embedded-firmware-pat.md for code style and workflow.
3. Update tasks/lessons.md after learning something new.
4. Commit with clear messages (e.g., "Add SPI driver", "Fix GPIO interrupt").

License

(Add license if applicable, e.g. MIT, Apache 2.0, or project-specific.)