`embgen`

Warning

This project is currently in an early development stage. While the core functionality is implemented and usable, expect breaking changes and incomplete features as we continue to develop and refine embgen.

Overview¶

embgen is a unified code generator for embedded systems that generates code from YAML definitions.

Example Use Cases¶

Embedded Device Commands: Imagine you have an embedded device that communicates with a host computer using a custom command protocol. You can define the commands in a YAML file and use embgen to generate C header files for the device firmware and Python code for the host application.

Hardware Register Maps: Define hardware register layouts in YAML and generate C headers for firmware, Python classes for testing, and Markdown documentation for reference.

Why should this be useful? One simple reason: Single Source of Truth. By defining your commands or registers in a single YAML file, you can automatically generate consistent code and documentation across multiple languages, formats and versions, reducing errors and saving development time.

flowchart TB
    subgraph DomainSub["Per Domain"]
        Domain["Domain<br>(Command Set)<br>(Register Map)"]
        Template["Template<br>_Jinja2_"]
    end
    subgraph ConfigSub["Per Run"]
        Config["Config<br>_YAML_"]
    end

    CodeGen["Code Generator"]
    Output["Generated Files<br>_Any Format_"]

    Domain --> |"Describe Data Structure"| CodeGen
    Template --> |"Describe Output Formatting"| CodeGen
    Config --> |"Describe Content"| CodeGen

    CodeGen --> |"Generates"| Output

Design Philosophy¶

This package is designed with a modular architecture that allows easy extension through custom domains and templates.

You can think of a Domain as a plugin that knows how to interpret a specific type of YAML definition (e.g., command protocols, register maps) and generate code in various formats (C headers, Python, Markdown, etc.) using Jinja2 templates.

Quick Start¶

Installation¶

# Using uv (recommended)
uv sync

# Or with pip
pip install -e .

Generate Code¶

# Generate C header from a commands definition
embgen commands config.yml -o output/ --h

# Generate multiple formats at once
embgen commands config.yml -o output/ --h --py --md

# Auto-detect the domain type
embgen auto config.yml -o output/ --h

Built-in Domains¶

embgen ships with two built-in domains:

Domain	Description	Output Formats
Commands	Command protocol definitions	C Header, Python, Markdown
Registers	Hardware register maps	C Header, Python, Markdown

Documentation¶

You can view the full documentation on github.io. The documentation includes:

CLI Usage: Complete command-line reference
Python API: Using embgen as a library
Built-in Domains: Commands and Registers documentation
Creating Domains: How to create custom domains
Architecture: Internal design and module structure

License¶

This project is licensed under the MIT License - see LICENSE for details.