TiltSense

<div align="center"> <img src="assets/logo-text.svg" alt="TiltSense" width="200"/> </div>

TiltSense

TiltSense is a flexible and powerful ESP32-based system that brings together multiple sensors, integrations, and user-friendly tools into a single customizable hub for fermentation monitoring.

After months of design, development, and testing, the first stable release is finally out of the oven — and it's packed with features for homebrewers, hackers, and fermentation geeks alike.

🧪 The complete documentation is now available at:
👉 https://bananabrewery.github.io/TiltSense

---

📦 Project Status

TiltSense is stable and fully functional in its first release. The current firmware is offered as a complete example configuration.

🛠️ Ongoing development:
A TiltSense Firmware Builder is available — a web app that generates fully customized firmware tailored to your specific setup, eliminating manual editing.

• ✅ Which Tilt hydrometers are used, and their colors
• 🆚 Whether they are Tilt or Tilt Pro versions
• 🏠 Whether the user has Home Assistant integration
• 💨 Whether a pressure sensor is included
• 📡 Whether integration with Brewfather is desired

This simplifies setup and allows adapting TiltSense to a wide variety of fermentation scenarios.

Check out the Firmware Builder here:
👉 https://bananabrewery.github.io/TiltSenseFirmwareBuilder

I’ve also developed a backend compiler service that can build your firmware automatically — no local ESPHome install needed!

---

🚀 Features

• ✅ Multi-Tilt Support
  Read and monitor multiple Tilt Hydrometers simultaneously, including standard and Pro models.

• 📡 Brewfather & Home Assistant Integration
  Native support for seamless tracking, automation, and remote data logging.

• 🌐 Built-in Web Server
  Configure system parameters via an intuitive and mobile-friendly web interface.

• 🔀 Sensor Fusion
  Combine Tilt data with pressure sensors for real-time fermentation profiling (e.g., gravity curves under pressure).

• 🔋 Internal Battery
  Portable and continuous operation with low-power consumption and battery support.

• 🧲 Magnetic 3D-Printed Enclosure
  Custom-designed case with magnetic mounting — easy to use, easy to love.

• 💡 Touchscreen Interface
  Clean LVGL-powered display with gesture-based navigation, real-time feedback, and interactive widgets.

• 💰 Affordable & Accessible
  Built using low-cost, off-the-shelf ESP32 hardware and open-source components.

---

📷 Screenshots

<div align="center"> <img src="docs/en/assets/prototypes/TiltSense%20-%20With%20Pressure.svg" alt="TiltSense Screen"/> </div>

---

📦 Hardware Requirements

Here’s what you need to build a complete TiltSense unit:

• ESP32-S3 with 1.28" Round Touchscreen (GC9A01A display + CST816S capacitive touch)
  A compact, all-in-one ESP32-S3 development board with integrated round LCD and touchscreen.

• LiPo Battery 3.7V (1S) 200mAh with JST 1.25mm connector
  Optional but supported.
  ⚠️ Important: Check polarity before connecting. Some batteries come with inverted pins!

• M2xL2xOD3.2 Brass Heat-Set Inserts
  For securing the case with threaded inserts.

• M2x5mm Screws
  To mount the case and secure the board.

• Neodymium Magnet 20×3 mm
  Embedded in the 3D-printed case for easy magnetic mounting on fermenters or fridges.

• 3D-Printed Case
  A custom enclosure designed for easy assembly, battery integration, and magnetic mounting.
  🖨️ Print instructions are available on MakerWorld.

• USB-A to USB-C Cable
  For flashing firmware and charging the internal battery.

• Pressure Sensor (optional — details coming soon)
  Used for advanced fermentation tracking by monitoring internal vessel pressure.

🖨️ Print instructions are available on MakerWorld

---

🔧 Setup & Flashing

1. Configure and generate your custom firmware using the Firmware Builder:
   👉 https://bananabrewery.github.io/TiltSenseFirmwareBuilder/

2. You can either:

   • Compile the firmware yourself using ESPHome, or
   • Use the backend compiler service integrated in the Firmware Builder to generate a ready-to-flash binary.

3. Flash your ESP32 using ESPHome with the firmware file.

4. Access the web UI via mDNS or IP (http://tiltsense.local/).

---

🤝 Integrations

• Tilt Hydrometer
• Brewfather
• Home Assistant

---

🛠️ Setup & Development Environment

1. Create a virtual environment

Make sure you have Python 3 installed. Then, in the root of the project, create a virtual environment:

python3 -m venv .venv

Activate the virtual environment:

source .venv/bin/activate

2. Install project dependencies

Once the virtual environment is active, install the required packages:

pip install -r requirements.txt

3. Serve the documentation (MkDocs)

To serve the documentation locally:

mkdocs serve

This will start a local server at:

http://127.0.0.1:8000/

MkDocs will automatically reload when you make changes to the documentation files.

4. Build the static site (optional)

To generate the static site in the site/ directory:

mkdocs build

This is useful if you want to deploy the documentation (e.g. to GitHub Pages).

---

🙋 Community & Support

• ❗ Report bugs or request features: Open an issue
• 💬 Share ideas and ask questions: Join the discussion
• 🤝 Want to help? Contributions are welcome!

---

📝 License

This project is licensed under the MIT License.

---

❤️ Acknowledgements

TiltSense is built with love using:

• ESPHome
• LVGL
• Tilt
• Community feedback and personal fermentation obsession 🧪🍻

Special thanks to Llupols for designing the TiltSense logo. Your creativity and talent have given our project a unique identity. Much appreciated!

---

🙌 Contribute

Pull requests are welcome! Fork the repo, improve the code or docs, and open a PR.
You can also contribute by sharing feedback or joining discussions.

---

📣 Stay tuned

More features, documentation, and exciting new hardware coming soon!