Skip to content
Open
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 33 additions & 11 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,12 @@

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:
Expand Down Expand Up @@ -33,29 +39,29 @@ board = Gaggimate-Controller
build_src_filter = -<*> +<controller/>
```


### Controller Firmware

Located in `lib/GaggiMateControlle` and `src/controller`.
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:

- `npm run dev` - Starts a dev server at http://localhost:5173/
- `npm run dev` - Starts a dev server at <http://localhost:5173/>
- `npm run build` - Builds for production, emitting to `dist/`
- `npm run preview` - Starts a server at http://localhost:4173/ to test production build locally
- `npm run preview` - Starts a server at <http://localhost:4173/> to test production build locally

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.
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

Expand All @@ -66,19 +72,35 @@ When building the firmware, the scripts/build_spiffs.sh script installs the web
## 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](https://platformio.org/) is available for firmware builds.

- Run `npm install` inside the `web/` directory for the web interface.
- Ensure [PlatformIO](https://platformio.org/install/cli) 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`

```shell
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 | <pre>scripts/build_spiffs.sh<br>platformio run -e display -t uploadfs -t monitor</pre> |

**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

Expand Down