Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (66 loc) · 3.81 KB

CONTRIBUTING.md

File metadata and controls

91 lines (66 loc) · 3.81 KB

Contributing to GaggiMate

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

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/GaggiMateControlle 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 and platformio run -e controller compile the firmware.
    • ./scripts/builds_spiffs.sh builds the web assets.
  4. Upload the Web UI by running platformio run -e display -t uploadfs

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.

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.