controller/.github

ClearGrow Controller CI/CD

GitHub Actions workflows for automated testing, building, and releasing ClearGrow Controller firmware.

Workflows

1. CI Pipeline (ci.yml)

Triggers:

• Push to main or develop branches
• Pull requests targeting main or develop

Jobs:

1. Test - Validates all unit tests

   • Runs test/run_tests.sh to validate test structure
   • Generates coverage report with test/run_coverage.sh
   • Must pass before builds proceed

2. Build Development - Builds firmware with development configuration

   • Uses sdkconfig.defaults (no security features)
   • Generates size analysis report
   • Uploads firmware artifacts (retained 30 days)

3. Build Production - Builds firmware with production configuration

   • Uses sdkconfig.defaults + sdkconfig.defaults.prod
   • Enables flash encryption, secure boot, NVS encryption
   • Uploads firmware artifacts (retained 90 days)

4. Status Summary - Reports overall CI status

   • Aggregates results from all jobs
   • Provides clear pass/fail status

Artifacts Generated:

• firmware-dev-<sha> - Development binaries (.bin, .elf, .map)
• firmware-prod-<sha> - Production binaries (.bin, .elf, .map)
• build-report-dev-<sha>.txt - Development size analysis
• build-report-prod-<sha>.txt - Production size analysis

2. Coverage Tracking (coverage.yml)

Triggers:

• Push to main
• Pull requests targeting main

Features:

• Builds with coverage flags (-fprofile-arcs -ftest-coverage)
• Generates component coverage report
• Comments coverage summary on pull requests
• Tracks coverage metrics over time

Future Enhancement:

• Full gcov/lcov line coverage analysis
• Coverage trend graphs
• Minimum coverage thresholds

3. Release Workflow (release.yml)

Triggers:

• Git tags matching v*.*.* (e.g., v2.1.0)

Process:

1. Builds production firmware with security features
2. Generates versioned artifacts with SHA256 checksums
3. Creates comprehensive release notes
4. Publishes GitHub Release with all artifacts

Release Artifacts:

• cleargrow-controller-v{version}.bin - Main firmware
• bootloader-v{version}.bin - Bootloader
• partition-table-v{version}.bin - Partition table
• checksums-v{version}.txt - SHA256 checksums
• build-report-v{version}.txt - Size analysis
• RELEASE_NOTES.md - Flashing instructions

Using the Workflows

For Developers

Local Development:

# Before pushing, run tests locally
cd /root/cleargrow/controller/test
./run_tests.sh

# Check coverage
./run_coverage.sh

# Build to verify
cd ..
idf.py build

Pull Request Process:

1. Create feature branch
2. Commit changes
3. Push to GitHub
4. Open pull request to develop or main
5. CI automatically runs and reports status
6. Coverage report posted as PR comment
7. Review build artifacts if needed

Accessing Artifacts:

1. Navigate to Actions tab on GitHub
2. Click on the workflow run
3. Scroll to "Artifacts" section
4. Download desired artifacts

For Maintainers

Creating a Release:

1. Update version in code (if needed)

2. Commit and push changes

3. Create and push git tag:

   git tag -a v2.1.0 -m "Release version 2.1.0"
   git push origin v2.1.0
   

4. GitHub Actions automatically:

   • Builds production firmware
   • Generates checksums
   • Creates GitHub Release
   • Uploads all artifacts

5. Edit release notes on GitHub (optional)

6. Distribute firmware to users/OTA server

Build Configurations

Development Build

• Security: Disabled
• Use Case: Daily development, debugging
• Reflashing: Easy, no restrictions
• Config: sdkconfig.defaults

Production Build

• Security: Full (flash encryption, secure boot, NVS encryption)
• Use Case: Manufacturing, production deployment
• Reflashing: Restricted (one-way operation)
• Config: sdkconfig.defaults + sdkconfig.defaults.prod

Status Checks

Pull requests require all CI checks to pass:

• Unit tests validated
• Coverage report generated
• Development build successful
• Production build successful

Troubleshooting

Build Failures

ESP-IDF version mismatch:

• Workflow uses ESP-IDF v5.2
• Ensure local environment matches: idf.py --version

Missing submodules:

• Workflows checkout with submodules: recursive
• Local: git submodule update --init --recursive

Configuration errors:

• Check sdkconfig.defaults and sdkconfig.defaults.prod
• Run idf.py menuconfig to verify settings

Test Failures

Test script errors:

• Ensure scripts are executable: chmod +x test/run_*.sh
• Run locally to reproduce: cd test && ./run_tests.sh

Missing test files:

• Test runner validates file structure
• Add missing tests or update test list in run_tests.sh

Artifact Issues

Artifacts expired:

• Development artifacts: 30 day retention
• Production artifacts: 90 day retention
• Rebuild from git tag if needed

Download failures:

• Check artifact size (large .elf files)
• Use GitHub CLI for reliable downloads: gh run download <run-id>

Performance

Typical workflow execution times:

• Test job: 2-3 minutes
• Build Development: 5-8 minutes
• Build Production: 5-8 minutes
• Coverage: 3-5 minutes
• Release: 6-10 minutes

Total CI time (parallel execution): ~10-15 minutes

Future Enhancements

Planned improvements tracked in testing assessment:

1. Hardware-in-the-Loop Testing (CTRL-TE-002)

   • Dedicated ESP32-S3 test hardware
   • Automated peripheral testing
   • Integration with CI pipeline

2. Full Line Coverage (gcov/lcov)

   • Generate detailed coverage reports
   • Visualize coverage trends
   • Enforce minimum thresholds

3. Performance Benchmarks

   • Boot time measurements
   • Memory usage tracking
   • Regression detection

4. Automated Firmware Signing

   • ECDSA signature generation
   • Secure key management
   • OTA package creation

5. Multi-Environment Testing

   • Test across ESP-IDF versions
   • Validate against different configurations
   • Matrix builds

References

• ESP-IDF CI Action: https://github.com/espressif/esp-idf-ci-action
• GitHub Actions Docs: https://docs.github.com/en/actions
• Testing Documentation: /root/cleargrow/controller/test/README.md
• Production Build Guide: /root/cleargrow/docs/guides/developer/onboarding/production-build.md