🏷 Gicisky Python Library

🐍 PyPi Page - 📄 Source code

A Python library for interacting with Gicisky electronic ink display tags via Bluetooth Low Energy (BLE).

ℹ️ Features

• Advertisement parsing: Discover compatible devices and get their info (battery level, model, hardware and software version)
• Image uploading: Upload images to your ESL, with all the features it supports (including third color and compression!)
• Bluetooth library independent: Use the provided Bleak backend or implement the BLE Interface to use any other Bluetooth library.
• Image conversion: Provide any image and let the library convert it for you to the device's format.

📱 Supported Devices

• EPD 2.1" BWR (0x0B)
• EPD 2.9" BWR (0x33)
• EPD 4.2" BWR (0x4B)
• EPD 7.5" BWR (0x2B)
• TFT 2.1" BW (0xA0)

⬇️ Installation

pip install gicisky

Or install from source:

git clone https://git.boxo.cc/massivebox/gicisky
cd gicisky
pip install -r requirements.txt

▶️ Quick Start

Check out the examples!

python3 examples/send_bleak.py ~/path/to/image.png
python3 examples/send_bleak.py --no-optimize ~/path/to/image.png # Without dithering

⚙️ Components

1. BLE Interface (gicisky.ble/): Handles Bluetooth Low Energy communication
2. Core Protocol (gicisky.core/): Implements the Gicisky communication protocol, independent of the Bluetooth library
3. Image Processing (gicisky.image/): conversion formats images to the Gicisky format, optimizer (optional) uses dithering and letterboxing for better results
4. Logging (gicisky.logger/): Provides detailed logging capabilities

⚠️ Version 0.2.0 Migration Guide

Breaking Change: Starting with version 0.2.0, all components are now under the gicisky namespace to prevent conflicts with other packages.

Import Changes

Before (v0.1.x):

from ble.bleak import BleakBackend
from core.advertisement import parse_advertisement
from image import optimize

After (v0.2.0+):

from gicisky.ble import BleakBackend
from gicisky.core import parse_advertisement
from gicisky.image import optimize

Quick Import

For convenience, you can still use star imports to access all public APIs:

from gicisky import *  # Imports: BleakBackend, parse_advertisement, optimize, etc.

🧱 Requirements

• Python 3.7+
• bleak (for BLE communication)
• PIL/Pillow (for image processing)
• numpy (for image manipulation)

Install all requirements:

pip install -r requirements.txt

❤️ Credits

• For much of the original work on the protocol: atc1441/ATC_GICISKY_ESL
• For most of the advertisement parsing logic: eigger/hass-gicisky

🤝 Support the Project

Thanks for your interest in supporting the project.

• Help me by opening issues and creating pull requests: all contributions are welcome!
• If you want to contribute financially, take a look here. Thanks a lot!
• If you haven't bought your Gigisky ESL yet, please buy it through my AliExpress affiliate link. I will earn a small commission from your order, but it will not cost you anything. Thanks!

📚 License

MIT License