From 5c401f6d0271fa955d4e4be4d1981cf201a5db8f Mon Sep 17 00:00:00 2001 From: Florian Date: Sat, 3 Jan 2026 10:54:31 -0600 Subject: [PATCH] [CI] Add Claude GitHub actions (#2266) * "Claude PR Assistant workflow" * "Claude Code Review workflow" * Add CLAUDE md for context --------- Co-authored-by: Florian <1technophile@users.noreply.github.com> --- .github/workflows/claude-code-review.yml | 57 ++++ .github/workflows/claude.yml | 50 ++++ CLAUDE.md | 319 +++++++++++++++++++++++ 3 files changed, 426 insertions(+) create mode 100644 .github/workflows/claude-code-review.yml create mode 100644 .github/workflows/claude.yml create mode 100644 CLAUDE.md diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml new file mode 100644 index 00000000..8452b0f2 --- /dev/null +++ b/.github/workflows/claude-code-review.yml @@ -0,0 +1,57 @@ +name: Claude Code Review + +on: + pull_request: + types: [opened, synchronize] + # Optional: Only run on specific file changes + # paths: + # - "src/**/*.ts" + # - "src/**/*.tsx" + # - "src/**/*.js" + # - "src/**/*.jsx" + +jobs: + claude-review: + # Optional: Filter by PR author + # if: | + # github.event.pull_request.user.login == 'external-contributor' || + # github.event.pull_request.user.login == 'new-developer' || + # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' + + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code Review + id: claude-review + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + prompt: | + REPO: ${{ github.repository }} + PR NUMBER: ${{ github.event.pull_request.number }} + + Please review this pull request and provide feedback on: + - Code quality and best practices + - Potential bugs or issues + - Performance considerations + - Security concerns + - Test coverage + + Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback. + + Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR. + + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + # or https://code.claude.com/docs/en/cli-reference for available options + claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"' + diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml new file mode 100644 index 00000000..d300267f --- /dev/null +++ b/.github/workflows/claude.yml @@ -0,0 +1,50 @@ +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + issues: read + id-token: write + actions: read # Required for Claude to read CI results on PRs + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + with: + claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + + # This is an optional setting that allows Claude to read CI results on PRs + additional_permissions: | + actions: read + + # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it. + # prompt: 'Update the pull request description to include a summary of changes.' + + # Optional: Add claude_args to customize behavior and configuration + # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md + # or https://code.claude.com/docs/en/cli-reference for available options + # claude_args: '--allowed-tools Bash(gh pr:*)' + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..56f138f4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,319 @@ +# OpenMQTTGateway - Claude Code Context + +This document provides essential context about the OpenMQTTGateway project for AI assistants working on the codebase. + +## Project Overview + +OpenMQTTGateway is a unified firmware that bridges various wireless technologies (RF 433MHz, IR, BLE, LoRa, etc.) to MQTT protocol, enabling home automation integration with platforms like Home Assistant, OpenHAB, and Node-RED. + +**Key Features:** +- Multi-protocol gateway (BLE, RF 433MHz, IR, LoRa, RTL_433, Pilight, etc.) +- ESP8266/ESP32 and Arduino support +- MQTT-based communication +- Web UI for configuration +- Home Assistant MQTT Discovery support +- Over 100 supported BLE sensors via Theengs Decoder + +**Main Branch:** `development` (not master/main) + +## Architecture + +### Modular Design + +The firmware uses a modular architecture where each protocol/sensor/actuator is implemented as a separate "gateway" or "sensor" module: + +- **Gateways**: Receive and transmit signals (e.g., `gatewayBT.cpp`, `gatewayRF.cpp`, `gatewayIR.cpp`) +- **Sensors**: Read physical sensor data (e.g., `sensorBME280.cpp`, `sensorDHT.cpp`) +- **Actuators**: Control outputs (e.g., `actuatorONOFF.cpp`, `actuatorPWM.cpp`) + +Each module has: +- A config file (e.g., `config_BT.h`, `config_RF.h`) +- An implementation file (e.g., `gatewayBT.cpp`, `gatewayRF.cpp`) + +### Configuration System + +Configuration is managed through: +1. **User_config.h** - Main configuration file with defaults +2. **config_*.h** - Module-specific configurations +3. **platformio.ini & environments.ini** - Build-time configurations +4. **prod_env.ini** - User-specific environments (gitignored) + +Build flags in `environments.ini` can override User_config.h parameters. + +## Directory Structure + +``` +OpenMQTTGateway/ +├── main/ # Main source code (Arduino convention) +│ ├── main.cpp # Main application entry point +│ ├── User_config.h # Global configuration +│ ├── config_*.h # Module configurations +│ ├── gateway*.cpp # Gateway implementations +│ ├── sensor*.cpp # Sensor implementations +│ ├── actuator*.cpp # Actuator implementations +│ ├── webUI.cpp # Web interface +│ ├── mqttDiscovery.cpp # Home Assistant discovery +│ └── rf/ # RF-specific modules +├── lib/ # Custom libraries +├── scripts/ # Build and automation scripts +├── docs/ # VuePress documentation +├── tests/ # Test configurations +├── environments.ini # PlatformIO environment definitions +├── platformio.ini # PlatformIO configuration +└── prod_env.ini.example # Example production environment + +Note: src_dir is set to "main" in platformio.ini +``` + +## Key Concepts + +### Environment-Based Builds + +The project supports 80+ hardware configurations defined in `environments.ini`. Examples: +- `esp32dev-ble` - ESP32 with BLE gateway +- `esp32dev-pilight` - ESP32 with Pilight RF +- `esp32dev-rtl_433` - ESP32 with RTL_433 decoder +- `nodemcuv2-ir` - NodeMCU with IR +- `rfbridge` - Sonoff RF Bridge + +### MQTT Topics + +Standard topic structure: +- Base: `home/` (configurable via Base_Topic) +- Gateway name: `OpenMQTTGateway` or `OMG` (configurable) +- Example: `home/OpenMQTTGateway/BTtoMQTT` + +### Module Activation + +Modules are activated via build flags in environments.ini: +```ini +build_flags = + '-DZgatewayBT="BT"' # Enable BLE gateway + '-DZgatewayRF="RF"' # Enable RF gateway + '-DZsensorBME280="BME280"' # Enable BME280 sensor +``` + +### Web UI & WiFi Manager + +- ESP32/ESP8266 boards include a WiFiManager for initial setup +- Access point: SSID = `WifiManager_ssid`, Password = `WifiManager_password` +- Web UI provides runtime configuration and control +- Can disable WiFiManager with `ESPWifiManualSetup` flag + +## Important Files + +### Core Files + +- **main/main.cpp** - Main application loop, MQTT handling, module coordination +- **main/User_config.h** - Global configuration defaults +- **main/webUI.cpp** - Web interface implementation +- **main/mqttDiscovery.cpp** - Home Assistant MQTT discovery + +### Gateway Files + +- **main/gatewayBT.cpp** - BLE gateway (uses Theengs Decoder) +- **main/gatewayRF.cpp** - RF 433MHz gateway (RCSwitch library) +- **main/gatewayRF2.cpp** - Alternative RF implementation +- **main/gatewayPilight.cpp** - Pilight protocol gateway +- **main/gatewayRTL_433.cpp** - RTL_433 decoder integration +- **main/gatewayIR.cpp** - Infrared gateway +- **main/gatewayLORA.cpp** - LoRa gateway + +### Configuration Files + +All in `main/` directory: +- **config_RF.h** - RF gateway configuration +- **config_BT.h** - BLE gateway configuration +- **config_IR.h** - IR gateway configuration +- etc. + +### Build System + +- **platformio.ini** - Main PlatformIO config +- **environments.ini** - All environment definitions (~3000+ lines) +- **scripts/** - Python scripts for build automation + +## Common Patterns + +### Adding a New Gateway Module + +1. Create `gateway[NAME].cpp` in `main/` +2. Create `config_[NAME].h` in `main/` +3. Add build flag in `environments.ini`: `-DZgateway[NAME]="[NAME]"` +4. Include conditional compilation: `#ifdef Zgateway[NAME]` +5. Implement setup function: `setup[NAME]()` +6. Implement loop function: `[NAME]toMQTT()` +7. Optionally implement MQTT callback: `MQTTto[NAME]()` + +### Adding a New Sensor Module + +Similar to gateways, but prefix with `sensor` instead of `gateway` and `Z` becomes `Zsensor`. + +### Configuration Override Pattern + +```cpp +#ifndef PARAM_NAME +# define PARAM_NAME default_value +#endif +``` + +This allows platformio.ini build flags to override defaults. + +### MQTT Publishing Pattern + +```cpp +pub(subjectToMQTT, data); // Basic publish +pub_custom_topic(topic, data, retain); // Custom topic with retain +``` + +## Development Workflow + +### Building + +```bash +# List all environments +pio run --list-targets + +# Build specific environment +pio run -e esp32dev-ble + +# Upload to device +pio run -e esp32dev-ble -t upload + +# Monitor serial +pio device monitor +``` + +### Code Formatting + +- Uses clang-format with config in `.clang-format` +- CI checks formatting automatically +- Format before committing + +### Testing + +- Unit tests in `tests/` directory +- CI runs builds for all environments +- Nightly builds test comprehensive environment matrix + +### Documentation + +- Documentation uses VuePress, located in `docs/` +- Hosted at https://docs.openmqttgateway.com + +## CI/CD + +### GitHub Actions Workflows + +Located in `.github/workflows/`: +- **build.yml** - Build validation on PRs +- **nightly.yml** - Nightly builds of all environments +- **format-check.yml** - Code formatting validation + +### Build Matrix + +The nightly build tests configurations: +- ESP32 variants (ESP32, ESP32-S3, ESP32-C3) +- ESP8266 variants (NodeMCU, Sonoff) +- Different gateway combinations +- Board-specific builds (M5Stack, Heltec, TTGO, etc.) + +## Common Issues & Solutions + +### Memory Constraints + +- ESP8266 has limited RAM (~40KB free) +- Use `PROGMEM` for constants +- Minimize module combinations on ESP8266 +- ESP32 has more headroom (~200KB+ free) + +### RF Module Conflicts + +- Some RF implementations (RF, RF2, Pilight, RTL_433) may conflict +- Use separate environments for different RF approaches +- Check GPIO pin assignments in config files + +### BLE on ESP32 + +- BLE stack uses significant RAM +- Limit simultaneous BLE connections + +## Related Projects + +- **Theengs Decoder** - BLE device decoder library +- **Theengs Gateway** - Python version for Raspberry Pi/PC +- **RTL_433_ESP** - ESP32 port of RTL_433 + +## Resources + +- **Documentation**: https://docs.openmqttgateway.com +- **Community Forum**: https://community.openmqttgateway.com +- **GitHub**: https://github.com/1technophile/OpenMQTTGateway +- **Web Installer**: https://docs.openmqttgateway.com/upload/web-install.html + +## Products + +- **Theengs Bridge** - ESP32 BLE gateway with Ethernet +- **Theengs Plug** - Smart plug with BLE gateway + +## Conventions + +### Naming + +- Gateways: `gateway[NAME].cpp` with `Zgateway[NAME]` flag +- Sensors: `sensor[NAME].cpp` with `Zsensor[NAME]` flag +- Actuators: `actuator[NAME].cpp` with `Zactuator[NAME]` flag +- Config files: `config_[NAME].h` + +### Code Style + +- 2-space indentation +- Follow existing patterns in similar modules +- Use preprocessor directives for module isolation +- Comment complex RF protocols or BLE parsing + +### Git Workflow + +- Main branch: `development` +- Feature branches from `development` +- PRs target `development` +- Squash commits when appropriate +- Descriptive commit messages + +## Quick Start for Contributors + +1. Fork the repository +2. Create `prod_env.ini` for your local environments +3. Choose an environment from `environments.ini` +4. Build: `pio run -e [environment-name]` +5. Make changes following existing patterns +6. Test build with your environment +7. Run format check +8. Submit PR to `development` branch + +## Platform-Specific Notes + +### ESP32 +- Preferred platform for new development +- More RAM and Flash +- Supports BLE natively +- Can use Ethernet via add-on boards + +### ESP8266 +- Legacy support +- Memory constrained +- No native BLE +- Good for simple RF/IR gateways + +## Tips for AI Assistants + +1. **Check environments.ini** when modifying build configurations +2. **Follow existing module patterns** when adding new features +3. **Test on relevant environments** - changes may affect multiple boards +4. **Memory is precious** especially on ESP8266 +5. **MQTT topic structure** is critical for Home Assistant integration +6. **Config headers** allow user customization without code changes +7. **Use conditional compilation** to keep builds modular +8. **WebUI changes** need both backend (webUI.cpp) and frontend (config_WebUI.h) +9. **RF protocols** often need precise timing - be careful with changes +10. **The main branch is `development`** - always target PRs there