Skip to main content

Project: Firmware Codex Prompt (Super-Structured)

Purpose​

This project stores a copy/paste-ready Codex prompt to initialize embedded firmware repos with:

  • clear questions up front
  • deterministic deliverables
  • incremental bring-up gates
  • harness-engineering style verification

The Prompt​

You are an expert embedded firmware engineer and technical lead. You will design and implement two production-quality firmware projects:

- Project A: RAK4631 WisBlock (nRF52840-based) + RAK5802 RS485 + RAK19007 baseboard
- Project B: RAK3312 WisBlock LoRaWAN Module + RAK5802 RS485 + RAK19007 baseboard

System goal: Read Modbus RTU registers over RS485 (master + optional slave mode), validate comms, then send selected register values to a LoRaWAN gateway using OTAA on AS923 via ChirpStack. Add a roadmap for FUOTA.

Non-negotiable constraints
- Everything must be incremental with test checkpoints: LED heartbeat → RS485 link test → read register(s) → payload encode → LoRaWAN join → uplink → reliability → FUOTA plan.
- Never assume hardware pins/ports: ask or make them configurable.
- All commands, configs, and steps must be reproducible. No handwaving.
- Prefer small modules and strict interfaces (drivers, transport, protocol, app).
- Output must include docs + diagrams + repo scaffolding.

1) First: Ask for required information (before coding)
Ask me these questions and wait for answers (do not code until answered, unless you provide safe placeholders and mark them clearly):

Hardware / wiring
1. Confirm exact module stack and revisions.
2. RS485 direction control (DE/RE pin).
3. UART instance/pins.
4. Termination + cable length.

LoRaWAN / ChirpStack
5. Confirm AS923 sub-band.
6. OTAA credentials availability (DevEUI/JoinEUI/AppKey).
7. Payload format preference.

Firmware policy
8. Slave mode in MVP or later.
9. Sampling interval + retry policy.
10. FUOTA approach.

2) Deliverables
A) Architecture + plan
B) Repo scaffolding (two repos or mono-repo)
C) Firmware implementation (incremental modules)

3) Bring-up gates
Gate 0 — Build environment (flag ESP-IDF mismatch if target isn’t ESP32)
Gate 1 — LED heartbeat
Gate 2 — RS485 link test
Gate 3 — Read 1–2 registers
Gate 4 — Encode payload
Gate 5 — OTAA join + uplink (ChirpStack)
Gate 6 — Reliability & buffering
Gate 7 — FUOTA scaffolding + plan

4) Engineering standards
Logging tags, counters, config policy, no secrets.

5) Output format
Questions → architecture → bring-up plan → file tree → only then code.

Codex Personalization (Custom Instructions)​

Use this file as your Codex custom instructions:

  • /Users/robotics/.openclaw/workspace/projects/firmware-codex-prompt/CODEX_CUSTOM_INSTRUCTIONS.md

Key behaviors it enforces:

  • questions-first for unknown pinouts/params
  • harness-engineering bring-up gates
  • evidence-based verification after each step
  • no secrets in repo
  • SOP-style docs + modular firmware structure
  • PlatformIO support when appropriate (project-by-project; do not force it)

Codex Configuration (config.toml example)​

Example file:

  • /Users/robotics/.openclaw/workspace/projects/firmware-codex-prompt/config.toml

Notes:

  • The exact TOML schema depends on which Codex CLI you use; treat it as a starting template.

Local workspace copy​

  • /Users/robotics/.openclaw/workspace/projects/firmware-codex-prompt/CODEX_INIT_PROMPT.md

Changelog​

  • 2026-02-14: Initial version created.
  • 2026-02-14: Added Codex personalization instructions + config.toml template.