EXAMPLE_USAGE.md

# ESPHome Nixie Tube Display Component

This is a custom ESPHome component for controlling a 6-digit nixie tube display with SPI interface.

## Installation

1. Copy the `esphome_component` folder to your ESPHome custom components directory:
   ```
   ~/.esphome/custom_components/nixie_display/
   ```

2. The component should have:
   - `__init__.py` - Component configuration
   - `nixie_display.h` - Header file
   - `nixie_display.cpp` - Implementation

## Configuration

Add to your ESPHome YAML:

```yaml
spi:
  id: nixie_spi
  clk_pin: GPIO18
  mosi_pin: GPIO23
  miso_pin: GPIO19

display:
  - platform: nixie_display
    id: nixie
    spi_id: nixie_spi
    anode0_pin: GPIO5
    anode1_pin: GPIO13
    anode2_pin: GPIO17
    le_pin: GPIO22
    
    # Lambda to update display with time
    lambda: |-
      it.display_text("000000");  // Display as string of 6 digits

text_sensor:
  - platform: homeassistant
    id: time_display
    entity_id: sensor.time
```

## Features

- **6 Nixie Tubes**: Organized as 3 anode sets of 2 tubes each
- **SPI Control**: Fast serial interface for cathode control
- **Anti-poisoning**: Implements digit cycling to prevent cathode poisoning
- **Text Display**: Can display any 6-character string of digits
- **60 Hz Refresh Rate**: Smooth flicker-free display

## Pin Configuration

- `anode0_pin`: Controls first tube pair (digits 0-1)
- `anode1_pin`: Controls second tube pair (digits 2-3)
- `anode2_pin`: Controls third tube pair (digits 4-5)
- `le_pin`: Latch Enable pin for SPI data locking
- SPI pins: CLK, MOSI, MISO (configured via SPI component)

## Display Format

The display expects a 6-character string of digits (0-9):
- Position 0-1: First anode set
- Position 2-3: Second anode set
- Position 4-5: Third anode set

## Usage Example

```yaml
lambda: |-
  // Display current time
  auto time_obj = id(homeassistant_time).now();
  if (time_obj.is_valid()) {
    char buf[7];
    snprintf(buf, sizeof(buf), "%02d%02d%02d", 
             time_obj.hour, time_obj.minute, time_obj.second);
    it.display_text(buf);
  }
```

## Anti-Poisoning Feature

Automatically enabled during transitions to cycle through digit values and prevent cathode poisoning that occurs with static displays. The algorithm:
1. Cycles all digits for 10 iterations
2. Then incrementally changes digits to target values
3. Total cycle takes ~20 iterations at the refresh rate