fwkit 0.1.0

Firmware Development Toolkit - Build, generate, and manage embedded projects

fwkit

Firmware Development Toolkit - Automate embedded firmware builds, code generation, and project management.

🎯 What is fwkit?

fwkit is a command-line toolkit that automates repetitive tasks in embedded firmware development. Instead of manually managing build configurations, generating boilerplate code, or maintaining multiple hardware variants, fwkit handles it for you.

Current focus: Texas Instruments microcontrollers (CC13xx, CC26xx series)
Architecture: Designed to support multiple vendors (STM32, ESP32, Nordic, etc.) in the future

🚀 What Can It Do?

✅ Available Now

1. Generate Version Headers from Git

# Automatically create version.h from your Git tags and commits
fwkit codegen version --output src/version.h

# Creates:
#define VERSION "1.2.3"
#define VERSION_MAJOR 1
#define VERSION_MINOR 2
#define GIT_COMMIT "a1b2c3d"
#define BUILD_DATE "2026-02-15"

Use in your firmware to display version info, track releases, and debug builds.

2. Generate TI Code Composer Studio Projects

# Generate .projectspec files from YAML configuration
fwkit ti ccs generate --platforms platforms.yaml --output projects/

# Supports:
# - Multiple hardware variants (CC2652R1, CC2652R7, CC2651R3, etc.)
# - Different build configurations (Debug/Release)
# - Custom compiler/linker flags per platform
# - Batch generation for CI/CD

Perfect for projects targeting multiple hardware revisions or product variants.

3. Import Projects into CCS Workspace

# Import .projectspec into Code Composer Studio workspace
fwkit ti ccs import --projectspec my_project.projectspec \
  --workspace ~/ccs-workspace

# CCS CLI path auto-detected from CCS_SERVER_CLI env var
# or common installation paths

Automate project setup without manual IDE clicks.

4. Build TI CCS Projects

# Headless builds without opening CCS IDE
fwkit ti ccs build --project my_project --workspace ~/ccs-workspace

# Build specific configuration
fwkit ti ccs build --project my_project -w ~/ccs-workspace --config Release

# Clean build
fwkit ti ccs build --project my_project -w ~/ccs-workspace --type clean

Enable CI/CD builds and automated testing.

🚧 Coming Soon

5. Flash & Debug (Planned)

# Flash firmware to device
fwkit ti ccs flash --platform cc26x2r1 --file firmware.hex

# Launch debugger
fwkit ti ccs debug --platform cc26x2r1

5. Project Initialization (Planned)

# Bootstrap new projects from templates
fwkit project init my-ble-sensor \
  --vendor ti \
  --platform cc26x2r1 \
  --template ble-peripheral

📦 Installation

pip install fwkit

💡 Real-World Example

Imagine you have a product line with 6 different hardware variants (different MCUs, different peripherals). Instead of maintaining 6 separate CCS projects by hand:

# platforms.yaml
defaults:
  compiler_version: "4.0.4.LTS"
  compiler_build_options:
    - "-O2"
    - "-gdwarf-3"

cc26x2r1_basic:
  platform: "cc26x2r1_basic"
  device: "Cortex M.CC2652R1F"
  project_name: "sensor_cc26x2r1"

cc26x2r7_advanced:
  platform: "cc26x2r7_advanced"
  device: "Cortex M.CC2652R7"
  project_name: "sensor_cc26x2r7"
  compiler_build_options:
    - "-DHAS_EXTRA_MEMORY"

Then generate all projects:

fwkit ti ccs generate --platforms platforms.yaml --subdirs

Result: 6 ready-to-import .projectspec files, automatically configured, in seconds.

🎯 Why fwkit?

Problem: Managing embedded projects involves:

• Manually configuring IDEs for each hardware variant
• Copy-pasting build settings between projects
• Keeping version numbers in sync across files
• Maintaining separate projects for Debug/Release builds

Solution: Define your configuration once in YAML, generate everything automatically.

Benefits:

• ✅ Reproducible builds - Configuration in version control
• ✅ Faster onboarding - New developers run one command
• ✅ CI/CD ready - Automated project generation and builds
• ✅ Less errors - No manual copy-paste mistakes
• ✅ Multi-platform - Manage 10 hardware variants as easily as 1

📖 Quick Start Guides

Generate Version Headers

# In your firmware repository with Git tags
git tag -a v1.0.0 -m "Release 1.0.0"

# Generate version.h
fwkit codegen version --output src/version.h

# Use in your code
#include "version.h"
printf("Firmware version: %s\n", VERSION);

Generate TI CCS Projects

1. Create platforms.yaml:

defaults:
  compiler_version: "4.0.4.LTS"
  
my_platform:
  platform: "my_platform"
  project_title: "My Project"
  project_name: "my_project"
  device: "Cortex M.CC2652R1F"
  link_file_path: "cc13x2_cc26x2_tirtos7.cmd"

2. Generate projects:

fwkit ti ccs generate --platforms platforms.yaml

3. Import into CCS:
   • Project → Import → CCS Projects
   • Select generated .projectspec file

See examples/ for complete configuration examples.

🛠️ Development

Prerequisites

• Python 3.9 or higher
• uv (recommended) or pip
• Git

Setup

# Clone repository
git clone https://github.com/AcenoTecnologia/fwkit.git
cd fwkit

# Install dependencies with uv (recommended)
uv sync --all-extras

# Or with pip
pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff format .
uv run ruff check .
uv run mypy fwkit/

Validating Changes Locally

To avoid CI failures, run the same checks locally before committing:

# Quick validation (runs all CI checks)
./scripts/validate.sh

# Or run checks individually:
uv run ruff format .          # Auto-fix formatting
uv run ruff check --fix .     # Auto-fix linting issues
uv run mypy fwkit/            # Type checking
uv run pytest tests/          # Run test suite

Optional: Pre-commit hooks (runs checks automatically before each commit)

pip install pre-commit
pre-commit install

# Now checks run automatically on git commit
# Or run manually:
pre-commit run --all-files

Project Structure

fwkit/
├── fwkit/
│   ├── codegen/           # Code generation (version headers, etc.)
│   ├── vendors/           # Vendor-specific implementations
│   │   └── ti/           # Texas Instruments (CCS, toolchains)
│   ├── common/           # Shared utilities
│   └── cli.py            # Main CLI entry point
├── tests/                # Test suite (71 tests, 77% coverage)
├── examples/             # Configuration examples
└── docs/                 # Complete documentation with MkDocs

🗺️ Roadmap

Phase 1: TI Foundation ✅ (Completed)

• Version header generation
• TI CCS .projectspec generation
• Multi-platform configuration
• YAML-based config
• CLI with rich output
• Project import to workspace
• Headless builds via ccs-server-cli

Phase 2: TI Complete 🚧 (In Progress)

• Flash support (Uniflash integration)
• Debug launch configurations
• Build matrix (multiple configs in parallel)
• Project templates
• Binary post-processing

Phase 3: Expansion 🔮 (Planned)

• STM32CubeIDE support (.project/.cproject generation)
• ESP-IDF support (CMakeLists.txt, sdkconfig)
• Nordic nRF support (SES/Keil projects)
• PlatformIO integration
• Generic Makefile/CMake templates

Phase 4: Advanced 🎯 (Future)

• Docker build environments
• Cloud build integration
• Firmware OTA packaging
• Binary analysis tools
• Plugin system for custom vendors

🏗️ Architecture

While fwkit currently focuses on Texas Instruments tools, it's designed with a vendor-agnostic architecture:

fwkit/
  vendors/
    ti/          # Texas Instruments (active development)
    stm32/       # STMicroelectronics (planned)
    esp/         # Espressif (planned)
    nordic/      # Nordic Semi (planned)

Each vendor module is independent and follows the same patterns:

• Schemas: Pydantic models for type-safe configuration
• Generators: Code/project generation from Jinja2 templates
• CLI: Commands under fwkit <vendor> namespace
• Tests: Isolated test suites with >90% coverage target

This makes it easy to add new vendors without affecting existing ones.

📚 Documentation

📖 Read the Full Documentation (or run mkdocs serve locally)

Quick Links

• Installation Guide - Setup and configuration
• CLI Commands - Complete command reference
• YAML Reference - Full schema documentation
• Project Modes - Root vs Subdirectory organization
• Troubleshooting - Common issues and solutions

Configuration Examples

• TI CCS Configuration Examples - Real-world YAML samples
• YAML Format Guide - Quick reference (Portuguese)

🤝 Contributing

Contributions are welcome! Areas where you can help:

• New vendor support: Implement STM32, ESP32, Nordic, etc.
• Features: Build automation, debugging, OTA packaging
• Documentation: Tutorials, examples, API docs
• Testing: Expand test coverage, add integration tests
• Bug fixes: Check Issues

Please read CONTRIBUTING.md for details (coming soon).

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with Typer and Rich
• Type-safe with Pydantic
• Version management via Dunamai
• Fast dependency management with uv
• Inspired by PlatformIO, Invoke, and modern build tools

📮 Support

• 🐛 Report bugs
• 💡 Request features
• 📧 Contact: [e-mail]

---

Status: Alpha - In active development. APIs may change. Production use at your own risk.