fwkit 0.1.1

Firmware Development Toolkit for Texas Instruments - Automate Code Composer Studio projects and TI embedded workflows

fwkit

Firmware Development Toolkit for Texas Instruments - Automate Code Composer Studio projects, builds, and firmware development workflows.

🎯 What is fwkit?

fwkit is a command-line toolkit designed specifically for Texas Instruments embedded development. It automates Code Composer Studio (CCS) project management, build configurations, and firmware development workflows for TI microcontrollers, while maintaining full compatibility with standard TI tools and workflows. Projects generated by fwkit can be opened, compiled, debugged, and maintained normally in Code Composer Studio, ensuring your projects remain robust as TI tools continue to evolve.

Target platforms: Texas Instruments CC13xx, CC26xx, CC32xx, MSPM0 (ARM Cortex-M0+) and other TI microcontrollers

Primary IDE: Code Composer Studio (CCS)

🎯 Why fwkit?

The Problem: Product Variants

Developing firmware for multiple hardware variants is challenging. You often have:

• Same codebase, different hardware (different MCUs, memory, peripherals)
• Different SysConfig files - each variant has unique peripheral configurations, pin mappings, clocks
• Different linker scripts - MCUs from different families require different memory layouts
• Different compiler defines - feature flags, memory sizes, hardware capabilities
• Different project files - some variants need additional source files or libraries
• Manual project management - creating, updating, and maintaining separate CCS projects by hand

Common scenario: You have a product line with CC2652R1, CC2652R7, CC1352P, and CC2651R3 variants. Each needs its own:

• .syscfg file (different GPIO, I2C, UART configurations)
• Linker script (.cmd file for the specific MCU family)
• Compiler flags (-DHAS_EXTRA_MEMORY, -DLOW_POWER_MODE)
• Sometimes different source files or .opt files

Maintaining 4+ separate CCS projects manually is error-prone and time-consuming.

The Solution: Automation

fwkit solves this with three core capabilities:

1. Automated Project Generation

• Define all variants in a single YAML file
• Generate .projectspec files for all platforms automatically
• Each variant gets the correct SysConfig, linker script, defines, and files
• Maintain compatibility with CCS - projects work normally in the IDE

2. Version Management

• Generate version headers from Git tags automatically
• Works for any platform/project (not just TI)
• Keep firmware version in sync with repository state

3. Automated Builds

• Build all platforms and variants without opening CCS
• Headless builds via CLI - perfect for CI/CD
• Generate multiple configurations in parallel

Future: CMake support, Docker containers, and complete CI/CD pipeline templates.

Key benefit: Define once, generate everywhere. Your YAML configuration is the single source of truth, while maintaining full compatibility with normal CCS workflows.

🚀 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 Examples

The examples below show fwkit in action. Start with the simple example if you're just getting started, or jump to the complete example to see all capabilities.

Simple Example

Quick setup for 2 hardware variants with minimal configuration:

# platforms.yaml
defaults:
  compiler_version: "4.0.4.LTS"

cc2652r1:
  platform: "cc2652r1"
  project_title: "My CC2652R1 Project"
  project_name: "my_cc2652r1"
  device: "Cortex M.CC2652R1F"
  link_file_path: "cc13x2_cc26x2_tirtos7.cmd"

cc2652r7:
  platform: "cc2652r7"
  project_title: "My CC2652R7 Project"
  project_name: "my_cc2652r7"
  device: "Cortex M.CC2652R7"
  link_file_path: "cc13x2x7_cc26x2x7_tirtos7.cmd"

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

Result: 2 ready-to-import .projectspec files in seconds.

Complete Example

Product line with 4 different hardware variants (different MCUs, memory, peripherals). Instead of maintaining 4 separate CCS projects by hand:

# platforms.yaml
defaults:
  project_description: "IoT Sensor Family"
  compiler_version: "4.0.4.LTS"
  tool_chain: "TICLANG"
  products: "com.ti.SIMPLELINK_CC13XX_CC26XX_SDK;sysconfig"
  mfloat_abi: "hard"
  mfpu: "fpv4-sp-d16"
  compiler_build_options:
    - "-I${PROJECT_ROOT}"
    - "-O2"
    - "-gdwarf-3"

cc26x2r1_basic:
  platform: "cc26x2r1_basic"
  project_title: "Sensor CC2652R1"
  project_name: "sensor_cc26x2r1"
  device: "Cortex M.CC2652R1F"
  link_file_path: "cc13x2_cc26x2_tirtos7.cmd"
  sysconfig_file_path: "sensor_cc26x2r1.syscfg"

cc26x2r7_advanced:
  platform: "cc26x2r7_advanced"
  project_title: "Sensor CC2652R7"
  project_name: "sensor_cc26x2r7"
  device: "Cortex M.CC2652R7"
  link_file_path: "cc13x2x7_cc26x2x7_tirtos7.cmd"
  sysconfig_file_path: "sensor_cc26x2r7.syscfg"
  compiler_build_options:
    - "-DHAS_EXTRA_MEMORY"

cc1352p_multiband:
  platform: "cc1352p_multiband"
  project_title: "Sensor CC1352P"
  project_name: "sensor_cc1352p"
  device: "Cortex M.CC1352P1F3"
  link_file_path: "cc13x2_cc26x2_tirtos7.cmd"
  sysconfig_file_path: "sensor_cc1352p.syscfg"
  compiler_build_options:
    - "-DHAS_SUB1GHZ"

cc2651r3_compact:
  platform: "cc2651r3_compact"
  project_title: "Sensor CC2651R3"
  project_name: "sensor_cc2651r3"
  device: "Cortex M.CC2651R3"
  link_file_path: "cc13x1_cc26x1_tirtos7.cmd"
  sysconfig_file_path: "sensor_cc2651r3.syscfg"
  mfloat_abi: "soft"
  mfpu: "none"
  compiler_build_options:
    - "-DLOW_POWER_MODE"

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

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

📖 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: Core TI Tooling ✅ (Completed)

• Version header generation from Git
• TI CCS .projectspec generation
• Multi-platform configuration with YAML
• Rich CLI with colored output
• Project import to CCS workspace
• Headless builds via eclipse CLI
• Batch builds for multiple variants

Phase 2: Extended TI Features 🚧 (Planned)

• Flash support (Uniflash CLI integration)
• Debug launch configurations
• Project templates for common TI SDKs
• Binary post-processing and signing
• Support for additional TI device families
• Integration with TI Resource Explorer

Phase 3: Advanced Workflows 🎯 (Future)

• Docker build environments for reproducible builds
• Firmware OTA packaging for TI wireless devices
• Binary analysis and size optimization tools
• CI/CD pipeline templates for TI projects

🏗️ Architecture

fwkit is built with a modular architecture focused on Texas Instruments tooling:

fwkit/
  codegen/         # Generic code generation (version headers)
  vendors/
    ti/            # Texas Instruments tools and workflows
      ccs/         # Code Composer Studio integration
      schemas/     # Pydantic models for type-safe configuration
      templates/   # Jinja2 templates for .projectspec generation
  common/          # Shared utilities and helpers

Key design principles:

• Type-safe configuration: Pydantic models validate YAML before generation
• Template-based generation: Jinja2 templates for flexible project file creation
• Modular CLI: Commands organized under fwkit ti ccs namespace
• Comprehensive testing: 71 tests with >75% coverage

📚 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:

• TI features: Uniflash integration, debug configurations, new device families
• Build automation: Enhanced build workflows, optimization tools
• Documentation: Tutorials, examples, API docs
• Testing: Expand test coverage, add integration tests
• Bug fixes: Check Issues

📄 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

---