Metadata-Version: 2.4
Name: fwkit
Version: 0.1.0
Summary: Firmware Development Toolkit - Build, generate, and manage embedded projects
Project-URL: Homepage, https://github.com/AcenoTecnologia/fwkit
Project-URL: Repository, https://github.com/AcenoTecnologia/fwkit
Project-URL: Documentation, https://fwkit.readthedocs.io
Author-email: Aceno Tecnologia <contato@aceno.com>
License: MIT
License-File: LICENSE
Keywords: build,ccs,embedded,firmware,mcu,ti,toolkit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: dunamai>=1.19.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: shellingham>=1.5.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# fwkit

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

[![Tests](https://github.com/AcenoTecnologia/fwkit/workflows/Tests/badge.svg)](https://github.com/AcenoTecnologia/fwkit/actions)
[![PyPI](https://img.shields.io/pypi/v/fwkit.svg)](https://pypi.org/project/fwkit/)
[![Python](https://img.shields.io/pypi/pyversions/fwkit.svg)](https://pypi.org/project/fwkit/)
[![License](https://img.shields.io/github/license/AcenoTecnologia/fwkit.svg)](https://github.com/AcenoTecnologia/fwkit/blob/main/LICENSE)

## 🎯 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**
```bash
# 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**
```bash
# 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**
```bash
# 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**
```bash
# 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)**
```bash
# 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)**
```bash
# Bootstrap new projects from templates
fwkit project init my-ble-sensor \
  --vendor ti \
  --platform cc26x2r1 \
  --template ble-peripheral
```

## 📦 Installation

```bash
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:

```yaml
# 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:
```bash
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

```bash
# 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`:
```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:
```bash
fwkit ti ccs generate --platforms platforms.yaml
```

3. **Import** into CCS:
   - `Project → Import → CCS Projects`
   - Select generated `.projectspec` file

See [examples/](examples/) for complete configuration examples.

## 🛠️ Development

### Prerequisites

- Python 3.9 or higher
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Git

### Setup

```bash
# 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:

```bash
# 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)
```bash
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)
- [x] Version header generation
- [x] TI CCS .projectspec generation
- [x] Multi-platform configuration
- [x] YAML-based config
- [x] CLI with rich output
- [x] Project import to workspace
- [x] 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](https://fwkit.readthedocs.io/)** (or run `mkdocs serve` locally)

### Quick Links

- **[Installation Guide](docs/installation.md)** - Setup and configuration
- **[CLI Commands](docs/cli/codegen-version.md)** - Complete command reference
- **[YAML Reference](docs/configuration/yaml-reference.md)** - Full schema documentation
- **[Project Modes](docs/configuration/project-modes.md)** - Root vs Subdirectory organization
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions

### Configuration Examples

- [TI CCS Configuration Examples](examples/) - Real-world YAML samples
- [YAML Format Guide](examples/YAML_FORMAT_GUIDE.md) - 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](https://github.com/AcenoTecnologia/fwkit/issues)

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

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Typer](https://typer.tiangolo.com/) and [Rich](https://rich.readthedocs.io/)
- Type-safe with [Pydantic](https://docs.pydantic.dev/)
- Version management via [Dunamai](https://github.com/mtkennerly/dunamai)
- Fast dependency management with [uv](https://docs.astral.sh/uv/)
- Inspired by [PlatformIO](https://platformio.org/), [Invoke](https://www.pyinvoke.org/), and modern build tools

## 📮 Support

- 🐛 [Report bugs](https://github.com/AcenoTecnologia/fwkit/issues)
- 💡 [Request features](https://github.com/AcenoTecnologia/fwkit/issues)
- 📧 Contact: contato@aceno.com

---

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