{"id":21332143,"url":"https://github.com/mathoudebine/homeassistant-timebox-mini","last_synced_at":"2025-07-12T10:31:14.766Z","repository":{"id":42691137,"uuid":"371674748","full_name":"mathoudebine/homeassistant-timebox-mini","owner":"mathoudebine","description":"Control your Divoom Timebox Mini from Home Assistant","archived":false,"fork":false,"pushed_at":"2023-01-03T12:08:48.000Z","size":720,"stargazers_count":14,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2023-03-06T21:12:12.337Z","etag":null,"topics":["bluetooth","divoom","hacs","hacs-integration","home-assistant","homeassistant","service","timebox","timebox-mini"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathoudebine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-28T11:12:44.000Z","updated_at":"2022-11-10T16:24:52.000Z","dependencies_parsed_at":"2023-02-01T06:01:27.207Z","dependency_job_id":null,"html_url":"https://github.com/mathoudebine/homeassistant-timebox-mini","commit_stats":null,"previous_names":[],"tags_count":null,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathoudebine%2Fhomeassistant-timebox-mini","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathoudebine%2Fhomeassistant-timebox-mini/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathoudebine%2Fhomeassistant-timebox-mini/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathoudebine%2Fhomeassistant-timebox-mini/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathoudebine","download_url":"https://codeload.github.com/mathoudebine/homeassistant-timebox-mini/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225814888,"owners_count":17528295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","divoom","hacs","hacs-integration","home-assistant","homeassistant","service","timebox","timebox-mini"],"created_at":"2024-11-21T22:46:06.588Z","updated_at":"2024-11-21T22:46:07.143Z","avatar_url":"https://github.com/mathoudebine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# homeassistant-timebox-mini\n[![hacs_badge](https://img.shields.io/badge/custom%20repository%20for-HACS-%2303a9f4.svg?style=flat-square\u0026logo=homeassistant\u0026logoColor=white)](https://hacs.xyz/) ![hacs_badge](https://img.shields.io/github/languages/top/mathoudebine/homeassistant-timebox-mini?style=flat-square)\n\nDivoom Timebox Mini custom service component for Home Assistant.\n\nTimebox protocol extracted from [ScR4tCh/timebox](https://github.com/ScR4tCh/timebox)\n\n### Table of content\n* [Limitations](#limitations)\n* [Requirements](#requirements)\n  * [Requirements](#bluetooth-hardware)\n  * [Home Assistant installation](#home-assistant-installation)\n* [Setup instructions](#setup-instructions)\n  * [Copying into custom_components folder](#copying-into-custom_components-folder)\n  * [Enabling the custom_component](#enabling-the-custom_component)\n* [Troubleshooting](#troubleshooting)\n* [Create your own picture / animation](#create-your-own-picture--animation)\n  * [Picture](#picture)\n  * [Animation](#animation)\n* [TODO](#todo)\n    \nThe Divoom Timebox Mini is a Bluetooth speaker with a 11x11 RGB LED matrix.\n\n![Timebox Mini](https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini.jpg)\n\nThis component allow to run the following actions on your Timebox Mini from a HomeAssistant service:\n- Set the clock automatically from your system clock\n- Display the clock\n- Set the audio volume level\n- Set the LED brightness level\n- Display the weather information (you have to use Divoom phone app to send weather info to your timebox)\n- Display a picture/animation from predefined choices (see [matrices](custom_components/timebox_mini/matrices) and [animations](custom_components/timebox_mini/animations) folders) :\n\n\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-homeassistant.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-hourglass.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-locked.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-unlocked.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-small-bell.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-green-check.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-red-cross.png\" width=\"200\"/\u003e\u003cimg src=\"https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/timebox-mini-orange-warning.png\" width=\"200\"/\u003e\n\n## Limitations\nThis service cannot be used to control multiple Divoom devices from one HomeAssistant instance:\n\nTo display custom content, a Bluetooth connection has to be established between the computer and your Divoom speaker when calling the service for the first time.\n\nIf you try to control another Divoom device, the connection to the first device will be stopped and the device will display a blinking \"Bluetooth\" symbol trying to reconnect. This is a Divoom limitation.\n\n## Requirements\n### Bluetooth Hardware\nThis component uses Python sockets for Bluetooth communication.\n\nAny Bluetooth hardware supported by your operating system should work. The Bluetooth interface of the Raspberry Pi 3/4 probably works, but hasn't been tested yet.  \n**Check that your hardware is not listed as \"unsupported\" here: https://www.home-assistant.io/integrations/bluetooth/**  \n\nTo check if your Bluetooth hardware is supported, run the following command on your system:\n```bash\n\u003e$ hcitool dev\nDevices:\n\thci0\t4C:79:6E:B2:0B:00\n```\nor\n```\n\u003e$ bluetoothctl\n[bluetooth]# list\n  Controller 4C:79:6E:B2:0B:00 [default]\n```\nYour Bluetooth interface should be listed. If you have more than one, this component will use the first one or the one listed as default.\n\n### Home Assistant installation\nAny Home assistant installation should be supported: OS, Container, Core, Supervised.\n\nIf you run Home Assistant in a virtual machine, you have to connect your computer Bluetooth hardware to the VM:\n- On VMWare: VM \u003e Removable devices \u003e (Your Bluetooth device i.e. Intel Wireless Bluetooth) \u003e Connect\n- On VirtualBox: Devices \u003e USB devices \u003e (Your Bluetooth device i.e. Intel Wireless Bluetooth)\n\n## Setup instructions\n\n### Automatic: add repository to HACS\n1. Make sure [HACS](https://hacs.xyz/) is installed.  \n2. Go to HACS \u003e Frontend \u003e Three dots \u003e Custom repositories  \n3. Add `https://github.com/mathoudebine/homeassistant-timebox-mini` as a custom repository (category: integration)  \n4. Install \"Timebox Mini service\" that appeared in your Integrations tab  \n\n### Manual: Copying into custom_components folder\nCreate a directory `custom_components` in your Home-Assistant configuration directory.\nCopy the whole [custom_components/timebox_mini](custom_components/timebox_mini) folder from this project into the newly created directory `custom_components`.\n\nThe result of your copy action(s) should yield a directory structure like so:\n\n```\nhomeassistant/\n|-- custom_components/\n|   |-- timebox_mini/\n|       |-- animations/*.gif\n|       |-- matrices/*.png\n|       |-- __init__.py\n|       |-- manifest.json\n|       |-- services.yaml\n```\n\n### Enabling the custom_component\nIn order to enable this custom device_tracker component, add this code snippet to your Home-Assistant `configuration.yaml` file:\n\n```yaml\ntimebox_mini:\n```\nAfter restart, the `timebox_mini.action` service will be available. You only need the MAC address of your Timebox.\n![Timebox Mini Service](https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/service.png)\n\nWhen you run an action that changes what is displayed on the Timebox, an entity will be created to save the current displayed state.\n\n![Timebox Mini entity](https://raw.githubusercontent.com/mathoudebine/homeassistant-timebox-mini/main/res/entity.png)\n\nPlease note that if you change the content on your Timebox without using the service (i.e. mobile app) this entity will not be updated.\n\n## Troubleshooting\nIf the actions are not applied to your Timebox when calling the service, you may need to pair manually with your device first using your OS Bluetooth settings or bluetoothctl:\n```\n[bluetooth]# list     \n  --\u003e Check that you have only one dongle listed\n[bluetooth]# select [MAC address of your dongle]\n[bluetooth]# power on\n[bluetooth]# scan on\n[bluetooth]# pair [your Timebox MAC address]\n[bluetooth]# connect [your Timebox MAC address]\n[bluetooth]# scan off\n```\nIf calling the service still does not work, check  Home Assistant logs. If you have the following errors:\n```\n[custom_components.timebox_mini] Error connecting to 11:75:58:A6:00:00 : [Errno 16] Resource busy\n[custom_components.timebox_mini] Error connecting to 11:75:58:A6:00:00 : [Errno 112] Host is down\n```\nyou need to reset your dongle and pair with the Timebox again:\n```\n[bluetooth]# list     \n  --\u003e Check that you have only one dongle listed\n[bluetooth]# select [MAC address of your dongle]\n[bluetooth]# scan off\n[bluetooth]# disconnect [your Timebox MAC address]\n  --\u003e ignore if error\n[bluetooth]# remove [your Timebox MAC address]\n  --\u003e ignore if error\n[bluetooth]# power off\n  --\u003e should display \"Changing power off succeeded\"\n[bluetooth]# power on\n[bluetooth]# scan on\n[bluetooth]# pair [your Timebox MAC address]\n[bluetooth]# connect [your Timebox MAC address]\n[bluetooth]# scan off\n```\n\n## Create your own picture / animation\n### Picture\nYou can create your own pixel-art matrix by using [PixilArt online tool](https://www.pixilart.com/draw).\n- Start with a blank canvas of 11 x 11 \n- Once finished, go to File \u003e Download and download your .png\n\nCopy the .png to the [matrices](custom_components/timebox_mini/matrices) folder and add its name to [services.yaml](custom_components/timebox_mini/services.yaml) in the `image` selector options. Restart HomeAssistant to take effect.\n\nNOTE : the Timebox has a limited color set and cannot display all RGB shades, some color from your matrix will be approximated to the nearest one supported by Timebox.\n\n### Animation\nYou can create a .gif for your animation using [EzGif Maker online tool](https://ezgif.com/maker). Start by loading all the matrices for your .gif that you have created previously (see above).\n\n- Set the same delay for all frames. Timebox does not support different frame delays : if you want a frame to appear longer, duplicate it (use \"copy\" button).\n- Min. delay is 200ms (`delay:20`), Timebox cannot display frames faster.\n- Check `use global colormap`\n- Click `Make a gif!` then click `Save` icon on the far right\n\nCopy the .gif to the [animations](custom_components/timebox_mini/animations) folder and add its name to [services.yaml](custom_components/timebox_mini/services.yaml) in the `animation` selector options. Restart HomeAssistant to take effect.\n\n## TODO\n- Specify which bluetooth adapter to use (to have multiple Timebox, one per adapter)\n- Weather info setting\n- [Moving text](https://github.com/DaveDavenport/timebox/blob/master/examples/movingtext.py)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathoudebine%2Fhomeassistant-timebox-mini","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathoudebine%2Fhomeassistant-timebox-mini","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathoudebine%2Fhomeassistant-timebox-mini/lists"}