eigger / hass-gicisky

hass-gicisky Gicisky BLE Label Home Assistant Integration Gallery | Size | Example | |------|---------| | 2.1" (250x128) | | | 2.9" (296x128) | | | 10.2" (960x640) | | What Is an Electronic Label? An **Electronic Label** (also known as an **Electronic Shelf Label, ESL**) is a small display device that uses **electronic paper (e-paper)** instead of traditional paper. Once content is displayed, it remains visible **without consuming power**, making electronic labels extremely energy-efficient and well suited for always-on information display. This project uses electronic labels manufactured by **Gicisky**. Key Characteristics • 📄 **E-paper display** • Paper-like appearance with excellent readability • 🔋 **Ultra-low power consumption** • Power is only used when the display is updated • 📡 **Wireless communication** • Display content can be updated remotely • 📐 **Compact and lightweight** • Easy to mount on walls, shelves, doors, or devices Although electronic labels are commonly associated with retail price tags, their core value lies in being **small, persistent, and power-efficient displays**. Why Electronic Labels? Electronic labels are ideal for displaying information that: • Needs to be visible at all times • Does not change frequently • Must be shown in locations where continuous power is impractical This project focuses on these fundamental characteristics and explores electronic labels beyond their traditional use cases. 💬 Feedback & Support 🐞 Found a bug? Let us know via an Issue. 💡 Have a question or suggestion? Join the Discussion! --- Supported Models | Type | Size | Resolution | Colors | |------|------|------------|--------| | TFT | 2.1" | 250 × 132 | BW | | EPD | 2.1" | 250 × 128 | BWR | | EPD | 2.9" | 296 × 128 | BW | | EPD | 2.9" | 296 × 128 | BWR | | EPD | 2.9" | 296 × 128 | BWRY | | EPD | 3.7" | 240 × 416 | BWR | | EPD | 4.2" | 400 × 300 | BWR | | EPD | 7.5" | 800 × 480 | BWR | | EPD | 10.2" | 960 × 640 | BWR | Where to Buy • In my country, I can purchase from the official site linked below, but I am not sure if it is available for purchase in all countries. • AliExpress - Gicisky Official Store • AliExpress - Gicisky Official Store Installation • Install this integration with HACS (adding repository required), or copy the contents of this repository into the directory. • Restart Home Assistant. ⚠️ Important Notice • It is **strongly recommended to use a Bluetooth proxy instead of a built-in Bluetooth adapter**. Bluetooth proxies generally offer more stable connections and better range, especially in environments with multiple BLE devices. > [!TIP] > For hardware recommendations, refer to Great ESP32 Board for an ESPHome Bluetooth Proxy. • When using a Bluetooth proxy, it is strongly recommended to **keep the scan interval at its default value**. Changing these values may cause issues with Bluetooth data transmission. • **bluetooth_proxy:** must always have **active: true**. Example (recommended configuration with default values): Options After adding a device, you can configure the following options via **Settings > Devices & Services > Gicisky > Configure**: | Option | Default | Range | Description | |--------|---------|-------|-------------| | **Retry Count** | 3 | 1–10 | Number of retry attempts when BLE write fails | | **Write Delay (ms)** | 0 | 0–1000 | Delay in milliseconds between each BLE write operation | | **Prevent Duplicate Send** | false | true/false | If enabled, prevents sending the same image data consecutively to save battery and reduce traffic | > [!TIP] > If you experience frequent write failures, try increasing the **Retry Count**. > If writes are unstable, try setting **Write Delay** to 50–100 ms to give the device more time to process each packet. --- Service: Service Parameters | Parameter | Required | Default | Description | |-----------|----------|---------|-------------| | | ✅ | — | List of drawing elements (see Payload Element Types) | | | ❌ | | Image rotation: , , , | | | ❌ | | Background color: , , | | | ❌ | | Black binary threshold ( – ) | | | ❌ | | Red binary threshold ( – ) | | | ❌ | | Generate preview image without sending to device | Basic Usage Rotation & Background Dry Run (Preview Only) > Preview image is available via the **Camera** entity without sending data to the physical device. > [!TIP] > You can use the **Gicisky Payload Editor** to design a rough layout via drag-and-drop in your browser and automatically generate YAML. Use the generated YAML with to preview it without sending data to the actual device. --- Payload Element Examples > [!TIP] > All elements support the field ( / ) to conditionally show or hide them. > [!NOTE] > **Color values**: This is an **e-ink display** that only supports 4 colors: , , , . > HEX strings ( ) are accepted as a convenience but will be **automatically mapped to the nearest supported color**. text If is omitted the element stacks below the previous element automatically ( controls the gap, default ). multiline line If is omitted the line is drawn at the current auto-stack Y position ( offset). rectangle rectangle_pattern circle ellipse icon Uses Material Design Icons. You can use the icon name with or without the prefix. dlimg Supports **HTTP/HTTPS URLs**, **local file paths**, and **Base64 data URIs**. | | Description | |--------|-------------| | | Stretch to fill exactly (default) | | / | Scale preserving aspect ratio, pad with transparency | | | Scale and crop to fill exactly, no padding | qrcode barcode diagram plot Reads entity history from **Home Assistant Recorder**. progress_bar arc gauge polygon table text_box datamatrix --- Combined Example --- Payload Element Types > [!TIP] > All elements support the field ( / , default: ) to conditionally show or hide them. | **Type** | **Required Fields** | **Optional Fields** | **Description** | | --------------------- | ---------------------------------------------------…