Firmware & Source Code

The AL60's firmware is modular and organized into high-level YAML packages and core C++ components. This structure makes it easy to add your own logic while maintaining the core functionality.

Source Code Structure

You can find the source code in the al60-firmware directory of your distribution. The structure is as follows:

al60-firmware/
├── al60.yaml # Main device configuration
├── al60_factory.yaml # Factory reset defaults
├── packages/ # Modular YAML components
│ ├── al60_core.yaml # ESP32 and WiFi setup
│ ├── al60_inputs.yaml # Button and mode logic
│ ├── al60_light.yaml # LED ring and effect definitions
│ ├── al60_sensors.yaml # Environmental and motion sensor setup
│ └── al60_time.yaml # SNTP and RTC management
└── components/ # Custom C++ logic
└── ring_clock/ # The core RingClock library

Custom ESPHome Component: ring_clock

The most critical part of the AL60 is the ring_clock custom component. This library handles:

• Dual Ring Rendering: Mapping 108 LEDs into two concentric rings.
• State Machine: Managing the transitions between time, timer, stopwatch, and sensory modes.
• Physics-based Fading: Smooth animation logic for "Hands".

Modifying the Ring Logic

If you wish to change how the clock hands are rendered, you can modify the render_time function in ring_clock.cpp. The hardware layout is constant:

• Ring 1 (Outer): LEDs 0-59 (Minutes/Seconds)
• Ring 2 (Inner): LEDs 60-107 (Hours/Markers)

Compiling Your Own Firmware

If you have ESPHome installed on your computer, you can compile and flash your own version of the firmware:

1. Navigate to the al60-firmware directory.

2. Edit al60.yaml or any of the linked packages to suit your needs.

3. Run the following command to compile:

   esphome compile al60.yaml

4. Once compiled, you can flash it via USB-C or OTA (Over-The-Air) using:

   esphome upload al60.yaml

Home Assistant Templates

Because the AL60 uses ESPHome, you can add your own Home Assistant templates directly to the YAML configuration. This is perfect for displaying custom data (like energy prices or your next calendar event) as a unique LED effect on the clock.

[!TIP] Use the notification_color dummy light in al60_light.yaml to trigger custom animations from Home Assistant.