From bf27321ccedb17d4da4e4baee79a75bcf72d060a Mon Sep 17 00:00:00 2001 From: webbrain-one <295484252+webbrain-one@users.noreply.github.com> Date: Wed, 5 Aug 2026 17:58:57 +0300 Subject: [PATCH 1/2] docs: add Spanish README --- README.es-ES.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 README.es-ES.md diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..76dcea9 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,200 @@ + + +# miband-bot + +Español | [English](README_EN.md) + +Bot de Telegram self-hosted y personal para datos de Xiaomi Fitness / Mi Band. + +Recoge los pasos, el sueño, el ritmo cardíaco, SpO2, estrés, actividad diaria, peso +y los entrenamientos desde la nube de Xiaomi Fitness, los almacena en una base de datos SQLite local +y permite acceder a ellos directamente desde Telegram — +sin servicios de terceros y sin transmitir datos a terceros. + +> **El proyecto está diseñado para un único propietario.** +> Este no es un bot público ni un servicio médico. + +## Funcionalidades + +- Visualización de los últimos pasos, sueño, ritmo cardíaco, SpO2, estrés, peso y entrenamientos en Telegram. +- Sincronización manual y automática programada. +- Actualización automática del mensaje principal fijado después de la sincronización en segundo plano. +- Almacenamiento del historial en SQLite (`data/`). +- Exportación de todas las tablas a un ZIP con archivos CSV directamente al chat. +- Implementación a través de Docker Compose. +- Escritura atómica del token de Xiaomi con permisos `0600`. +- Vinculación automática inteligente al primer usuario (lista blanca). + +## Cómo funciona + +```text +Mi Band → Xiaomi Fitness cloud → miband-bot → SQLite → Telegram / CSV +``` + +Docker Compose inicia dos procesos: + +- `tracker` — sincroniza periódicamente los datos desde Xiaomi Fitness; +- `fitness-bot` — gestiona el menú de Telegram, la sincronización manual y la exportación. + +Ambos procesos trabajan con el mismo directorio `./data`. La escritura concurrente +está evitada mediante un bloqueo de archivo (file lock). + +## Requisitos + +- Docker y Docker Compose (o Python 3.11+ instalado). +- Token de bot de Telegram de [@BotFather](https://t.me/BotFather). +- Cuenta de Xiaomi con datos de Xiaomi Fitness. + +## Inicio rápido + +### Método 1: Instalación sin fisuras con un clic (Recomendado) + +Si aún no tienes el proyecto en tu computadora, puedes descargarlo y configurarlo automáticamente con un solo comando en la terminal: + +- **macOS / Linux:** + ```sh + curl -fsSL https://raw.githubusercontent.com/iAlexeyRu/miband-bot/main/install.sh | bash + ``` +- **Windows (PowerShell):** + ```powershell + powershell -c "irm https://raw.githubusercontent.com/iAlexeyRu/miband-bot/main/install.ps1 | iex" + ``` + +¡El instalador creará automáticamente la carpeta `miband-bot`, descargará y extraerá los archivos del proyecto, verificará el entorno y ejecutará la configuración interactiva! +Volver a ejecutar este mismo comando de PowerShell en una instalación ya configurada actualizará los archivos e iniciará el bot inmediatamente sin volver a ingresar el token. + +--- + +### Método 2: Ejecución desde la carpeta descargada + +Si ya clonaste el repositorio con `git clone` o descargaste el archivo ZIP manualmente: + +- **macOS / Linux:** + ```sh + ./setup.sh + ``` +- **Windows:** + Ejecuta el archivo `setup.bat` con un doble clic o ejecuta lo siguiente en la consola: + ```cmd + setup.bat + ``` + +El script verificará automáticamente el entorno, te guiará paso a paso para obtener el token, creará la configuración `secrets.env`, instalará el entorno de Python (si se elige la ejecución sin Docker) y te ofrecerá iniciar el bot con un solo clic. +Después de la configuración, puedes reiniciar el bot usando `run_local.sh` en macOS/Linux o `run_local.bat` en Windows desde la carpeta `miband-bot`. + +--- + +### Método 3: Configuración completamente manual (manual setup): + +1. Copia la plantilla de configuración: + ```sh + cp secrets.env.example secrets.env + ``` +2. Indica tu `TELEGRAM_BOT_TOKEN` en el archivo `secrets.env`. Deja la variable `TELEGRAM_ALLOWED_USER_ID` **vacía** — el bot se vinculará automáticamente contigo en el primer inicio. +3. Inicia los contenedores de Docker: + ```sh + docker compose up -d --build + ``` +4. Abre a tu bot creado en Telegram y envíale el comando `/start` — el bot reconocerá tu cuenta, la vinculará como único propietario y comenzará la sincronización. + +## Configuración + +Todas las variables están en `secrets.env`: + +| Variable | Predeterminado | Descripción | +| -------------------------- | ------------ | --------------------------------------- | +| `TELEGRAM_BOT_TOKEN` | — | Token del bot de Telegram | +| `TELEGRAM_ALLOWED_USER_ID` | — | ID de usuario autorizado (déjalo vacío para vinculación automática) | +| `SYNC_INTERVAL` | `900` | Intervalo de sincronización en segundo plano, segundos | +| `QUERY_DURATION` | `2` | Profundidad de la consulta al sincronizar, días | +| `ENABLE_FDS_SLEEP_DETAILS` | `true` | Cargar datos detallados nocturnos de FDS | + +Las rutas de la base de datos y del estado están definidas en `compose.yaml`. Al ejecutar sin Docker +consulta `secrets.env.example`. + +## Archivos de datos + +Los archivos de ejecución se crean en `./data`: + +| Archivo | Contenido | +| ---------------------- | --------------------------------- | +| `token_.json` | Token de autenticación de Xiaomi (**secreto**) | +| `miband_.db` | Base de datos SQLite con datos de salud | +| `status_.json` | Último estado de sincronización | +| `allowed_user.id` | ID del propietario vinculado | +| `fitness_bot_state.db` | Estado interno del menú de Telegram | +| `sync_.lock` | Archivo de bloqueo de sincronización | + +`secrets.env`, `data/`, `*.db`, `token*.json` y `status*.json` +están agregados a `.gitignore` — no los commitees. + +## Comandos + +| Comando | Acción | +| --------- | ------------------------------------- | +| `/start` | Abrir el menú o iniciar el inicio de sesión de Xiaomi | +| `/sync` | Iniciar una sincronización manual | +| `/status` | Mostrar el estado de la base de datos local | + +## Desarrollo local + +```sh +python3 -m venv .venv +.venv/bin/pip install -r requirements-dev.txt -e mi-fitness-python +.venv/bin/python -m py_compile fitness_bot.py miband_sync.py \ + $(find miband_tracker -name '*.py' | sort) +.venv/bin/python -m pytest +.venv/bin/python -m pytest mi-fitness-python/tests/unit +.venv/bin/ruff check . +.venv/bin/python -m pip check +``` + +Puntos de entrada: + +```sh +python -u miband_sync.py # или: miband-sync +python -u fitness_bot.py # или: miband-fitness-bot +``` + +## Solución de problemas + +**El bot no responde** — verifica `TELEGRAM_BOT_TOKEN`, los registros (logs) y asegúrate de haber sido el primero en enviarle `/start` al bot para vincularlo. Si necesitas reiniciar al propietario vinculado, simplemente elimina el archivo `data/allowed_user.id` y envía `/start` nuevamente. + +```sh +docker compose logs -f fitness-bot +``` + +**Token no encontrado** — envía `/start` y completa el flujo de inicio de sesión de Xiaomi. + +**Token caducado** — inicia el inicio de sesión nuevamente desde el menú; el archivo antiguo +se puede eliminar desde `data/`. + +**Sin SpO2 o detalles de sueño** — asegúrate de que estos datos se muestren +en la propia aplicación Xiaomi Fitness. La disponibilidad depende del modelo +de la pulsera y de la configuración de compartición. + +**Después de una actualización de Xiaomi todo se rompió** — este es un riesgo esperado +al trabajar con una API no oficial. Revisa los issues y los logs, luego +actualiza el código o deshabilita temporalmente el módulo problemático. + +## Importante: ingeniería inversa y limitaciones + +`miband-bot` es un proyecto no oficial, no afiliado con Xiaomi, Zepp, +Huami o Telegram. + +El acceso a los datos se implementa mediante ingeniería inversa de APIs cerrados, +por lo tanto: + +- Xiaomi puede cambiar la API sin previo aviso; +- la autenticación o la sincronización pueden dejar de funcionar temporalmente; +- utiliza el proyecto solo con tus propias cuentas y datos; +- cumple con las leyes y los términos de uso de los servicios; +- los datos de la pulsera no constituyen un diagnóstico médico. + +## Licencia + +El proyecto se distribuye bajo la licencia [GNU GPL v3.0 o posterior](LICENSE). + +El SDK `mi-fitness-python` se incluye como una copia de código fuente vendored bajo +[GNU GPL v3.0](mi-fitness-python/LICENSE). Para más detalles, consulta +[VENDORED.md](VENDORED.md). From 273d2539e4d3f08f11ee5f8104ad380269734d7c Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 5 Aug 2026 18:14:49 +0300 Subject: [PATCH 2/2] docs: link Spanish README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4d17695..b2ad5ed 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # miband-bot -Русский | [English](README_EN.md) +Русский | [English](README_EN.md) | [Español](README.es-ES.md) Личный self-hosted Telegram-бот для данных Xiaomi Fitness / Mi Band.