MCP Prompts Server

{
  "id": "esp32-flatbuffers-schema-sync-workflow",
  "name": "ESP32 FlatBuffers Schema Sync Workflow",
  "description": "Prevent FlatBuffers schema version mismatch errors by maintaining schema synchronization",
  "content": "# ESP32 FlatBuffers Schema Sync Workflow\n\n## Problem\nFlatBuffers schema version mismatch errors occur when schema files (.fbs) are modified but generated headers are not regenerated, or when schema and code are out of sync.\n\n## Workflow Steps\n\n### 1. Edit Schema Files\n```bash\n# Edit schema files in schemas/ directory\n# Example: schemas/BpmCommon.fbs, schemas/BpmRequests.fbs\n\n# Common changes:\n# - Add new fields to tables\n# - Add new enum values\n# - Create new table types\n# - Modify field types\n```\n\n### 2. Regenerate Headers\n```bash\n# Using flatc compiler directly\nflatc --cpp --gen-mutable --gen-object-api schemas/*.fbs -o include/\n\n# Or using project script (if available)\npython scripts/generate_flatbuffers.py\n\n# Verify generation:\n# - Check include/*_generated.h files have recent timestamps\n# - Check include/*_extracted.h for enum definitions\n```\n\n### 3. Clean Build (If Needed)\n```bash\n# Only needed if:\n# - Schema structure changed significantly\n# - Build cache issues\n# - Linker errors about missing symbols\n\npio run --target clean\n```\n\n### 4. Rebuild and Upload\n```bash\n# Build with regenerated headers\npio run --environment esp32-s3\n\n# Upload to device\npio run --environment esp32-s3 --target upload\n```\n\n## When to Regenerate\n\n### Always Regenerate When:\n- [ ] Modifying any `.fbs` schema file\n- [ ] Adding new fields to existing tables\n- [ ] Creating new table/enum types\n- [ ] Changing field types or names\n- [ ] Updating FlatBuffers version\n\n### Skip Regeneration When:\n- [ ] Only modifying C++ implementation files\n- [ ] Only changing comments in schema files\n- [ ] Only reformatting existing schema\n\n## Verification\n\n### Check Generated Files\n```bash\n# Verify headers were generated\nls -lh include/*_generated.h\nls -lh include/*_extracted.h\n\n# Check for \"generated by flatc\" comment\nhead -5 include/BpmCommon_generated.h\n# Should show: // automatically generated by the FlatBuffers compiler\n```\n\n### Build Verification\n```bash\n# Build should complete without errors\npio run --environment esp32-s3\n\n# Look for these error types (indicates sync issue):\n# - \"no member named 'X' in 'Y'\"\n# - \"FLATBUFFERS_VERSION_*\" errors\n# - \"undefined reference\" to FlatBuffers types\n```\n\n## Common Errors and Fixes\n\n### Error: \"no member named 'newField' in 'BpmRequest'\"\n**Cause**: Schema updated but headers not regenerated\n**Fix**: Run `flatc --cpp schemas/*.fbs -o include/`\n\n### Error: \"FLATBUFFERS_VERSION_MAJOR not defined\"\n**Cause**: FlatBuffers version mismatch between schema and library\n**Fix**: \n```bash\n# Check installed version\npio lib list | grep flatbuffers\n\n# Update if needed:\npio lib install \"flatbuffers@^25.12.19\"\n```\n\n### Error: \"undefined reference to 'flatbuffers::Offset'\"\n**Cause**: Missing FlatBuffers library or wrong version\n**Fix**: Verify `lib_deps` in `platformio.ini` includes flatbuffers\n\n## Project Structure\n\n```\nproject/\n├── schemas/              # .fbs schema files\n│   ├── BpmCommon.fbs\n│   ├── BpmRequests.fbs\n│   └── BpmResponses.fbs\n├── include/              # Generated headers\n│   ├── BpmCommon_generated.h\n│   ├── BpmCommon_extracted.h\n│   └── ...\n├── src/                  # Implementation using generated headers\n│   └── bpm_flatbuffers.cpp\n└── scripts/\n    └── generate_flatbuffers.py  # Optional: automation script\n```\n\n## Automation Script Example\n\n```python\n#!/usr/bin/env python3\n# scripts/generate_flatbuffers.py\n\nimport subprocess\nimport os\nfrom pathlib import Path\n\nSCHEMAS_DIR = Path(\"schemas\")\nINCLUDE_DIR = Path(\"include\")\n\n# Find all .fbs files\nfbs_files = list(SCHEMAS_DIR.glob(\"*.fbs\"))\n\nif not fbs_files:\n    print(\"No .fbs files found in schemas/\")\n    exit(1)\n\n# Build flatc command\ncmd = [\n    \"flatc\",\n    \"--cpp\",\n    \"--gen-mutable\",\n    \"--gen-object-api\",\n    *[str(f) for f in fbs_files],\n    \"-o\", str(INCLUDE_DIR)\n]\n\nprint(f\"Regenerating FlatBuffers headers from {len(fbs_files)} schemas...\")\nresult = subprocess.run(cmd, check=True)\nprint(\"✓ Headers regenerated successfully\")\n```\n\n## Best Practices\n\n1. **Version Control**: Commit both `.fbs` and generated headers\n   - Generated headers are deterministic\n   - Ensures team members have matching code\n\n2. **Pre-commit Hook**: Regenerate before committing schema changes\n   ```bash\n   # .git/hooks/pre-commit\n   #!/bin/bash\n   python scripts/generate_flatbuffers.py\n   git add include/*_generated.h include/*_extracted.h\n   ```\n\n3. **CI/CD Integration**: Regenerate in build pipeline\n   ```yaml\n   # .github/workflows/build.yml\n   - name: Generate FlatBuffers\n     run: python scripts/generate_flatbuffers.py\n   ```\n\n## Related Patterns\n\n- Use with `esp32-platformio-serial-upload-debugging` for full build workflow\n- See `mcp-server-file-storage-index-sync` for similar sync patterns\n\n## Success Metrics\n\n- **Regeneration Time**: < 5 seconds for typical schemas\n- **Build Success Rate**: 100% after regeneration\n- **Sync Accuracy**: Zero version mismatch errors",
  "isTemplate": false,
  "tags": ["embedded", "esp32", "flatbuffers", "schema", "build", "code-generation"],
  "category": "esp32",
  "version": 1,
  "createdAt": "2026-01-01T03:00:00.000Z",
  "updatedAt": "2026-01-01T03:00:00.000Z",
  "metadata": {
    "context": ["embedded", "esp32", "flatbuffers", "schema"],
    "problem": "Prevent FlatBuffers schema version mismatch errors",
    "success_count": 1,
    "confidence": "high",
    "triggers": {
      "when_to_regenerate": [
        "After modifying any .fbs schema file",
        "After changing flatbuffers version",
        "When seeing 'FLATBUFFERS_VERSION_*' errors during build"
      ]
    }
  }
}