20260326

esphome/custom_component/nixie_display/EXAMPLE_USAGE.md

@@ -0,0 +1,91 @@
+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