# 🏷 Gicisky Python Library

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](ble/bleak.py) or implement the [BLE Interface](ble/interface.py)
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

```bash
pip install gicisky
```

Or install from source:

```bash
git clone https://git.massive.box/massivebox/gicisky
cd gicisky
pip install -r requirements.txt
```

## ▶️ Quick Start

Check out the [examples](examples)!

```bash
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** ([ble/](file:///home/massive/Dev/gicisky/ble/)): Handles Bluetooth Low Energy communication
2. **Core Protocol** ([core/](file:///home/massive/Dev/gicisky/core/)): Implements the Gicisky communication protocol, independent of the Bluetooth library
3. **Image Processing** ([image/](file:///home/massive/Dev/gicisky/image/)): `conversion` formats images to the Gicisky format, `optimizer` (optional) uses
dithering and letterboxing for better results
4. **Logging** ([logger/](file:///home/massive/Dev/gicisky/logger/)): Provides detailed logging capabilities

## 🧱 Requirements

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

Install all requirements:

```bash
pip install -r requirements.txt
```

## ❤️ Credits

- For much of the original work on the protocol: [atc1441/ATC_GICISKY_ESL](https://github.com/atc1441/ATC_GICISKY_ESL)
- For most of the advertisement parsing logic: [eigger/hass-gicisky](https://github.com/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](https://s.massive.box/donate). Thanks a lot!
- If you haven't bought your Gigisky ESL yet, please buy it through my [AliExpress affiliate link](https://s.click.aliexpress.com/e/_c2IOUkF5).
I will earn a small commission from your order, but it will not cost you anything. Thanks!

## 📚 License

MIT License