Advanced Customisation

The AL60 is designed with open standards in mind. While it works perfectly as a standalone clock, its true potential is revealed when you dive into its firmware and integration options. At its core, the AL60 uses a powerful ESP32 C3 microcontroller running firmware built with ESPHome.

Open Hardware and Software

We believe in the Right to Repair and the freedom to customise. Almost every aspect of the AL60's behaviour can be modified, from the way it renders the clock hands to the sounds its buzzer makes. You can:

• Modify the Firmware: Change the ESPHome YAML configuration to adjust existing features and preferences, or extend the C++ external component to add new features.
• Extend the Hardware: The internal I²C bus is accessible for adding additional sensors.

Warranty & Support

While NIX labs encourages exploration, modifying the hardware or firmware incorrectly can lead to unintended behaviour. Modifying the product does not automatically void the warranty; however, you may be required to return it to its factory state before technical or warranty support can be provided.

Safety First

Never attempt to modify the physical hardware whilst it is powered on.

Source Code Structure

The AL60's firmware is modular. It consists of a core ESPHome YAML configuration, additional package files, and a custom external component. You can find the full source code and additional documentation in the GitHub project.

• al60.yaml Main device configuration
• al60_factory.yaml Factory firmware configuration
• Directorycomponents/ring_clock/ Ring Clock external component

  • __init__.py
  • ring_clock.h
  • ring_clock.cpp
• Directorypackages/

  • al60_core.yaml ESP and Wi-Fi 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
• Directoryblueprints/ Templates for Home Assistant automations

  • …

The Ring_Clock Component

The ring_clock custom component is the core of the display. It handles the LED ring rendering logic, the system state machines, and low-level control of the hardware. Generally, this component would not be modified and instead additional functionality can be added via the YAML files.

Compiling Your Own Firmware

While the AL60 comes ready to use, you may wish to modify and compile the firmware yourself to unlock advanced customisations or manage the device entirely offline.

ESPHome Version Support

The AL60 firmware utilises custom components that may be sensitive to upstream changes in the ESPHome project. NIX labs provides support for the ESPHome version active at the time of our firmware release.

ESPHome Adoption

This method allows you to make small changes to the clock's configuration. It uses remote packages, meaning your clock will automatically pull the latest NIX labs features and fixes.

1. Ensure you have the ESPHome Device Builder installed and open your Dashboard.

2. Look for a new device card labelled al60 under the "Discovered" section. Click Adopt.

3. Give your device a permanent name and enter your Wi-Fi credentials.

4. ESPHome will perform an initial "Install." This links the device to your dashboard for future wireless (OTA) updates.

Manual Import

Choose this method for total control. By downloading the source files locally, you can modify the underlying YAML and ring_clock component, or build your firmware without an internet connection.

1. Clone the Repository: Obtain the source code from the GitHub project.

2. Move Files to ESPHome: Copy the relevant YAML and component files into your local ESPHome configuration directory.

3. Customise Substitutions: Modify the substitutions block in the YAML files as required.

4. Flash the Firmware: Use the ESPHome command line or dashboard to compile and install the firmware either wirelessly or via USB.

Adding Features

Full Radar Control

By default the AL60 uses the output pin of the radar sensor with a customisable cooldown period. You can enable extra features of the LD2410 radar sensor, including still and moving targets, by enabling the radar package. Further details about this component can be found on the ESPHome documentation site.

packages:
  ...
  # Uncomment this line
  radar: github://nix-labs/al60/packages/al60_radar.yaml@main

Bluetooth Proxy

To add Bluetooth functionality in Home Assistant add the following lines to your al60.yaml file:

esp32_ble_tracker:

bluetooth_proxy:
  active: true

External Temperature/Humidity Sensors

While the AL60 has its own integrated sensors, you can swap these with external temperature or humidity sensors and display those values instead.

# Add external home assistant sensors. Change entity_id to match your sensor.
sensor:
  - platform: homeassistant
    entity_id: sensor.my_temperature_sensor
    id: external_temperature
    internal: true
  - platform: homeassistant
    entity_id: sensor.my_humidity_sensor
    id: external_humidity
    internal: true

# Swap default sensors with external ones.
ring_clock:
  id: RingClock
  temperature_sensor: external_temperature
  humidity_sensor: external_humidity

Customise Sensor Display Colours

You can adjust the colours used for the temperature and humidity display by replacing the [red, green, blue] values with colours of your own selection.

ring_clock:
  id: RingClock
  # Sensor Color Ranges
  temperature_colors:
    - { value: -10.0, color: [26, 22, 73] }
    - { value: 0.0, color: [18, 94, 131] }
    - { value: 10.0, color: [60, 157, 116] }
    - { value: 20.0, color: [207, 216, 113] }
    - { value: 30.0, color: [223, 158, 60] }
    - { value: 40.0, color: [193, 59, 44] }
    - { value: 50.0, color: [136, 26, 23] }
  humidity_colors:
    - { value: 0.0, color: [190, 155, 47] }
    - { value: 30.0, color: [160, 195, 27] }
    - { value: 70.0, color: [60, 215, 127] }
    - { value: 100.0, color: [20, 95, 227] }