mirror of
https://github.com/alexgetmancom/miband-bot.git
synced 2026-09-05 18:16:18 +03:00
docs: add Spanish README
This commit is contained in:
webbrain-one
+200
@@ -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_<id>.json` | Token de autenticación de Xiaomi (**secreto**) |
|
||||||
|
| `miband_<id>.db` | Base de datos SQLite con datos de salud |
|
||||||
|
| `status_<id>.json` | Último estado de sincronización |
|
||||||
|
| `allowed_user.id` | ID del propietario vinculado |
|
||||||
|
| `fitness_bot_state.db` | Estado interno del menú de Telegram |
|
||||||
|
| `sync_<id>.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).
|
||||||
Reference in New Issue
Block a user