Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
113 lines (79 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

113 lines (79 loc) · 4.67 KB
Raw

Contributing to GaggiMate

Thank you for considering a contribution to the project. This document explains the repository structure and how to get involved.

CLA

We require contributors to sign our Contributor License Agreement. In order for us to review and merge your code, please contact @jniebuhr (mdwasp) on Discord to access the CLA. A signed CLA is required for contributing.

Codebase Overview

The repository is organized into the following folders:

.
├── boards/             # Custom PlatformIO board definitions
├── docs/               # Documentation assets and diagrams
├── icons/              # Source icons and conversion scripts
├── lib/                # PlatformIO libraries such as GaggiMateController
├── scripts/            # Helper scripts for builds and formatting
├── src/
│   ├── controller/     # Firmware for the controller board
│   └── display/        # Firmware for the display unit (LVGL UI, plugins)
├── ui/                 # SquareLine Studio project for the LVGL UI
├── web/                # Preact-based web interface
└── platformio.ini      # PlatformIO configuration

There are two main PlatformIO environments defined in platformio.ini:

[env:display]
board = LilyGo-T-RGB
build_src_filter = -<*> +<display/>

[env:controller]
board = Gaggimate-Controller
build_src_filter = -<*> +<controller/>

Controller Firmware

Located in lib/GaggiMateController and src/controller. Implements hardware control and BLE communication. GaggiMateController.* sets up peripherals (heater, pump, valve) and handles safety mechanisms such as thermal runaway shutoff. Communication with the display uses the NimBLE library.

Display Firmware

Resides in src/display. core/Controller.h orchestrates Wi‑Fi, Bluetooth, profiles, and process control. Uses LVGL for graphics, with UI assets generated by SquareLine Studio (ui/ folder). Plugins (e.g., BLEScalePlugin, MQTTPlugin, BoilerFillPlugin, HomekitPlugin) extend functionality via an event-driven PluginManager.

Web Interface

The web/ directory contains a Preact + Vite project. The README inside explains how to run it:

When building the firmware, the scripts/build_spiffs.sh script installs the web dependencies and copies the compiled files to the data/ directory for inclusion in the device’s SPIFFS image.

Next Steps for Learning

  • Review plugin implementations in src/display/plugins to see how new functionality hooks into the controller using events.
  • Look at src/display/core/Settings.* for how user preferences are stored and updated.
  • Study the BLE protocol defined in lib/NimBLEComm to understand how the display and controller communicate.

Getting Started

  1. Fork the repository and create your branch from master.

  2. Install dependencies:

    • Run npm install inside the web/ directory for the web interface.
    • Ensure PlatformIO is available for firmware builds.

  3. Build the project to verify your environment:

    platformio run -e display -e controller
scripts/build_spiffs.sh

  4. Choose what to deploy:

    Asset Commands
    Display Firmware platformio run -e display -t upload -t monitor
    Controller Firmware platformio run -e controller -t upload -t monitor
    Web UI 
    scripts/build_spiffs.sh
    platformio run -e display -t uploadfs -t monitor

    NOTE: You can omit -t monitor if you don't want to immediately attach to the board's serial console.

Code Style

  • Format C/C++ sources using scripts/format.sh which applies the project's clang-format settings.
  • For web code, use npm run format to apply Prettier.
  • Run static analysis with platformio check -e display and platformio check -e controller.
  • For markdown files, use npx prettier -w <file>.md

Pull Requests

  • Keep PRs focused and describe the motivation behind your change.
  • Include screenshots when modifying the UI.
  • Ensure all formatting and checks pass before opening the PR.

Reporting Issues

If you encounter a problem, open an issue describing the steps to reproduce and any relevant logs.