Component Library

ESPHome Swift includes a growing library of components for various sensors, actuators, and integrations. This page documents all available components and how to use them.

Sensor Components

Sensors are input devices that read values from the physical world.

DHT Temperature & Humidity

The DHT component supports DHT11, DHT22, and AM2302 temperature and humidity sensors.

sensor:
  - platform: dht
    pin:
      number: GPIO4
    model: DHT22              # DHT11, DHT22, or AM2302
    temperature:
      name: "Room Temperature"
    humidity:
      name: "Room Humidity"
    update_interval: 60s      # How often to read

Wiring:

Notes:

ADC (Analog to Digital Converter)

Read analog voltages using the ESP32’s built-in ADC.

sensor:
  - platform: adc
    pin:
      number: GPIO1          # ADC pins: GPIO0-7 on ESP32-C6
    name: "Battery Voltage"
    update_interval: 30s
    # Note: Advanced filtering is planned for future releases

ESP32-C6 ADC Pins:

Common Uses:

Switch Components

Switches are output devices that can be turned on or off.

GPIO Switch

Control digital outputs like relays, LEDs, or other devices.

switch:
  - platform: gpio
    pin:
      number: GPIO5
    name: "Relay Control"
    inverted: false          # true = active low
    restore_mode: RESTORE_DEFAULT_OFF
    # Note: Automation actions are planned for future releases

Restore Modes:

Common Uses:

Light Components

Lights are specialized outputs with brightness and color control.

Binary Light

Simple on/off light control.

light:
  - platform: binary
    pin:
      number: GPIO2
    name: "Status LED"
    # Note: Light effects are planned for future releases

RGB Light

Full color control with red, green, and blue channels.

light:
  - platform: rgb
    red_pin:
      number: GPIO6
    green_pin:
      number: GPIO7
    blue_pin:
      number: GPIO8
    name: "RGB Strip"
    # Note: Light effects are planned for future releases

RGBW Light (with white channel):

light:
  - platform: rgb
    red_pin:
      number: GPIO6
    green_pin:
      number: GPIO7
    blue_pin:
      number: GPIO8
    white_pin:
      number: GPIO9
    name: "RGBW Strip"

PWM Frequency:

Binary Sensor Components

Binary sensors detect on/off states like buttons, motion, or contact.

GPIO Binary Sensor

Read digital inputs from switches, buttons, or digital sensors.

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO3
      mode: INPUT_PULLUP
      inverted: true         # true for active-low
    name: "Push Button"
    device_class: button
    # Note: Advanced filtering and automation actions are planned for future releases

Common Device Classes:

Planned Advanced Features

Note: The following features are planned for future releases:

Component Actions & Automations

Advanced Filtering

Light Effects

Creating Custom Components

To add a new component type to ESPHome Swift:

1. Create Component Factory

// Sources/ComponentLibrary/Sensors/MySensor.swift
import Foundation
import ESPHomeSwiftCore

public class MySensorFactory: ComponentFactory {
    public let platform = "my_sensor"
    public let componentType = ComponentType.sensor
    public let requiredProperties = ["pin", "type"]
    public let optionalProperties = ["name", "update_interval"]
    
    public func validate(config: ComponentConfig) throws {
        // Validate configuration
    }
    
    public func generateCode(
        config: ComponentConfig, 
        context: CodeGenerationContext
    ) throws -> ComponentCode {
        // Generate C++ code
        return ComponentCode(
            headerIncludes: ["#include \"my_sensor.h\""],
            globalDeclarations: ["MySensor sensor;"],
            setupCode: ["sensor.begin();"],
            loopCode: ["sensor.update();"]
        )
    }
}

2. Register Component

// In ComponentLibrary.swift
private func registerBuiltInComponents() {
    // ... existing components ...
    register(MySensorFactory())
}

3. Add Tests

// Tests/ComponentLibraryTests/MySensorTests.swift
import XCTest
@testable import ComponentLibrary

final class MySensorTests: XCTestCase {
    func testMySensorValidation() throws {
        // Test component validation
    }
    
    func testMySensorCodeGeneration() throws {
        // Test code generation
    }
}

Component Roadmap

In Development

Planned

Contributing Components

We welcome contributions! To add a new component:

  1. Check existing issues for requests
  2. Discuss your component idea in discussions
  3. Follow the Contributing Guide
  4. Submit a pull request with:
    • Component implementation
    • Tests
    • Documentation
    • Example configuration

Component Best Practices

  1. Validation - Thoroughly validate configurations
  2. Error Handling - Provide clear error messages
  3. Documentation - Include wiring diagrams and examples
  4. Testing - Test on actual hardware
  5. Compatibility - Note board-specific limitations
  6. Performance - Consider power consumption and timing